Security Configuration

Zipline includes several security features to protect your instance from abuse and ensure safe operation.

Core Security Settings

Secret Key

CORE_SECRET

string

required

The master secret key used for session encryption, token generation, and other cryptographic operations.Requirements:

Minimum 32 characters
Must not be the default value “changethis”
Should be cryptographically random

# Generate a secure secret
CORE_SECRET=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32)

The CORE_SECRET is critical for security. If compromised, attackers can:

Forge session tokens
Impersonate users
Access protected resources

Never commit this value to version control or share it publicly.

Proxy Trust

CORE_TRUST_PROXY

boolean

default:"false"

Trust proxy headers for client IP address detection.

CORE_TRUST_PROXY=true

Enable this when Zipline is behind a reverse proxy (Nginx, Apache, Cloudflare, etc.) to:

Correctly identify client IP addresses from X-Forwarded-For header
Respect X-Forwarded-Proto for HTTPS detection
Enable accurate rate limiting by IP
Properly log client addresses

When to enable:

Behind Nginx, Apache, Caddy, or similar reverse proxy
Using Cloudflare or other CDN
In containerized environments with ingress controllers

When to keep disabled:

Direct exposure to the internet
When you don’t have a trusted proxy layer

Reverse Proxy Configuration Examples

Nginx

