---
title: 'Run with Docker'
url: 'https://chronoslice.app/docs/installing/run-with-docker'
markdown: 'https://chronoslice.app/docs/installing/run-with-docker.md'
date: '2026-11-14'
description: '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…'
taxonomy:
  kb_category:
    - Installing
---

[Docs](https://chronoslice.app/docs)

 [Contact support](https://chronoslice.app/help/new) 

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](https://chronoslice.app/docs/installing/reverse-proxy-and-https).

## Get the image

The image is `ghcr.io/skulkworks/chronoslice`. The [download page](https://chronoslice.app/download) 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`:

```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:PASSWORD@smtp.example.com:465
      CHRONOSLICE_MAIL_FROM: "Your Studio <billing@example.com>"
      # CHRONOSLICE_SETUP_TOKEN: a long random string, until the first account exists

volumes:
  chronoslice-data:
```

Then start it and watch the log:

```sh
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](https://chronoslice.app/docs/installing/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](https://chronoslice.app/docs/installing/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](https://chronoslice.app/docs/installing/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](https://chronoslice.app/docs/installing/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:

```yaml
    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](https://chronoslice.app/docs/installing/the-first-account). Or do it from the command line:

```sh
docker compose exec chronoslice chronoslice setup --email you@example.com --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](https://chronoslice.app/docs/help/command-reference).

Your 30-day trial starts with the first account. See [The trial](https://chronoslice.app/docs/licence-and-updates/the-trial).

## Updating

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

```sh
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](https://chronoslice.app/docs/licence-and-updates/updating).

## Backups

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

```sh
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](https://chronoslice.app/docs/installing/backups-and-restoring).

## Next

Put a reverse proxy in front of the container: [Reverse proxy and HTTPS](https://chronoslice.app/docs/installing/reverse-proxy-and-https). Then create your account: [The first account](https://chronoslice.app/docs/installing/the-first-account).

## Related

- [Requirements](https://chronoslice.app/docs/getting-started/requirements)
- [Updating](https://chronoslice.app/docs/licence-and-updates/updating)
- [Quick start](https://chronoslice.app/docs/getting-started/quick-start)
- [Install on Linux](https://chronoslice.app/docs/installing/install-on-linux)

## 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.

 [Contact support](https://chronoslice.app/help/new?from=%2Fdocs%2Finstalling%2Frun-with-docker)[Your requests](https://chronoslice.app/help/tickets)

---

## Navigation

- Parent: [Installing](https://chronoslice.app/docs/installing.md)
- Previous: [Install on macOS](https://chronoslice.app/docs/installing/install-on-macos.md)
- Next: [Reverse proxy and HTTPS](https://chronoslice.app/docs/installing/reverse-proxy-and-https.md)
