Self-hosted service
diced/zipline avatar
diced/zipline

Zipline: a self-hosted ShareX upload server you run with Docker Compose

A ShareX/file upload server that is easy to use, packed with features, and with an easy setup!

3,494 stars262 forksTypeScriptMIT

At a glance

What is it?
Zipline is an MIT-licensed TypeScript upload server for ShareX and other clients, shipped as a container image with Postgres and a local or S3 datasource. This article covers how to install it, how its storage and database layers fit together, and where it stops being the right tool.
Who is it for?
Adopt Zipline if you want a self-hosted upload endpoint for ShareX or a browser, you can run Docker Compose with Postgres 16, and your CPU exposes AVX. Do not adopt it if you need an in-place upgrade from Zipline v3, if you cannot mount the three required volumes, or if your hardware lacks AVX, because the project states it ships no images for those CPUs.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 10, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • diced/zipline3,494 ★ · +64
Star history
Repository2026-09-242026-11-10
diced/zipline3.4k3.5k

64 Stars in the last 47 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Zipline replaces, and who ends up running it

ShareX and similar screenshot tools need somewhere to send a file and a URL to put on the clipboard afterwards. Public hosts exist, but they decide retention, naming and access rules. Zipline is the self-hosted end of that pipe: a server that accepts uploads, stores them, and hands back a link, with folders, tags, URL shortening, embeds and password protection layered on top. The README describes it as "The next generation ShareX / File upload server" and lists OAuth2, 2FA and passkeys among its features, which tells you the intended operator is a person or small team who wants accounts and access control, not just an anonymous drop box.

The audience is narrow in a useful way. You need to be comfortable running Postgres and a container alongside it. In exchange you get an HTTP API, a PWA front end, quotas and invites. If your only requirement is moving a file from A to B once a week, the operational surface here is larger than the problem.

How uploads move through Zipline: datasource, database and volumes

The architecture splits into three parts that the compose file makes explicit. Postgres holds metadata, and the Zipline container is given a DATABASE_URL built from POSTGRESQL_USER, POSTGRESQL_PASSWORD and POSTGRESQL_DB, defaulting to the zipline user and database. It waits on a pg_isready healthcheck before starting, so the ordering is enforced by Compose rather than by retry logic in the app.

File bytes go somewhere else. By default the datasource is the local filesystem at /zipline/uploads, mounted from ./uploads on the host. Setting DATASOURCE_TYPE=s3 switches the storage backend, with DATASOURCE_S3_ACCESS_KEY_ID, DATASOURCE_S3_SECRET_ACCESS_KEY, DATASOURCE_S3_BUCKET and DATASOURCE_S3_REGION as the credentials and target. That separation is the main design decision worth noting: the database and the object store can be scaled or backed up independently, and a full disk on the uploads volume does not corrupt metadata.

The third piece is temporary files. The README states they default to ./uploads/.tmp and warns that pointing CORE_TEMP_DIRECTORY at another filesystem, such as tmpfs, can reduce local upload performance. That is an unusual warning, and it is worth taking literally: the fast-looking option is the one the documentation flags as slower.

Two more volumes are required and must be mounted at fixed paths. ./public maps to /zipline/public and ./themes maps to /zipline/themes. The README is explicit that these must mount to those locations, so relocating them on the host side means editing the compose file, not adding an environment variable.

Installing Zipline with Docker Compose and taking a first upload

The README calls Docker the recommended way to run Zipline and points at the get-started/docker page for the longer guide. The repository ships a docker-compose.yml with a postgres:16 service and a zipline service using the image ghcr.io/diced/zipline:latest, exposing port 3000.

Start by writing the two secrets into a .env file next to the compose file. The README gives these exact commands; CORE_SECRET is mandatory and the server will not start without it.

bash
echo "POSTGRESQL_PASSWORD=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32 | tr -d '\n')" > .env
echo "CORE_SECRET=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32 | tr -d '\n')" >> .env

Bring the stack up in the background. Compose will start Postgres first and hold Zipline until the pg_isready check passes.

