Self-Hosting
Run OpenTickly on your own machine with Docker Compose. One command starts the app, PostgreSQL, and Redis. Also covers CasaOS, ZimaOS, Synology, fnOS, and other NAS platforms.
All you need to run OpenTickly yourself is one docker-compose.yml file. Here's how to go from nothing to a working instance.
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
Make a new folder and download the compose file:
mkdir -p opentickly && cd opentickly
wget -O docker-compose.yml \
https://raw.githubusercontent.com/CorrectRoadH/OpenTickly/main/docker-compose.ymlIt starts three containers:
- OpenTickly — Web UI + REST API (exposed on
8080) postgres— Database (internal network only, not exposed)redis— Cache and background jobs (internal network only, not exposed)
Step 2 — (Optional) Configure .env
The defaults work as-is. To change the port or passwords, create a .env file in the same folder:
# Exposed port for the web UI and API
OPENTOGGL_PORT=8080
# Change these to strong passwords before real use
OPENTOGGL_POSTGRES_PASSWORD=postgres
OPENTOGGL_REDIS_PASSWORD=opentogglThese three are the only settings you can change through .env. Everything else (database name, user, images, connection strings) is fixed in the compose file on purpose, to keep setups simple and alike. To change more, edit docker-compose.yml directly.
Change both passwords before real use. The defaults are only fine for trying it out locally. Postgres and Redis aren't reachable from outside Docker, but if another machine or container on your network gets compromised, strong passwords stop it from reading your data.
Step 3 — Start the Containers
docker compose up -dAccess the Web App
Open http://<your-ip>:8080 in a browser, register the first account, and start tracking time.
Mobile
There's no mobile app yet, but you can add the web app to your phone's home screen and use it like one (PWA). We're also talking to developers of third-party Toggl apps, such as Timery, about supporting OpenTickly.
Hook Up AI Agents
OpenTickly doesn't have Toggl's 30 requests/hour limit, so Claude, Cursor, and other agents can use it as much as they need. Set up toggl-cli and in a few minutes your agent can start and stop timers and organize projects for you.
Upgrade
docker compose pull
docker compose up -dDeploy to NAS / Homelab
OpenTickly runs anywhere Docker Compose does. The steps below are the same setup, done through each platform's UI.
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
8080and 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
You can change three settings through .env:
| 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, connection strings, volume names) is set directly in docker-compose.yml. To change it, edit the file.
Health Check Endpoints
| Path | Purpose |
|---|---|
/readyz | Ready to serve? (checks DB + Redis) |
/healthz | Is the process running? |
Next Steps
- HTTPS and reverse proxy
- Backups, restore, and upgrades
- AI Integration — Connect Claude, Cursor, and other agents to your instance
- GitHub Repository — Source, Issues, Discussions
- Hitting issues during deployment? Let us know in Issues