Install Enterprise
Enterprise is delivered as prebuilt images and a customer install bundle. Prepare the package below, then choose Docker Compose or Kubernetes with Helm. No source checkout or build toolchain is required.
What you receive from TokenTimer
When your enterprise license is issued, support@tokentimer.ch delivers a
single secure package containing:
| Item | File / format | Purpose |
|---|---|---|
| License | <your-id>.license.key (JWT) | Paste into .env as TT_LICENSE_KEY, import from the dashboard after boot, and/or mount as a file (see the Compose license file overlay below) |
| Registry robot credentials | <your-id>.creds.txt | Pulls images and the Helm chart from harbor.tokentimer.ch; details in Registry access |
| Install bundle | tokentimer-enterprise-<version>.tar.gz | The delivery tarball: Compose file, env template, Helm value examples, and documentation |
The install bundle (also called the delivery tarball) contains everything you need to deploy. For upgrades, you can either request a refreshed package or pull the latest bundle yourself from Harbor (see Upgrade Enterprise).
Prerequisites
| Path | Requirements |
|---|---|
| Docker Compose | Docker 24+ with the Compose plugin |
| Kubernetes (Helm) | Helm 3.14+, Kubernetes 1.29+, and the CloudNativePG operator if you use the bundled PostgreSQL |
| All paths | Outbound HTTPS to harbor.tokentimer.ch:443 from any node that will pull images or charts |
You do not need Node.js, pnpm, source code, or any local image build.
Step 0: Authenticate to the TokenTimer registry
Registry authentication covers image pulls, the Helm chart, and (optionally)
future bundle versions. Your robot username and token are in the
<your-id>.creds.txt delivery file; see Registry access
for the credential format, scope, and rotation.
docker login harbor.tokentimer.ch \
-u 'robot$tokentimer-enterprise+<company>-<your-id>' \
-p '<your-robot-token>'
For Kubernetes, you also create a pull secret in the install namespace (see Helm installation).
Step 1: Extract the install bundle
mkdir tokentimer && cd tokentimer
read -r -p 'Install bundle path: ' ENTERPRISE_BUNDLE
tar -xzf "$ENTERPRISE_BUNDLE"
ls
You should see: QUICKSTART.md VERSION LICENSE compose/ helm/ docs/
The bundle contains:
| Path | Contents |
|---|---|
VERSION | Bundle version, build time, source commit |
QUICKSTART.md | Offline copy of the install walkthrough |
LICENSE | BSL 1.1 product license terms |
compose/docker-compose.yml | Production Docker Compose file |
compose/docker-compose.license-file.yml | Optional bind-mount helper for a file-based license JWT |
compose/docker-compose.sso.yml | Optional SSO overlay (bootstrap manifest and keyring) |
compose/.env.example | Environment template (full reference) |
compose/.env.sso-basic.example | SSO secret env var template (OIDC and SAML examples) |
compose/sso-providers.README.md and sso-providers.*.example.json | SSO bootstrap manifest reference and examples |
helm/README.md, helm/values.yaml, helm/examples/ | Chart install guide, enterprise chart defaults, and scenario starter values files |
docs/ | Offline copies of the configuration, authentication, architecture, registry, and SSO guides, plus a docs/core/ subfolder with the Core references (database, SMTP, alerts) |
Choose a method
- Docker Compose: one host, using the supplied
compose/files. - Kubernetes with Helm: the Enterprise chart includes its matching Core subchart.
Then check your first asset and alert. For SSO-only bootstrap, follow Authentication before first startup.
Previous section links
Option 1: Docker Compose (fastest)
Continue in the Compose guide.
a. Configure .env
Continue in Configure .env.
b. Supply the license (pick one or combine)
Continue in Supply the license.
c. Start the stack
Continue in Start the stack.
d. Verify
Continue in Verify.
Option 2: Kubernetes (Helm)
Continue in the Helm guide.
a. Create the pull secret
Continue in Create the pull secret.
b. Authenticate Helm to Harbor
Continue in Authenticate Helm to Harbor.
c. Create the license secret (optional)
Continue in Create the license secret.
d. Pick a starter values file and customize
Continue in Pick a starter values file.
e. Install
Continue in Install.
f. Verify
Continue in Verify.
Scenario values files
Continue in Scenario values files.
License lifecycle
Continue in License lifecycle and Configuration: License.
Upgrading
Continue in the Upgrade guide.
Pull the new bundle (optional, recommended)
Continue in Retrieve the target bundle.
Docker Compose
Continue in Upgrade: Docker Compose.
Helm
Continue in Upgrade: Helm.
Registry token renewal
Continue in Registry token renewal.
Previous deployment, scenario-values, license, and upgrade sections now live in Compose, Helm, configuration, and Upgrade.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
unauthorized: authentication required on docker pull | Token expired or wrong robot prefix | Confirm the full username (robot$tokentimer-enterprise+<company>-<id>) and re-login; see Registry access |
| API fails at startup with a license error | Invalid or corrupt license JWT | Re-import from System Settings > License or fix TT_LICENSE_KEY / the mounted license file |
Login succeeds but immediately redirected to /login | Cookie blocked because Secure is set on plain HTTP | Either run behind HTTPS or set SESSION_COOKIE_SECURE_LOCALHOST_OVERRIDE=true for local testing |
| AWS / Azure / GCP / Vault tiles greyed out in the import modal | License missing the entitlement | Log in and check System Settings > License (or request a re-issued license) |
/auth/oidc/<slug> redirects to /login?error=license_oidc_required | License does not include feature:oidc | Same as above |
ImagePullBackOff in Kubernetes | Pull secret missing or in the wrong namespace | See Registry access, troubleshooting |
SSO redirect URI shows http://localhost:4000/... | tokentimer.config.apiUrl left at chart default | Set apiUrl (and baseUrl) to your public HTTPS origins, run helm upgrade, restart the API if you only changed bootstrap secrets outside Helm |
Next steps
First asset and alert check, SSO setup, and Upgrade Enterprise.