Take Control of Your File Sharing With Zipline
Most people who share files regularly have at some rate handed over control to a third-party service – uploading screenshots, videos, and documents to platforms that collect usage data, enforce storage limits, and can change their terms at any moment. Zipline is an open-source, self-hosted file sharing server that puts that control back in your hands. It gives you a clean web dashboard, shareable links, user management, and optional URL shortening, all running on your own hardware or VPS.
Zipline is built with Next.js and supports Docker deployments, which makes it relatively straightforward to get running on any Linux machine. It handles image uploads natively, works well with screenshot tools like ShareX and Flameshot, and lets you configure storage backends including local disk and S3-compatible providers. This guide walks through a complete Docker-based setup on a fresh Ubuntu or Debian server, from prerequisites to your first upload.
What You Need Before You Start
This setup assumes you have a Linux server – either a VPS or a home machine – running Ubuntu 22.04 or Debian 12. You will need root or sudo access, Docker and Docker Compose installed, and a domain name pointed at your server’s IP address if you want HTTPS via a reverse proxy. Zipline needs at least 1GB of RAM to run comfortably, though 2GB is a safer baseline if you plan to handle larger files or serve multiple users.
Make sure Docker is installed before moving forward. If it is not, install it with the official convenience script: curl -fsSL https://get.docker.com | sh. Add your user to the Docker group with sudo usermod -aG docker $USER, then log out and back in. Confirm Docker Compose is available by running docker compose version – you want Compose v2 or newer, which ships bundled with modern Docker installations.
Installing and Configuring Zipline
Start by creating a working directory for Zipline and pulling the official Docker Compose configuration. Run the following to set up your folder structure:
- mkdir -p ~/zipline && cd ~/zipline
- Download the official compose file: curl -o docker-compose.yml https://raw.githubusercontent.com/diced/zipline/trunk/docker-compose.yml
- Create a .env file in the same directory for your environment variables
The .env file is where Zipline’s core configuration lives. Open it with your editor of choice and set the following essential variables. CORE_SECRET is the most critical – it signs session tokens, so use a long random string generated with something like openssl rand -hex 32. Set CORE_DATABASE_URL to match the PostgreSQL credentials you will define in the compose file. Set CORE_RETURN_HTTPS to true if you are running behind a reverse proxy with SSL. Set DATASOURCE_TYPE to local for local disk storage, and DATASOURCE_LOCAL_DIRECTORY to your preferred upload path, typically ./uploads.
The default Docker Compose file bundles a PostgreSQL container alongside Zipline’s main application container. Open the compose file and confirm the database service is configured with a username, password, and database name that match your CORE_DATABASE_URL string exactly. A common mistake here is a mismatch between the connection string credentials and the PostgreSQL environment variables – double-check both before proceeding. If you prefer to use an external PostgreSQL instance you already manage, remove the database service from the compose file and point the connection string at your existing host.
Once your configuration is set, bring the stack up with docker compose up -d. Watch the logs with docker compose logs -f zipline to confirm the application starts cleanly and connects to the database. On first boot, Zipline runs database migrations automatically. When you see the ready message in the logs, the server is accepting connections on port 3000 by default.
Setting Up a Reverse Proxy With HTTPS
Exposing port 3000 directly to the internet is not recommended for production use. Running Nginx or Caddy as a reverse proxy in front of Zipline handles SSL termination and gives you a clean domain-based URL. Caddy is the simpler option for most setups because it handles certificate renewal automatically via Let’s Encrypt with almost no configuration.
Install Caddy on your server, then create or edit your Caddyfile with a block like this: set your domain as the site address, and proxy all requests to localhost:3000. A minimal Caddyfile entry looks like: files.yourdomain.com { reverse_proxy localhost:3000 }. Reload Caddy with sudo systemctl reload caddy, and within seconds your Zipline instance will be reachable over HTTPS with a valid certificate. Make sure your domain’s DNS A record is pointing at your server’s public IP before this step, or the certificate request will fail.
First Login and Configuring Your Instance
Open your browser and navigate to your Zipline domain. The first-time setup screen will prompt you to create an administrator account – set a strong password here, as this account has full control over the instance. After logging in, you land on the dashboard, which shows upload statistics, recent files, and quick-access controls for user management.
Head into the Admin panel to configure global settings. You can set maximum file size limits, enable or disable user registrations, configure an invite system for controlled signups, and set default file expiration policies. Zipline also supports URL shortening out of the box – this is toggled from the admin settings and uses the same domain as your file server. If you plan to use Zipline as a personal ShareX host, navigate to the Upload section of your user settings and download the pre-generated ShareX configuration file, which contains your API token and endpoint URL already filled in.
For S3-compatible storage – useful if you want to store files on Backblaze B2, Cloudflare R2, or a MinIO instance rather than local disk – update your .env file to set DATASOURCE_TYPE=s3 and supply the bucket name, access key, secret key, endpoint URL, and region. Restart the stack with docker compose restart zipline after any environment variable changes, since Zipline reads these only at startup.
Keeping Zipline Updated and Backed Up
Zipline releases updates regularly through its Docker image tagged as ghcr.io/diced/zipline. To update, pull the latest image and recreate the container: run docker compose pull followed by docker compose up -d. The container will be replaced with the new version, and migrations run automatically on startup. Check the Zipline GitHub release notes before each update – occasionally a release includes a breaking change that requires a config adjustment.
Backups require two components: the PostgreSQL database and your uploads directory. For the database, use docker exec to run pg_dump inside the PostgreSQL container and pipe the output to a file on the host. For uploads, a simple rsync or rclone job copying the uploads folder to an offsite location covers the file side. If you switched to S3-compatible storage, your files are already handled by the remote provider, so only the database backup needs to be part of your regular routine. Scheduling both jobs as daily cron tasks takes under ten minutes to configure and saves significant headache if your server ever needs to be rebuilt from scratch.