bash
docker compose up -d

When the containers are healthy, the README says the site is reachable at http://localhost:3000, or whichever port you set. Log in there and create an upload, or point a ShareX destination at the instance and send a screenshot. The container also exposes a health endpoint that the compose healthcheck probes with wget against http://0.0.0.0:3000/api/healthcheck.

If you want the port elsewhere, set CORE_PORT and CORE_HOSTNAME. The README's example uses CORE_PORT=80 and CORE_HOSTNAME=localhost, and it notes that changing the port means updating the ports section of the compose file as well.

bash
CORE_PORT=80
CORE_HOSTNAME=localhost

For object storage instead of the local disk, the README gives this set of variables. Only the four shown are documented in the README itself; the datasource config page covers other providers.

bash
DATASOURCE_TYPE=s3

DATASOURCE_S3_ACCESS_KEY_ID=access_key_id
DATASOURCE_S3_SECRET_ACCESS_KEY=secret
DATASOURCE_S3_BUCKET=zipline
DATASOURCE_S3_REGION=us-west-2

If you move the uploads directory, set DATASOURCE_LOCAL_DIRECTORY to the new path, either absolute or relative to the working directory, and remember to change the volume mapping to match. The README does not document rollback of a bad configuration change, so keep the previous .env until the new one is confirmed working.

The AVX requirement and the v3 migration wall

Two constraints stand out because they are not fixable by configuration. The first is CPU support. The README carries a warning that Zipline requires a CPU with AVX support and that the project does not provide binaries or images for non-AVX CPUs. On older hardware, or on some virtualized and ARM environments, that ends the evaluation before installation begins. There is no documented fallback build.

The second is the upgrade path from Zipline v3. The README states plainly that v4 was a complete rewrite and that there is no upgrade path from v3 to v4; data has to be exported from v3 and imported into v4. The mitigation is that v4 has a built-in importer, and the migration page covers the process. That is a real cost for anyone running v3 in production: this is a data migration, not a version bump, and it needs a window and a test.

A smaller limitation is the volume contract. Because /zipline/public and /zipline/themes must be mounted at those exact paths, and uploads default to ./uploads, a deployment that cannot bind-mount host directories needs a different storage arrangement, meaning the S3 datasource. That is documented, but it means the "easy setup" claim depends on having a host where bind mounts are available.

Zipline against a plain object store with presigned URLs

The obvious alternative is to skip the application layer and upload straight to S3-compatible storage using presigned URLs, with a small script or ShareX's own S3 destination support handling the client side. The difference in approach is where the logic lives. With presigned URLs, the object store is the only stateful component, and access control, expiry and URL shape come from bucket policy and signature parameters. There is no database to run and no web UI to keep patched.

Zipline moves that logic into the server: accounts, OAuth2, 2FA, passkeys, folders, tags, quotas, invites and URL shortening are all application features, and the README lists image compression and video thumbnails as processing steps. That is why Postgres is a hard dependency rather than an optional one. The trade is clear: presigned URLs give you fewer moving parts and no gallery, while Zipline gives you a browsable, permissioned front end at the cost of a second service and a schema you now own. Note that Zipline can also use S3 as its datasource, so the two are not mutually exclusive; you can keep the application layer and still put bytes in a bucket.

Licence, releases and the cost of staying current

Zipline is MIT-licensed, and the package.json carries "license": "MIT" with version 4.7.0. MIT is permissive, so the practical implication for most operators is that running a modified build internally is not a licensing question. This is not legal advice, and if you redistribute a modified image you should read the LICENSE file in the repository rather than this summary.

The release cadence visible in the repository is regular: v4.7.0 on 2026-08-16, v4.6.5 on 2026-07-28 and v4.6.4 on 2026-07-06, with the last push to trunk on 2026-09-19. Frequent releases mean the upgrade cost is real but small per step, provided you keep up. The compose file references ghcr.io/diced/zipline:latest, which means a plain docker compose pull will move you to whatever is newest, and the README's own example uses ghcr.io/diced/zipline without a tag. If you want reproducible deployments, pin a tag or digest yourself; the repository does not do it for you in the compose file.

