Install Core
Choose the deployment method that fits your infrastructure. Both install the dashboard, API, database, and workers.
Choose a method
- Docker Compose: deploy released images on one host. Requires Git, Docker, and Docker Compose.
- Kubernetes with Helm: deploy into a cluster with in-cluster or external PostgreSQL. Requires Kubernetes 1.29+ and Helm 3.14+.
After sign-in, follow First asset and alert check. You can add integrations and certificate automation afterward.
Operate your installation
- Configuration basics: settings, SMTP, secrets, and restarts.
- Upgrade and Backup and restore.
- Kubernetes operations: optional networking, metrics, and scaling.
For contributing or running from source, use Core DEVELOPMENT.md.
Previous section links
Option A - Docker Compose
Continue in the Compose guide.
Step 1 - Clone and configure
Continue in Clone and configure.
Step 2 - Edit .env
Continue in Edit .env.
Step 3 - Start all services
Continue in Start all services.
Step 4 - Verify
Continue in Verify.
Option B - Kubernetes with Helm
Continue in the Helm guide.
Step 1 - Install the CloudNativePG operator (if using in-cluster PostgreSQL)
Continue in Install the CloudNativePG operator.
Step 2 - Install the chart
Continue in Install the chart.
Step 3 - Wait for pods and access the dashboard
Continue in Wait for pods and access the dashboard.
Required environment variables
Continue in the configuration reference and Configuration basics.
First login
Continue in Compose first login or Helm first login.
Optional components
Continue in Kubernetes operations.
NetworkPolicy
Continue in NetworkPolicy.
Autoscaling and pod disruption budgets
Continue in Autoscaling and pod disruption budgets.
ServiceMonitor
Continue in ServiceMonitor.
Pinning images (private registries, air-gapped, reproducible deploys)
Continue in Pinning images.
Upgrading
Continue in the Upgrade guide.
Docker Compose
Continue in Upgrade: Docker Compose.
Kubernetes
Continue in Upgrade: Kubernetes.
Previous installation sections now live in the complete Compose, Helm, configuration, and upgrade guides.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| API won't start | Database unreachable or credentials wrong | Test with psql postgresql://tokentimer:password@localhost:5432/tokentimer; check docker compose logs api, or kubectl logs -n tokentimer deployment/tokentimer-api |
| Login returns 401 on localhost | NODE_ENV=production with plain-HTTP local URLs; the browser drops secure session cookies | Put HTTPS in front, or use NODE_ENV=development locally; last resort: SESSION_COOKIE_SECURE_LOCALHOST_OVERRIDE=true |
| No admin account exists | Admin bootstrap skipped (no ADMIN_EMAIL/ADMIN_PASSWORD on first start, or DISABLE_ADMIN_BOOTSTRAP set) | Set the bootstrap variables and restart the API once; remove ADMIN_PASSWORD afterwards |
| Workers not sending alerts | SMTP unconfigured, or alerts still queued | Check worker logs (docker compose logs worker-discovery worker-delivery, or kubectl logs -n tokentimer -l app.kubernetes.io/component=alert-delivery); check SMTP configuration without copying secret values; inspect the alert_queue table for pending rows |
| Dashboard loads but API calls fail | API_URL/APP_URL mismatch with actual public URLs | Align the URL variables with what browsers use, rebuild/restart the dashboard |
| Helm install stalls on database | CloudNativePG operator not installed (default in-cluster PostgreSQL requires it) | Install the CNPG operator first, or switch to postgresql.external |
| Settings changed but behavior unchanged (Kubernetes) | Pods still hold the old environment; env vars are read at start | Run a rollout restart of the affected Deployments |
App looks down but all pods are Ready (Kubernetes) | networkPolicy.enabled=true without ingressNamespace, so the Ingress-controller rule is absent and external API calls are blocked | Set networkPolicy.ingressNamespace to your Ingress controller's namespace; see Kubernetes operations |
Certificates never renew, offline agents stay active (Kubernetes) | The certops worker CronJob is missing or disabled | kubectl get cronjobs -n tokentimer should list tokentimer-certops; check worker.cronjobs.certops.enabled |
Uninstalling
# Docker Compose (keeps data)
docker compose down
# Delete database volumes only after preserving a recovery backup:
# docker compose down -v
# Kubernetes: verify a separate recovery backup first.
# Uninstall can delete the CloudNativePG Cluster and its database storage.
helm uninstall tokentimer -n tokentimer
Next steps
Check your first alert, then import inventory or connect an integration.