location / {
  proxy_pass http://localhost:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

Set CORE_TRUST_PROXY=true in Zipline.

Caddy

zipline.example.com {
  reverse_proxy localhost:3000
}

Caddy automatically sets proper headers. Set CORE_TRUST_PROXY=true.

Apache

<VirtualHost *:443>
  ServerName zipline.example.com
  
  ProxyPreserveHost On
  ProxyPass / http://localhost:3000/
  ProxyPassReverse / http://localhost:3000/
  
  RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>

Set CORE_TRUST_PROXY=true in Zipline.

Rate Limiting

Protect your instance from abuse with built-in rate limiting.

RATELIMIT_ENABLED

boolean

default:"true"

Enable rate limiting globally.

RATELIMIT_ENABLED=true

RATELIMIT_MAX

number

default:"10"

Maximum number of requests allowed per window.

RATELIMIT_MAX=10

RATELIMIT_WINDOW

number

default:"null"

Time window in milliseconds. If not set, uses a default window.

RATELIMIT_WINDOW=60000  # 1 minute

RATELIMIT_ADMIN_BYPASS

boolean

default:"true"

Allow administrators to bypass rate limits.

RATELIMIT_ADMIN_BYPASS=true

RATELIMIT_ALLOW_LIST

string[]

default:"[]"

Comma-separated list of IP addresses or CIDR ranges exempt from rate limiting.

RATELIMIT_ALLOW_LIST=127.0.0.1,192.168.1.0/24,10.0.0.5

Rate Limit Examples

# 5 requests per minute
RATELIMIT_ENABLED=true
RATELIMIT_MAX=5
RATELIMIT_WINDOW=60000
RATELIMIT_ADMIN_BYPASS=true

Rate limiting is applied per IP address. With CORE_TRUST_PROXY=true, the client’s real IP from proxy headers is used.

File Security

Extension Blocking

FILES_DISABLED_EXTENSIONS

string[]

default:"[]"

Block uploads of files with specific extensions.

FILES_DISABLED_EXTENSIONS=exe,bat,cmd,sh,ps1

Common security-focused configurations:

# Block executables
FILES_DISABLED_EXTENSIONS=exe,bat,cmd,com,msi,scr

# Block scripts
FILES_DISABLED_EXTENSIONS=sh,bash,ps1,vbs,js,jar

# Block potentially dangerous files
FILES_DISABLED_EXTENSIONS=exe,dll,bat,cmd,sh,ps1,vbs,com,scr,pif,msi

Metadata Removal

FILES_REMOVE_GPS_METADATA

boolean

default:"false"

Automatically strip GPS and location metadata from uploaded images.

FILES_REMOVE_GPS_METADATA=true

When enabled, removes EXIF data including:

GPS coordinates
Location names
Timestamps
Camera information

Protecting user privacy by removing location data from photos is recommended for public instances.

File Size Limits

FILES_MAX_FILE_SIZE

string

default:"100mb"

Maximum allowed file size for uploads.

FILES_MAX_FILE_SIZE=500mb

Considerations:

Prevents storage exhaustion attacks
Limits bandwidth consumption
Affects server memory usage during uploads

Webhooks

Webhooks can notify external services when events occur, but should be configured carefully.

HTTP Webhooks

HTTP_WEBHOOK_ON_UPLOAD

string

default:"null"

URL to POST to when a file is uploaded.

HTTP_WEBHOOK_ON_UPLOAD=https://api.example.com/webhooks/upload

HTTP_WEBHOOK_ON_SHORTEN

string

default:"null"

URL to POST to when a URL is shortened.

HTTP_WEBHOOK_ON_SHORTEN=https://api.example.com/webhooks/shorten

Webhook payload includes:

File/URL metadata
User information
Timestamp
File URL

Discord Webhooks

DISCORD_WEBHOOK_URL

string

default:"null"

Global Discord webhook URL.

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123456789/abcdefg

DISCORD_USERNAME

string

default:"null"

Username for Discord webhook messages.

DISCORD_USERNAME=Zipline Bot

DISCORD_AVATAR_URL

string

default:"null"

Avatar URL for Discord webhook messages.

DISCORD_AVATAR_URL=https://zipline.example.com/logo.png

Upload-Specific Discord Webhook

DISCORD_ON_UPLOAD_WEBHOOK_URL

string

default:"null"

Separate webhook URL specifically for file uploads.

DISCORD_ON_UPLOAD_USERNAME

string

default:"null"

Username for upload notifications.

DISCORD_ON_UPLOAD_AVATAR_URL

string

default:"null"

Avatar URL for upload notifications.

DISCORD_ON_UPLOAD_CONTENT

string

default:"null"

Message content for upload notifications.

DISCORD_ON_UPLOAD_EMBED

json

default:"null"

JSON configuration for Discord embed on uploads.

DISCORD_ON_UPLOAD_EMBED='{"title":"New Upload","color":"#5865F2"}'

URL Shorten-Specific Discord Webhook

DISCORD_ON_SHORTEN_WEBHOOK_URL

string

default:"null"

Separate webhook URL specifically for URL shortening.

DISCORD_ON_SHORTEN_USERNAME

string

default:"null"

Username for shorten notifications.

DISCORD_ON_SHORTEN_AVATAR_URL

string

default:"null"

Avatar URL for shorten notifications.

DISCORD_ON_SHORTEN_CONTENT

string

default:"null"

Message content for shorten notifications.

DISCORD_ON_SHORTEN_EMBED

json

default:"null"

JSON configuration for Discord embed on URL shortening.

Webhook Security:

Webhook URLs contain secrets - keep them private
Don’t expose sensitive user data in webhook payloads
Use HTTPS endpoints only
Validate webhook destination is trusted
Monitor webhook activity for abuse

Security Best Practices

Production Deployment

# Strong secret (32+ characters)
CORE_SECRET=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32)

# Trust proxy when behind reverse proxy
CORE_TRUST_PROXY=true

# Return HTTPS URLs
CORE_RETURN_HTTPS_URLS=true

# Enable rate limiting
RATELIMIT_ENABLED=true
RATELIMIT_MAX=20
RATELIMIT_WINDOW=60000

# Remove GPS metadata
FILES_REMOVE_GPS_METADATA=true

# Disable public registration
FEATURES_USER_REGISTRATION=false

Private Instance

# Strict rate limiting
RATELIMIT_ENABLED=true
RATELIMIT_MAX=10
RATELIMIT_WINDOW=60000

# Invite-only access
FEATURES_USER_REGISTRATION=false
FEATURES_OAUTH_REGISTRATION=false
INVITES_ENABLED=true

# Block executables
FILES_DISABLED_EXTENSIONS=exe,bat,cmd,sh,ps1

