Skip to main content
Zipline provides extensive customization options to brand your instance and tailor the user experience.

​
Website Settings

​
Basic Branding

​
WEBSITE_TITLE
string
default:"Zipline"
Website title displayed in browser tabs and page headers.
WEBSITE_TITLE=My File Server
URL to a logo image displayed next to the title.
WEBSITE_TITLE_LOGO=https://example.com/logo.png
​
WEBSITE_DEFAULT_AVATAR
string
default:"null"
Path to default avatar image for users without custom avatars.
WEBSITE_DEFAULT_AVATAR=/zipline/public/default-avatar.png

​
Login Page Customization

​
WEBSITE_LOGIN_BACKGROUND
string
default:"null"
URL to background image for the login page.
WEBSITE_LOGIN_BACKGROUND=https://example.com/background.jpg
​
WEBSITE_LOGIN_BACKGROUND_BLUR
boolean
default:"true"
Apply blur effect to login background image.
WEBSITE_LOGIN_BACKGROUND_BLUR=false
​
WEBSITE_EXTERNAL_LINKS
json
JSON array of external links displayed in the interface.
WEBSITE_EXTERNAL_LINKS='[{"name":"Support","url":"https://example.com/support"},{"name":"Status","url":"https://status.example.com"}]'
Each link object should have:
  • name (string): Display text for the link
  • url (string): Valid URL
Example: 
[
  {"name": "GitHub", "url": "https://github.com/yourorg/zipline"},
  {"name": "Documentation", "url": "https://docs.example.com"},
  {"name": "Support", "url": "https://support.example.com"}
]

​
Terms of Service

​
WEBSITE_TOS
string
default:"null"
Path to a Markdown file containing terms of service.
WEBSITE_TOS=/zipline/tos.md
The ToS file must be a .md (Markdown) file. Users will be required to accept the terms during registration.

​
Theme Configuration

Zipline supports custom themes with separate configurations for light and dark modes.
​
WEBSITE_THEME_DEFAULT
string
default:"system"
Default theme selection. Options: system, dark, light.
WEBSITE_THEME_DEFAULT=dark
​
WEBSITE_THEME_DARK
string
default:"builtin:dark_gray"
Theme to use in dark mode.
WEBSITE_THEME_DARK=builtin:dark_gray
# or custom theme
WEBSITE_THEME_DARK=custom:mytheme
​
WEBSITE_THEME_LIGHT
string
default:"builtin:light_gray"
Theme to use in light mode.
WEBSITE_THEME_LIGHT=builtin:light_gray
# or custom theme
WEBSITE_THEME_LIGHT=custom:mylighttheme

​
Built-in Themes

Zipline includes several built-in themes: Dark Themes:
  • builtin:dark_gray (default)
  • builtin:dark_blue
Light Themes:
  • builtin:light_gray (default)
  • builtin:light_blue

​
Custom Themes

Create custom themes by placing theme files in the /zipline/themes directory.
  1. Create a JSON theme file:
themes/mytheme.json
{
  "name": "My Custom Theme",
  "dark": true,
  "colors": {
    "primary": "#3b82f6",
    "background": "#1a1a1a",
    "foreground": "#ffffff",
    "card": "#262626",
    "border": "#404040"
  }
}
  1. Mount the themes directory in Docker:
docker-compose.yml
volumes:
  - './themes:/zipline/themes'
  1. Reference in environment variable:
WEBSITE_THEME_DARK=custom:mytheme

​
Progressive Web App (PWA)

Configure Zipline as a Progressive Web App for mobile-friendly installation.
​
PWA_ENABLED
boolean
default:"false"
Enable PWA manifest and service worker.
PWA_ENABLED=true
​
PWA_TITLE
string
default:"Zipline"
Application name displayed when installed as PWA.
PWA_TITLE=MyFiles
​
PWA_SHORT_NAME
string
default:"Zipline"
Short name for PWA (used on home screen).
PWA_SHORT_NAME=Files
​
PWA_DESCRIPTION
string
default:"Zipline"
Description of the PWA.
PWA_DESCRIPTION=My personal file sharing platform
​
PWA_THEME_COLOR
string
default:"#000000"
Theme color for PWA (affects browser UI).
PWA_THEME_COLOR=#3b82f6
​
PWA_BACKGROUND_COLOR
string
default:"#000000"
Background color shown during PWA launch.
PWA_BACKGROUND_COLOR=#1a1a1a

​
PWA Example

PWA_ENABLED=true
PWA_TITLE="MyFiles"
PWA_SHORT_NAME="Files"
PWA_DESCRIPTION="Personal file sharing and storage"
PWA_THEME_COLOR="#3b82f6"
PWA_BACKGROUND_COLOR="#1a1a1a"

