Docs Contact support
Docs menu

Run with Docker

Run ChronoSlice from its Docker image with Docker Compose, keep the data in a volume or a folder, and update by pulling the new image.

Updated Nov 14, 2026 5 min read

This page covers running ChronoSlice in a container: the image, a Compose file, where the data lives, the first account, updates and backups. The image is the same static build as the Linux download, on a minimal base with only CA certificates and the time zone database added. It runs as a non-root user (uid 65532), keeps everything in /data, and listens on port 7340. It comes for linux/amd64 and linux/arm64, so it runs on a VPS, a Raspberry Pi, and on NAS boxes that run containers, such as Synology, QNAP, Unraid and TrueNAS SCALE. HTTPS comes next, in Reverse proxy and HTTPS.

Get the image

The image is ghcr.io/skulkworks/chronoslice. The download page lists the newest version. Each release has a tag with its version number, such as ghcr.io/skulkworks/chronoslice:0.1.0, and latest is the newest release. There's nothing else to download. The trial image is the same one as the licensed one.

A Compose file

Make a folder for the install and put this in compose.yaml:

services:
  chronoslice:
    image: ghcr.io/skulkworks/chronoslice:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:7340:7340"
    volumes:
      - chronoslice-data:/data
    environment:
      CHRONOSLICE_PUBLIC_URL: https://time.example.com
      CHRONOSLICE_SECURE_COOKIES: "true"
      CHRONOSLICE_SMTP_URL: smtps://USERNAME:[email protected]:465
      CHRONOSLICE_MAIL_FROM: "Your Studio <[email protected]>"
      # CHRONOSLICE_SETUP_TOKEN: a long random string, until the first account exists

volumes:
  chronoslice-data:

Then start it and watch the log:

docker compose up -d
docker compose logs -f

You should see listening on http://0.0.0.0:7340. That address is inside the container. On a new install the log also says that there are no accounts yet and where to finish setup.

  • The port line publishes ChronoSlice on 127.0.0.1:7340 only, for a reverse proxy on the same machine. Use "7340:7340" to reach it directly from other machines.
  • CHRONOSLICE_PUBLIC_URL is the address people use, with no path. Emails link to invoices with it, and Stripe sends clients back to it after they pay.
  • CHRONOSLICE_SECURE_COOKIES marks the sign-in cookie Secure. Set it once HTTPS works. The value must be "true" or "false".
  • CHRONOSLICE_SMTP_URL and CHRONOSLICE_MAIL_FROM turn email on. See Email. Leave them out and the server says email is off, which is fine until you want to send invoices.
  • CHRONOSLICE_SETUP_TOKEN is a secret that the first-run setup page asks for, so nobody else can create the first account. Uncomment it and make a value with openssl rand -hex 24. See The first account.

CHRONOSLICE_DB and CHRONOSLICE_BIND are already set in the image, to sqlite:///data/chronoslice.db and 0.0.0.0:7340. Leave them alone. Every setting is listed in Settings reference.

Settings can also go in a file at /data/env, as KEY=value lines. The image reads it when the server starts, and every chronoslice command you run in the container reads it too. It keeps the SMTP password out of compose.yaml. Settings you give in compose.yaml win over the same setting in the file.

Put HTTPS in front

The container speaks plain HTTP. Put HTTPS in front with Caddy, Traefik, Nginx Proxy Manager or a Cloudflare Tunnel, and point it at port 7340. The proxy has to pass the Host header as the browser sent it, and not hold back the live updates stream. Reverse proxy and HTTPS explains both, with working Caddy and nginx files. Passkeys only work over HTTPS at the address in CHRONOSLICE_PUBLIC_URL.

Keep the data in a folder

The chronoslice-data volume holds the database. To keep the data in a folder you can see, which is common on a NAS, mount a folder at /data instead. The folder has to belong to uid 65532, or you run the container as the folder's owner:

    volumes:
      - ./data:/data
    user: "1000:1000"

Replace 1000:1000 with the owner of ./data. The other choice is to leave out user and run sudo chown 65532:65532 ./data.

The first account

Open the public address and finish setup in the browser. See The first account. Or do it from the command line:

docker compose exec chronoslice chronoslice setup --email [email protected] --name "Your Name" --org "Your Studio" --timezone America/Denver

It asks for the password. Every other chronoslice command runs the same way. For example, docker compose exec chronoslice chronoslice licence shows where the licence stands. See Command reference.

Your 30-day trial starts with the first account. See The trial.

Updating

Pull the new image and recreate the container. The new release brings the database up to date as it starts:

docker compose pull && docker compose up -d

Pin a version, such as ghcr.io/skulkworks/chronoslice:0.2.0, if you want to update only when you choose. chronoslice update doesn't replace anything inside a container. It only says whether a newer release is out. See Updating.

Backups

The database is /data/chronoslice.db. This makes a consistent copy while the server runs. The file name must be new:

docker compose exec chronoslice chronoslice backup /data/backup.db

The copy lands in the data folder or volume, so copy it somewhere else as well. You can also stop the container and copy the volume. Litestream can run as a second container that streams /data/chronoslice.db to S3-compatible storage, as it does on Linux. See Backups and restoring.

Next

Put a reverse proxy in front of the container: Reverse proxy and HTTPS. Then create your account: The first account.

Was this helpful?

Still stuck?

Send us a request: it goes to the people who build ChronoSlice, and the reply comes by email. Include your ChronoSlice version (Settings › Licence shows it) and what you tried.