paulmataruso/Palmr
1
0
Fork 0
mirror of https://github.com/kyantech/Palmr.git synced 2025-10-23 06:11:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add PRESIGNED_URL_EXPIRATION configuration option

Browse Source 
- Introduced the PRESIGNED_URL_EXPIRATION environment variable across multiple configuration files to allow users to customize the expiration time for presigned URLs.
- Updated documentation to include details on the new variable, its default value, and guidance on choosing appropriate expiration times based on security and usability needs.
- Refactored relevant code to utilize the new configuration option for generating presigned URLs in the file and reverse share services.
This commit is contained in:
Daniel Luiz Alves
2025-08-19 09:18:52 -03:00
parent 0f22b0bb23
commit aecda25b25
10 changed files with 157 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
apps/docs/content/docs/3.1-beta/quick-start.mdx
View File

@@ -69,6 +69,7 @@ Choose your storage method based on your needs:
# - PALMR_GID=1000 # GID for the container processes (default is 1000)
# - SECURE_SITE=false # Set to true if you are using a reverse proxy
# - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
# - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (optional, defaults to 3600 seconds / 1 hour)
volumes:
- palmr_data:/app/server
@@ -116,6 +117,7 @@ Choose your storage method based on your needs:
# - PALMR_GID=1000 # GID for the container processes (default is 1000)
# - SECURE_SITE=false # Set to true if you are using a reverse proxy
# - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
# - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (optional, defaults to 3600 seconds / 1 hour)
volumes:
- ./data:/app/server
```
@@ -251,6 +253,40 @@ Prefer Docker commands over Compose? Here are the equivalent commands:
---
## Common Configuration Options
### Presigned URL Expiration
Palmr. uses temporary URLs (presigned URLs) for secure file access. These URLs expire after a configurable time period to enhance security.
**Default:** 1 hour (3600 seconds)
You can customize this for all storage types (filesystem or S3) by adding:
```yaml
environment:
- PRESIGNED_URL_EXPIRATION=7200 # 2 hours
```
**When to adjust:**
- **Shorter time (1800 = 30 min):** Higher security, but users may need to refresh download links
- **Longer time (7200-21600 = 2-6 hours):** Better for large file transfers, but URLs stay valid longer
- **Default (3600 = 1 hour):** Good balance for most use cases
### File Encryption
For filesystem storage, you can enable file encryption:
```yaml
environment:
- DISABLE_FILESYSTEM_ENCRYPTION=false
- ENCRYPTION_KEY=your-secure-32-character-key-here
```
**Note:** S3 storage handles encryption through your S3 provider's encryption features.
---
## Maintenance
### Updates

121
apps/docs/content/docs/3.1-beta/s3-providers.mdx
View File

@@ -7,6 +7,8 @@ This guide provides comprehensive configuration instructions for integrating Pal
> **Overview:** Palmr. supports any S3-compatible storage provider, giving you flexibility to choose the solution that best fits your needs and budget.
> **Note:** Some configuration options (like presigned URL expiration) apply to **all storage types**, including filesystem storage. These are marked accordingly in the documentation.
## When to use S3-compatible storage
Consider using S3-compatible storage when you need:
@@ -19,19 +21,27 @@ Consider using S3-compatible storage when you need:
## Environment variables
### General configuration (applies to all storage types)
| Variable | Description | Required | Default |
| -------------------------- | ------------------------------------------------ | -------- | --------------- |
| `PRESIGNED_URL_EXPIRATION` | Duration in seconds for presigned URL expiration | No | `3600` (1 hour) |
### S3-specific configuration
To enable S3-compatible storage, set `ENABLE_S3=true` and configure the following environment variables:
| Variable | Description | Required | Default |
| ----------------------- | ------------------------------------- | -------- | ----------------- |
| `S3_ENDPOINT` | S3 provider endpoint URL | Yes | - |
| `S3_PORT` | Connection port | No | Based on protocol |
| `S3_USE_SSL` | Enable SSL/TLS encryption | Yes | `true` |
| `S3_ACCESS_KEY` | Access key for authentication | Yes | - |
| `S3_SECRET_KEY` | Secret key for authentication | Yes | - |
| `S3_REGION` | Storage region | Yes | - |
| `S3_BUCKET_NAME` | Bucket/container name | Yes | - |
| `S3_FORCE_PATH_STYLE` | Use path-style URLs | No | `false` |
| `S3_REJECT_UNAUTHORIZED`| Enable strict SSL certificate validation | No | `true` |
| Variable | Description | Required | Default |
| ------------------------ | ---------------------------------------- | -------- | ----------------- |
| `S3_ENDPOINT` | S3 provider endpoint URL | Yes | - |
| `S3_PORT` | Connection port | No | Based on protocol |
| `S3_USE_SSL` | Enable SSL/TLS encryption | Yes | `true` |
| `S3_ACCESS_KEY` | Access key for authentication | Yes | - |
| `S3_SECRET_KEY` | Secret key for authentication | Yes | - |
| `S3_REGION` | Storage region | Yes | - |
| `S3_BUCKET_NAME` | Bucket/container name | Yes | - |
| `S3_FORCE_PATH_STYLE` | Use path-style URLs | No | `false` |
| `S3_REJECT_UNAUTHORIZED` | Enable strict SSL certificate validation | No | `true` |
## Provider configurations
@@ -52,6 +62,7 @@ S3_SECRET_KEY=your-secret-access-key
S3_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name
S3_FORCE_PATH_STYLE=false
# PRESIGNED_URL_EXPIRATION=3600 # Optional: 1 hour (default)
```
**Getting credentials:**
@@ -153,6 +164,7 @@ S3_SECRET_KEY=your-application-key
S3_REGION=us-west-002
S3_BUCKET_NAME=your-bucket-name
S3_FORCE_PATH_STYLE=false
# PRESIGNED_URL_EXPIRATION=7200 # Optional: 2 hours for large files
```
**Cost advantage:**
@@ -203,6 +215,93 @@ S3_FORCE_PATH_STYLE=false
- Use container name as bucket name
- Configure appropriate access policies
## Presigned URL configuration
Palmr. uses presigned URLs to provide secure, temporary access to files stored in **both S3-compatible storage and filesystem storage**. These URLs have a configurable expiration time to balance security and usability.
> **Note:** This configuration applies to **all storage types** (S3, filesystem, etc.), not just S3-compatible storage.
### Understanding presigned URLs
Presigned URLs are temporary URLs that allow direct access to files without exposing storage credentials or requiring authentication. They automatically expire after a specified time period, enhancing security by limiting access duration.
**How it works:**
- **S3 Storage:** URLs are signed by AWS/S3-compatible provider credentials
- **Filesystem Storage:** URLs use temporary tokens that are validated by Palmr server
**Default behavior:**
- Upload URLs: 1 hour (3600 seconds)
- Download URLs: 1 hour (3600 seconds)
### Configuring expiration time
You can customize the expiration time using the `PRESIGNED_URL_EXPIRATION` environment variable:
```bash
# Set URLs to expire after 2 hours (7200 seconds)
PRESIGNED_URL_EXPIRATION=7200
# Set URLs to expire after 30 minutes (1800 seconds)
PRESIGNED_URL_EXPIRATION=1800
# Set URLs to expire after 6 hours (21600 seconds)
PRESIGNED_URL_EXPIRATION=21600
```
### Choosing the right expiration time
**Shorter expiration (15-30 minutes):**
- [+] Higher security
- [+] Reduced risk of unauthorized access
- [-] May interrupt long uploads/downloads
- [-] Users may need to refresh links more often
**Longer expiration (2-6 hours):**
- [+] Better user experience for large files
- [+] Fewer interruptions during transfers
- [-] Longer exposure window if URLs are compromised
- [-] Potential for increased storage costs if users leave downloads incomplete
**Recommended settings:**
- **High security environments:** 1800 seconds (30 minutes)
- **Standard usage:** 3600 seconds (1 hour) - default
- **Large file transfers:** 7200-21600 seconds (2-6 hours)
### Example configurations
**For Backblaze B2 with extended expiration:**
```bash
ENABLE_S3=true
S3_ENDPOINT=s3.us-west-002.backblazeb2.com
S3_USE_SSL=true
S3_ACCESS_KEY=your-key-id
S3_SECRET_KEY=your-application-key
S3_REGION=us-west-002
S3_BUCKET_NAME=your-bucket-name
S3_FORCE_PATH_STYLE=false
PRESIGNED_URL_EXPIRATION=7200 # 2 hours for large file transfers
```
**For high-security environments:**
```bash
ENABLE_S3=true
S3_ENDPOINT=s3.amazonaws.com
S3_USE_SSL=true
S3_ACCESS_KEY=your-access-key-id
S3_SECRET_KEY=your-secret-access-key
S3_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name
S3_FORCE_PATH_STYLE=false
PRESIGNED_URL_EXPIRATION=1800 # 30 minutes for enhanced security
```
## Configuration best practices
### Security considerations