​
File URL Configuration

​
FILES_ROUTE
string
default:"/u"
URL route prefix for uploaded files.
FILES_ROUTE=/f
# Results in URLs like: https://example.com/f/abc123.png
​
URLS_ROUTE
string
default:"/go"
URL route prefix for shortened URLs.
URLS_ROUTE=/s
# Results in URLs like: https://example.com/s/abc123
Route values must start with / and be lowercase. Changing routes after deployment will break existing file links.

​
Feature Visibility

​
FEATURES_ROBOTS_TXT
boolean
default:"true"
Serve a robots.txt file to control search engine indexing.
FEATURES_ROBOTS_TXT=true
When enabled, Zipline serves a robots.txt that:
  • Disallows indexing of uploaded files
  • Disallows indexing of admin panels
  • Allows indexing of public pages
Set to false for completely private instances.

​
Customization Examples

# Company branding
WEBSITE_TITLE="Acme Corp Files"
WEBSITE_TITLE_LOGO="https://cdn.acme.com/logo.svg"

# Custom colors via theme
WEBSITE_THEME_DARK="custom:acme_dark"
WEBSITE_THEME_LIGHT="custom:acme_light"

# Corporate links
WEBSITE_EXTERNAL_LINKS='[{"name":"IT Support","url":"https://support.acme.com"},{"name":"Privacy Policy","url":"https://acme.com/privacy"}]'

# Terms of service
WEBSITE_TOS="/zipline/corporate-tos.md"

# Custom routes
FILES_ROUTE="/files"
URLS_ROUTE="/links"

# Personal branding
WEBSITE_TITLE="John's Files"
WEBSITE_LOGIN_BACKGROUND="https://example.com/my-photo.jpg"
WEBSITE_LOGIN_BACKGROUND_BLUR="true"

# Simple theme
WEBSITE_THEME_DEFAULT="dark"
WEBSITE_THEME_DARK="builtin:dark_blue"

# Minimal external links
WEBSITE_EXTERNAL_LINKS='[{"name":"Portfolio","url":"https://john.example.com"}]'

# Clean URLs
FILES_ROUTE="/i"
URLS_ROUTE="/l"

# No robots.txt (private)
FEATURES_ROBOTS_TXT="false"

# Community branding
WEBSITE_TITLE="Community Files"
WEBSITE_TITLE_LOGO="https://cdn.example.com/community-logo.png"

# Friendly appearance
WEBSITE_THEME_DEFAULT="system"
WEBSITE_THEME_DARK="builtin:dark_gray"
WEBSITE_THEME_LIGHT="builtin:light_gray"

# Community links
WEBSITE_EXTERNAL_LINKS='[{"name":"Discord","url":"https://discord.gg/example"},{"name":"Rules","url":"https://example.com/rules"},{"name":"Donate","url":"https://example.com/donate"}]'

# Community terms
WEBSITE_TOS="/zipline/community-tos.md"

# PWA for mobile users
PWA_ENABLED="true"
PWA_TITLE="Community Files"
PWA_SHORT_NAME="CommFiles"
PWA_DESCRIPTION="Community file sharing"
PWA_THEME_COLOR="#10b981"

​
Static Assets

Custom images and files should be placed in the /zipline/public directory:
docker-compose.yml
volumes:
  - './public:/zipline/public'
Then reference them: 
WEBSITE_TITLE_LOGO="/zipline/public/logo.png"
WEBSITE_DEFAULT_AVATAR="/zipline/public/default-avatar.png"
WEBSITE_LOGIN_BACKGROUND="/zipline/public/background.jpg"

​
Multi-Domain Configuration

​
DOMAINS
string[]
default:"[]"
Additional domains for multi-domain support.
DOMAINS=files.example.com,uploads.example.com,cdn.example.com
​
CORE_DEFAULT_DOMAIN
string
default:"null"
Default domain to use when generating URLs.
CORE_DEFAULT_DOMAIN=cdn.example.com
Use cases:
  • Separate domains for different file types
  • CDN integration
  • Geographic distribution
  • Branding variations

​
Best Practices

  • Use optimized images for logos and backgrounds
  • Recommended logo size: 200x50px (or similar aspect ratio)
  • Background images: Use compressed JPEG/WebP
  • Limit background image size to less than 500KB
  • Ensure light and dark themes are visually coherent
  • Test themes on multiple devices
  • Consider color accessibility (WCAG guidelines)
  • Provide sufficient contrast ratios
  • Enable PWA for better mobile experience
  • Test login background on mobile devices
  • Keep external links list concise (3-5 items max)
  • Use responsive images

​
Next Steps

Environment Variables

Complete configuration reference

Datasource Configuration

Storage backend setup

Build docs developers (and LLMs) love

Get started for freeTalk to us