Skip to main content
After installing Zipline, follow these steps to set up your instance and start uploading files.

​
Create your admin account

1

Access the registration page

Navigate to your Zipline instance in a web browser:
http://localhost:3000
Or use your configured domain if you’ve set one up.
2

Enable user registration

By default, user registration is disabled. To create the first admin account, you need to temporarily enable it:Add to your .env file (Docker) or environment:
.env
FEATURES_USER_REGISTRATION=true
Then restart Zipline:
docker compose restart zipline
3

Register your account

  1. Click Sign up or navigate to /auth/register
  2. Enter your desired username and password
  3. Click Create Account
The first user created is automatically granted administrator privileges.
4

Disable public registration

After creating your admin account, disable public registration for security:
.env
FEATURES_USER_REGISTRATION=false
Restart Zipline again to apply the change.
You can create additional users through invites or the admin dashboard.

​
Configure basic settings

Once logged in, configure essential settings through the dashboard:
Navigate to Settings → Uploads to configure:
  • File name format: Choose how uploaded files are named
    • random - Random characters (default)
    • date - Timestamp-based names
    • uuid - UUID v4 format
    • name - Original filename
    • gfycat - Gfycat-style names
    • random-words - Readable random words
  • File name length: Number of characters for random names (default: 6)
  • Maximum file size: Set upload size limits
  • Disabled extensions: Block specific file types
These settings can also be configured via environment variables. See environment variables.
Configure custom domains for file URLs:Navigate to Settings → Domains and add your domains:
https://i.yourdomain.com
https://cdn.yourdomain.com
Ensure your domains point to your Zipline instance before adding them.
Customize your personal settings:
  • Avatar: Upload a custom avatar
  • Theme: Choose between light, dark, or system theme
  • Embed settings: Configure default embed appearance
  • API token: Generate tokens for API access
Enable additional security features:
  • Two-factor authentication (2FA): Add TOTP-based 2FA
  • Passkeys: Register hardware security keys
  • OAuth2: Configure external authentication providers
See authentication configuration for details.

​
Your first upload

1

Navigate to dashboard

From the main dashboard, click Upload or drag and drop files anywhere on the page.
2

Select files

Choose one or more files from your computer. You can also:
  • Paste images from clipboard
  • Take screenshots (using ShareX or similar tools)
3

Configure upload options

Before uploading, optionally configure:
  • Folder: Organize uploads into folders
  • Password protection: Require password to access
  • Expiration: Auto-delete after a time period
  • Max views: Delete after X views
  • Compression: Enable image compression
4

Upload and share

Click Upload and copy the generated URL. The file is now accessible!

​
Essential environment variables

Here are the most important environment variables to configure:
​
CORE_SECRET
string
required
Encryption secret, minimum 32 characters. Required to start Zipline.
CORE_SECRET="your-32-character-minimum-secret"
​
DATABASE_URL
string
required
PostgreSQL connection string.
DATABASE_URL="postgresql://user:password@host:5432/database"
​
CORE_PORT
number
default:"3000"
Port for Zipline to listen on.
CORE_PORT=3000
​
CORE_HOSTNAME
string
default:"0.0.0.0"
Hostname to bind to.
CORE_HOSTNAME=0.0.0.0
​
DATASOURCE_TYPE
string
default:"local"
Storage backend: local or s3.
DATASOURCE_TYPE=local
​
DATASOURCE_LOCAL_DIRECTORY
string
default:"./uploads"
Directory for local file storage.
DATASOURCE_LOCAL_DIRECTORY=./uploads
See the configuration reference for all available options.

​
Common tasks

​
Create additional users

With registration disabled, create users through:
  1. Invites: Navigate to Admin → Invites → Create Invite
  2. CLI: Use ziplinectl to create users directly 
    docker exec -it zipline-zipline-1 ziplinectl user create

​
Set up reverse proxy

For production deployments, use a reverse proxy (nginx, Caddy, Traefik) with HTTPS: 
server {
    listen 80;
    server_name your-domain.com;
    
    client_max_body_size 100M;
    
    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;
    }
}
When using a reverse proxy, set CORE_TRUST_PROXY=true in your environment to properly handle forwarded headers.

​
Enable HTTPS URLs

If you’re using HTTPS via a reverse proxy, configure Zipline to return HTTPS URLs:
.env
CORE_RETURN_HTTPS_URLS=true
CORE_DEFAULT_DOMAIN=https://your-domain.com

​
Next steps

Configuration guide

Explore all configuration options and features

ShareX integration

Set up ShareX for seamless uploads

S3 storage

Configure S3-compatible storage

API documentation

Build integrations with the Zipline API

Build docs developers (and LLMs) love

Get started for freeTalk to us