Self-Hosting

Deploy OpenTickly on your own machine — Docker Compose brings up Web + API + Postgres + Redis in one command, online in 5 minutes. 100% Toggl API compatible, works with the official clients out of the box.

Running OpenTickly on your own machine only takes a single docker-compose.yml. Here's the full path from zero to working.

System Requirements

Any Linux, macOS, or Windows machine with Docker Engine 20.10+ and Docker Compose v2
About 1 GB of RAM and 1 GB of disk
One free TCP port (default 8080)

If you don't have Docker yet, follow the official install guide first.

Deploy the Server

Step 1 — Download `docker-compose.yml`

Create a new directory and pull down the official compose file:

mkdir -p opentickly && cd opentickly

wget -O docker-compose.yml \
  https://raw.githubusercontent.com/CorrectRoadH/OpenTickly/main/docker-compose.yml

This compose file defines three containers:

OpenTickly — Web UI + REST API (exposed on 8080)
postgres — Database (internal network only, not exposed)
redis — Cache and background task queue (internal network only, not exposed)

Step 2 — (Optional) Configure `.env`

Defaults work out of the box. To change the port or passwords, create a .env in the same directory:

# Exposed port for the web UI and API
OPENTOGGL_PORT=8080

# Strongly recommend switching to strong passwords before going to production
OPENTOGGL_POSTGRES_PASSWORD=postgres
OPENTOGGL_REDIS_PASSWORD=opentoggl

These three variables are the only overridable settings in the entire compose file — everything else (database name, user, images, internal connection strings) is hard-coded to avoid config drift. If you need deeper customization, edit docker-compose.yml directly.

Always change both passwords in production. The defaults are only suitable for local tinkering. Even though Postgres/Redis don't expose ports to the host, setting passwords is basic hygiene against lateral movement inside your network.

Step 3 — Start the Containers

docker compose up -d

Access the Web App

Open http://<your-ip>:8080 in a browser, register the first account, and start tracking time.

Mobile

There's no official mobile app yet, but you can add the web UI to your phone's home screen (PWA). Third-party Toggl clients such as timery — we're currently reaching out to their developers about OpenTickly support.

Hook Up AI Agents

OpenTickly has no 30 requests/hour rate limit, which means Claude, Cursor, and similar agents can go all-in. Pair it with toggl-cli to install the skill pack into an agent environment, and in a few minutes you can have AI start/stop timers and tidy up projects for you.

Upgrade

docker compose pull
docker compose up -d

Deploy to NAS / Homelab

OpenTickly runs on anything that supports Docker Compose. The flows below are just the same steps wrapped in each platform's UI — the underlying commands are identical.

CasaOS

Open the CasaOS dashboard
Go to App Store → Custom Install → Import docker-compose
Paste the contents of docker-compose.yml
Set the Web UI port to 8080 and save
Launch from the dashboard

Access via http://<your-casaos-ip>:8080.

ZimaOS

ZimaOS (the official OS for Zimablade / Zimacube) shares the same App Store as CasaOS, so the steps are identical: App Store → Custom Install → Import docker-compose, then paste the compose file.

Synology

Synology DSM 7.2+ supports Docker Compose through Container Manager:

Open Container Manager → Project → Create
Set a project name, e.g. opentickly
Choose Use docker-compose.yml and paste the compose file
Click through the wizard to finish

If 8080 conflicts with DSM, add OPENTOGGL_PORT=9090 (or any free port) in the environment settings before creating the project.

fnOS

fnOS ships with a built-in Docker panel:

Open the Docker app from the fnOS desktop
In the left sidebar, choose Compose → New Project
Project name opentickly, leave the storage path at its default
Paste the compose file into Compose Content
Click Deploy and wait for all three containers to turn green

Other Platforms

The following platforms follow the same Docker Compose flow:

Unraid — Community Applications or Compose Manager plugin
TrueNAS SCALE — Custom app + Docker Compose
Proxmox LXC — Install Docker inside an LXC container, then follow the Deploy the Server steps

Configuration Reference

The entire compose file only has three overridable settings:

Variable	Default	Description
`OPENTOGGL_PORT`	`8080`	Exposed port for the web UI and API
`OPENTOGGL_POSTGRES_PASSWORD`	`postgres`	Postgres password (must change in production)
`OPENTOGGL_REDIS_PASSWORD`	`opentoggl`	Redis password (must change in production)

Everything else (database name, user, image tags, internal connection strings, volume names) is hard-coded in docker-compose.yml. If you need to change it, edit the file.

Health Check Endpoints

Path	Purpose
`/readyz`	Readiness check (depends on DB + Redis)
`/healthz`	Liveness check (is the process running)

Next Steps

AI Integration — Connect Claude, Cursor, and friends to your own instance
GitHub Repository — Source, Issues, Discussions
Hitting issues during deployment? Let us know in Issues

On this page