Schema changes are handled with Drizzle. The repository has a drizzle/ directory and a drizzle.config.ts at the top level, and package.json exposes db:migrate (drizzle-kit generate) and db:prototype (drizzle-kit push) scripts. Those are development-side commands. The README does not document how migrations are applied to a running container, so verify that before you plan an upgrade window.

Building from source and the Nix development shell

The README points manual installs at the get-started/source documentation page rather than inlining steps, so the repository files are the better guide. The Dockerfile is a three-stage build on node:24-alpine3.23 that installs ffmpeg and tzdata, runs pnpm install with a frozen lockfile, and builds with ZIPLINE_BUILD=true. The runtime stage copies node_modules from the deps stage and the build output from the builder stage, then sets NODE_ENV=production and ZIPLINE_ROOT=/zipline. It also installs a ziplinectl script symlinked into /usr/local/bin.

For local development, package.json defines dev, which runs the server through tsx with NODE_ENV=development and DEBUG=zipline, and dev:inspector, which adds --inspect=0.0.0.0:9229. Tests run through Node's built-in test runner with a custom reporter over tests/**/*.ts.

The README offers a Nix path as well. With Nix and direnv installed, cd into the cloned directory and run direnv allow to set up the shell; without direnv, nix develop --no-pure-eval enters the same shell. The repository has flake.nix and flake.lock at the top level, consistent with that instruction. There is also a docker:engine script that starts colima with the themes, uploads and public directories mounted writable, which is a macOS-oriented convenience rather than a general requirement.

Editorial conclusion

Adopt Zipline if you want a self-hosted upload endpoint for ShareX or a browser, you can run Docker Compose with Postgres 16, and your CPU exposes AVX. Do not adopt it if you need an in-place upgrade from Zipline v3, if you cannot mount the three required volumes, or if your hardware lacks AVX, because the project states it ships no images for those CPUs. Verify the AVX flag on the target host before you pull anything, and confirm which image tag you intend to pin, since the compose file references ghcr.io/diced/zipline:latest while the README example uses ghcr.io/diced/zipline.

Frequently asked questions

How do I install Zipline?

The README recommends Docker: create a .env with POSTGRESQL_PASSWORD and CORE_SECRET, then run docker compose up -d against the repository's docker-compose.yml, which starts postgres:16 alongside the ghcr.io/diced/zipline image on port 3000. A manual source install is pointed at the get-started/source documentation page.

What is Zipline?

Zipline is a self-hosted ShareX and file upload server written in TypeScript and licensed MIT. The README lists uploads, folders, tags, URL shortening, embeds, OAuth2, 2FA, passkeys and an API among its features.

Does Zipline need a database?

Yes. The shipped docker-compose.yml runs a postgres:16 service and passes a DATABASE_URL built from POSTGRESQL_USER, POSTGRESQL_PASSWORD and POSTGRESQL_DB to the Zipline container, which waits for the pg_isready healthcheck before starting.

Can Zipline store uploads in S3 instead of the local disk?

Yes. Setting DATASOURCE_TYPE=s3 switches the datasource, with DATASOURCE_S3_ACCESS_KEY_ID, DATASOURCE_S3_SECRET_ACCESS_KEY, DATASOURCE_S3_BUCKET and DATASOURCE_S3_REGION as the credentials and target. The README points at the datasource config page for other providers.

Can I upgrade an existing Zipline v3 install to v4?

No. The README states that v4 was a complete rewrite and that there is no upgrade path from v3 to v4, so data must be exported from v3 and imported into v4. It notes that v4 includes a built-in importer to make that easier.

Official sources

  1. diced/zipline on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/diced-zipline.svg)](https://hysenlabs.com/projects/diced-zipline)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/diced-zipline.svg)](https://hysenlabs.com/projects/diced-zipline)

Was this useful?