Public Instance

# Moderate rate limiting
RATELIMIT_ENABLED=true
RATELIMIT_MAX=30
RATELIMIT_WINDOW=60000

# Allow registration with safeguards
FEATURES_USER_REGISTRATION=true

# Privacy protection
FILES_REMOVE_GPS_METADATA=true

# File restrictions
FILES_MAX_FILE_SIZE=100mb
FILES_DISABLED_EXTENSIONS=exe,dll,bat,cmd,sh,scr

Additional Security Features

HTTPS Enforcement

CORE_RETURN_HTTPS_URLS

boolean

default:"false"

Generate HTTPS URLs instead of HTTP.

CORE_RETURN_HTTPS_URLS=true

Always enable this in production when using HTTPS.

Password Protection

Users can password-protect individual files and URLs. Passwords are hashed using bcrypt before storage.

View Limits

FEATURES_DELETE_ON_MAX_VIEWS

boolean

default:"true"

Automatically delete files when they reach their maximum view count.

FEATURES_DELETE_ON_MAX_VIEWS=true

Useful for:

Self-destructing file shares
One-time secret sharing
Controlling content distribution

Monitoring and Logging

Enable logging to monitor security events:

DEBUG=zipline

Logs include:

Authentication attempts
Rate limit violations
File upload/download activity
Configuration validation errors
Datasource access issues

Troubleshooting

Rate Limiting Issues

Users getting rate limited incorrectly:

Check CORE_TRUST_PROXY is enabled if behind proxy
Verify proxy is setting X-Forwarded-For header
Add internal IPs to RATELIMIT_ALLOW_LIST

Rate limits not working:

Ensure RATELIMIT_ENABLED=true
Check window value is reasonable
Verify IP detection is working (check logs)

Proxy Issues

Wrong IP addresses in logs:

Enable CORE_TRUST_PROXY=true
Verify proxy headers are being sent

Rate limiting by proxy IP:

Same as above - trust proxy configuration needed

Next Steps

Authentication Configuration

OAuth, MFA, and user registration settings

Get Started

Core Concepts

Configuration

Features

Integrations

Administration

Guides

Security Configuration

Core Security Settings

Secret Key

Proxy Trust

Reverse Proxy Configuration Examples

Rate Limiting

Rate Limit Examples

File Security

Extension Blocking

Metadata Removal

File Size Limits

Webhooks

HTTP Webhooks

Discord Webhooks

Upload-Specific Discord Webhook

URL Shorten-Specific Discord Webhook

Security Best Practices

Additional Security Features

HTTPS Enforcement

Password Protection

View Limits

Monitoring and Logging

Troubleshooting

Rate Limiting Issues

Proxy Issues

Next Steps

Authentication Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Features

Integrations

Administration

Guides

Documentation Index

​Core Security Settings

​Secret Key

​Proxy Trust

​Reverse Proxy Configuration Examples

​Rate Limiting

​Rate Limit Examples

​File Security

​Extension Blocking

​Metadata Removal

​File Size Limits

​Webhooks

​HTTP Webhooks

​Discord Webhooks

​Upload-Specific Discord Webhook

​URL Shorten-Specific Discord Webhook

​Security Best Practices

​Additional Security Features

​HTTPS Enforcement

​Password Protection

​View Limits

​Monitoring and Logging

​Troubleshooting

​Rate Limiting Issues

​Proxy Issues

​Next Steps

Authentication Configuration

Build docs developers (and LLMs) love

Core Security Settings

Secret Key

Proxy Trust

Reverse Proxy Configuration Examples

Rate Limiting

Rate Limit Examples

File Security

Extension Blocking

Metadata Removal

File Size Limits

Webhooks

HTTP Webhooks

Discord Webhooks

Upload-Specific Discord Webhook

URL Shorten-Specific Discord Webhook

Security Best Practices

Additional Security Features

HTTPS Enforcement

Password Protection

View Limits

Monitoring and Logging

Troubleshooting

Rate Limiting Issues

Proxy Issues

Next Steps