Skip to content

Documentation

Self-hosted installs

Fixes for settings that fail the install check, a malware scanner that doesn't answer, an app that won't start or fails its health check, license and first-run setup problems, upgrades, semantic search and startup warnings.

Where
install.sh --check · /api/health/live · /api/health/ready · /get-started · Admin → Billing · Admin → Settings → Evee AI
Permission
Admin of the host, cluster or server · workspace administrator (license, Evee settings)
Updated
October 2026

Before you start

Each heading is a symptom, with the likely cause and the commands to check it.

Logs: docker compose logs app on Docker Compose, kubectl logs deployment/eventier -c web on Kubernetes, journalctl -u eventier on a server. Each line is JSON with a level, a source and a message.

/api/health/live answers 200 while the process runs. /api/health/ready answers 200 once the database answers and every migration in the release is applied, and 503 until then.

Set METRICS_TOKEN and send it as a bearer token to see each check and its message, from /api/health/ready and the fuller /api/health.

Settings are read at startup. After a change, run docker compose up -d, helm upgrade with your values file, or sudo systemctl restart eventier.

Problems and fixes

  1. 01

    install.sh --check lists problems

    The server install checks eventier.env before it changes anything. Each line names a setting to fix, and nothing is installed until the list is empty.

    • NEXT_PUBLIC_APP_URL must be the full https address people open
    • DATABASE_URL must start with postgresql:// and hold no placeholder such as <password>
    • With EVENTIER_BUNDLED_POSTGRES=true, POSTGRES_PASSWORD must be set
    • With EMAIL_DELIVERY_MODE=smtp, SMTP_HOST and SMTP_FROM are required. With auto, SMTP_FROM is required once SMTP_HOST is set
    • SMS_PROVIDER must be off, sns (with the AWS settings) or webhook (with SMS_WEBHOOK_URL and SMS_WEBHOOK_SECRET)
    • With scanning on, CLAMAV_HOST and CLAMAV_PORT must point at clamd
    • A blank secret such as SECRET_ENCRYPTION_KEY: restore it from your copy of this install's eventier.env
    • “could not be read”: quote values that contain spaces or < >, such as SMTP_FROM
    Run the checkbash
    # Before the first install, in the bundle folder
    ./install.sh --check
    
    # Once installed, it checks /etc/eventier/eventier.env, so use sudo
    sudo ./install.sh --check
  2. 02

    clamd does not answer

    Attachment malware scanning needs clamd. Until it answers, every upload is refused with “Attachment scanning is temporarily unavailable”.

    • clamd answers only after its first signature download, a few minutes after install; restart it once that is done
    • Server: clamd must listen on 127.0.0.1:3310
    • Docker Compose: the clamav service runs clamd; check its status and log
    • Give clamd 3 to 4 GB of memory
    • Air-gapped: clamd refuses to start without signature files, so copy them in first
    • Or run without scanning: ATTACHMENT_MALWARE_SCANNER=off (Kubernetes: clamav.enabled: false)
    Check and fixbash
    # Server (Ubuntu or Debian): listen on 127.0.0.1:3310, then restart
    printf 'TCPSocket 3310\nTCPAddr 127.0.0.1\n' | sudo tee -a /etc/clamav/clamd.conf
    sudo systemctl restart clamav-daemon
    
    # Docker Compose
    docker compose ps clamav
    docker compose logs --tail 50 clamav
    
    # Any path: 200 once clamd answers
    curl -sS "https://<your domain>/api/health/ready?require=scanner"
  3. 03

    EvenTier doesn't start

    The process stopped or never opened its port. The log says why. On a server, install.sh ends with “did not answer … within two minutes” and names the command to read it.

    • Docker Compose refuses to start while EVENTIER_DOMAIN is blank
    • The database must answer: check DATABASE_URL, and on Docker Compose that the postgres service is healthy
    • Kubernetes: each pod runs the migrate init container before the app; a failure there stops the pod
    • An error line at startup names the setting at fault
    Read the logbash
    # Server
    journalctl -u eventier -n 100
    
    # Docker Compose
    docker compose ps
    docker compose logs --tail 100 app
    
    # Kubernetes
    kubectl get pods
    kubectl logs deployment/eventier -c migrate
    kubectl logs deployment/eventier -c web --tail 100
  4. 04

    The app runs, but nobody can sign in

    A missing or reused secret, or an http address, stops sign-in while the rest of the app answers. The startup log has a security-config error that names it.

    • “Missing required production secrets: …”: set each one listed; every bundle generates them
    • Each secret must be its own value: a placeholder, or a value shared with another secret, is refused
    • Restore secrets from this install's first settings file. Never replace SECRET_ENCRYPTION_KEY on an install that holds data
    • “NEXTAUTH_URL must use https://”: session cookies are Secure, so sign-in over plain HTTP fails
    • Server: NEXT_PUBLIC_APP_URL sets the address. Docker Compose builds it from EVENTIER_DOMAIN, Kubernetes from app.url
    Find the errorbash
    docker compose logs app | grep security-config
    journalctl -u eventier | grep security-config
  5. 05

    The health check fails

    /api/health/ready answers 503 until the database answers and every migration in this release is applied. With METRICS_TOKEN, the answer lists each check.

    • /api/health/live only says the process runs; use it for liveness
    • migrations says “pending: …”: run the migrate step for your path (see the upgrade problems below)
    • migrations says “failed: …”: a migration stopped partway; restore your pre-upgrade backup and roll back
    • ?require=worker also fails when the background worker's heartbeat is more than 180 seconds old
    • ?require=scanner also fails while clamd doesn't answer
    • /api/health adds storage, outbox, secret_key, smtp, email_sender, app_url and config
    Check each endpointbash
    curl -sS https://<your domain>/api/health/live
    curl -sS https://<your domain>/api/health/ready
    
    # With METRICS_TOKEN set: every check and its message
    curl -sS -H "Authorization: Bearer $METRICS_TOKEN" https://<your domain>/api/health/ready
    curl -sS -H "Authorization: Bearer $METRICS_TOKEN" https://<your domain>/api/health
  6. 06

    HTTPS fails on an internal hostname (Docker Compose)

    The bundled Caddy gets a Let's Encrypt certificate, which needs EVENTIER_DOMAIN to resolve to the host from the public internet, with ports 80 and 443 reachable.

    • For a name only reachable inside your network, add tls internal to the site block and trust Caddy's local certificate authority on your clients
    • Or point tls at your own certificate and key
    1. {$EVENTIER_DOMAIN} {
    2. tls internal
  7. 07

    Sign-ins are refused or rate limited for everyone

    EvenTier reads each person's address from the X-Forwarded-For header, trusting as many proxies as TRUSTED_PROXY_HOPS says (default 1). With the wrong count, no address can be read.

    • The log has a client-ip warning: X-Forwarded-For has fewer hops than TRUSTED_PROXY_HOPS, so the client address is unresolved
    • Everyone then shares one rate limit, and a workspace with a login IP allowlist refuses sign-in
    • Count the proxies in front of the app that add to X-Forwarded-For: an ingress alone is 1
    • A value outside 1 to 10 is ignored with a warning, and 1 is used
    • Never expose the app without a proxy that sets X-Forwarded-For
    Settings file: two proxies that each add to X-Forwarded-Forbash
    TRUSTED_PROXY_HOPS=2
  8. 08

    The setup page asks for a token, or sends you to sign-in

    First-run setup is open only until the first organization exists, and it needs the install's setup token.

    • The token is EVENTIER_SETUP_TOKEN, in .env (Docker Compose), /etc/eventier/eventier.env (server) or secrets.yaml (Kubernetes)
    • A wrong token gets “That setup token does not match this installation.”
    • Once an organization exists, /get-started sends you to /login for good; everyone else joins by invitation, single sign-on (SSO) or SCIM provisioning
    • Setup emails the first administrator a code. If your mail settings would make that fail, the page says so
    • With email off (off, or auto with no SMTP_HOST), setup skips the code and the token alone applies
    Find the tokenbash
    # Docker Compose, in the bundle folder
    grep EVENTIER_SETUP_TOKEN .env
    
    # Server
    sudo grep EVENTIER_SETUP_TOKEN /etc/eventier/eventier.env
  9. 09

    The license expired

    An expired license keeps working for a 14-day grace period. After that, new requests and new agents pause until a valid license is installed.

    • From 14 days before expiry, the log carries a jobs.license-expiry-alert error with the days left
    • During the grace period, Admin → Billing shows the date it ends, and no agents can be added
    • After it, requesters see “This installation is not taking new requests until an administrator installs a valid license at Admin > Billing.”
    • After it, user CSV imports are refused too
    • Licenses issued for your account are under License in the account console, and the owner gets each one by email
    • Paste the license file's text on Admin → Billing and choose Install license; it is checked offline
    1. Admin → Billing → Self-hosted license
    2. Install or replace license key → paste the license file's text → Install license
  10. 10

    The license shows as invalid or revoked

    Admin → Billing shows the license status, the reason and a hint for the cause. The table below lists each status code.

    • Revocation reaches an install only through the list inside each release, so a revoked license stops at the first upgrade that carries it
    • A revoked or invalid license has no grace period
    • DECRYPT_FAILED: SECRET_ENCRYPTION_KEY changed after the license was installed; put the original key back
    • CLOCK_ROLLBACK_DETECTED: the server clock went backwards; correct the time
    • UNKNOWN_KID: the license was signed with a newer key; upgrade EvenTier
  11. 11

    An upgrade fails, or the app isn't ready after it

    The new release must apply its database changes before it serves. If they didn't run, or one failed, /api/health/ready answers 503.

    • Docker Compose: run docker compose run --rm migrate before docker compose up -d, exactly as written
    • Adding a --profile flag replaces COMPOSE_PROFILES, so the bundled database is not started
    • Kubernetes: read the migrate init container's log; don't pass --reuse-values to helm upgrade, which keeps the old image digest
    • Server: install.sh applies migrations and stops before switching /opt/eventier/current if they fail
    • A migration that failed partway: restore the backup from before the upgrade, then return to the previous release
    • Never replace the settings file with one from a new bundle download: it carries new secrets
    Run or inspect the migrationsbash
    # Docker Compose
    docker compose run --rm migrate
    
    # Kubernetes
    kubectl logs deployment/eventier -c migrate
    
    # Server: the install script's output, then the service log
    journalctl -u eventier -n 100
  12. 12

    Integrations, SSO or MFA stop working after a settings change

    SECRET_ENCRYPTION_KEY encrypts stored credentials. If it changed, for example because the settings file was replaced by a new bundle download, they can no longer be read.

    • The secret_key check of /api/health says “SECRET_ENCRYPTION_KEY cannot decrypt …”
    • Webhook deliveries stop with 0 attempts, and the license can show DECRYPT_FAILED
    • Put the original key back, for example from .env.before-upgrade or eventier.env.before-upgrade, then restart
    • Keep the first bundle's settings file for the life of the install
  13. 13

    A settings change has no effect

    Settings are read when the app starts, so each change needs a restart on its own path.

    • Docker Compose: edit .env in the bundle folder, then run docker compose up -d
    • Server: edit /etc/eventier/eventier.env, not the bundle's copy, then restart the service
    • Kubernetes: change your values file and run helm upgrade with it
    • Kubernetes: after changing secrets.yaml, apply it and run kubectl rollout restart deployment/eventier deployment/eventier-worker
    • Kubernetes: a name set in both env.config and the Secret takes the Secret's value
    Restart after a changebash
    # Docker Compose
    docker compose up -d
    
    # Server
    sudo systemctl restart eventier
    
    # Kubernetes
    helm upgrade eventier oci://ghcr.io/eventierio/charts/eventier --version <x.y.z> -f my-values.yaml
  14. 14

    Semantic search or Similar past tickets doesn't work

    Both need Evee turned on, an embedding provider and the Semantic search switch. Without them, search falls back to keywords and Similar past tickets stays empty.

    • Every bundle sets AI_DISABLED=true, which turns every AI feature off, embeddings included
    • Anthropic has no embeddings: set AI_EMBEDDING_PROVIDER to openai_compatible with AI_BASE_URL, or to bedrock with AWS_REGION
    • Any other AI_EMBEDDING_PROVIDER value leaves embeddings off
    • Restart, then turn on Semantic search and Similar past requests in Admin → Settings → Evee AI
    • New requests and published articles are embedded as they arrive; older ones in the background, up to 200 of each every 30 minutes
    • Admin → Settings → Evee AI shows how many published articles are indexed under Semantic search; Index now indexes the rest straight away
    • Similar past tickets lists only resolved or closed requests that aren't confidential
    • Choose AI_EMBEDDING_MODEL before you start: vectors from different models are never compared
    Settings file: chat on Anthropic, embeddings from a local Ollamabash
    AI_DISABLED=false
    AI_PROVIDER=anthropic
    ANTHROPIC_API_KEY=<your key>
    AI_EMBEDDING_PROVIDER=openai_compatible
    AI_BASE_URL=http://ollama.internal:11434/v1
    AI_EMBEDDING_MODEL=nomic-embed-text
  15. 15

    Warnings in the startup log

    At startup the app logs each setting it can't use, with what happens instead. Warnings don't stop the app.

    • AUDIT_RETENTION_DAYS that isn't a whole number of days or unlimited is ignored, and the change log is kept for good
    • The same applies to AUTH_AUDIT_RETENTION_DAYS and SECURITY_AUDIT_RETENTION_DAYS
    • TRUSTED_PROXY_HOPS outside 1 to 10: addresses are read as if it were 1
    • “Attachment malware scanning is turned off” and “Email is turned off”: expected when you chose those settings
    • SMTP_HOST is unset or SMTP_FROM is unset: email fails until each is set
    • NEXT_PUBLIC_APP_URL is unset: links in email fall back to NEXTAUTH_URL
    List the warningsbash
    docker compose logs app | grep '"level":"warn"'
    journalctl -u eventier | grep '"level":"warn"'

License status codes

Shown on Admin → Billing with each license problem.

CodeMeaningWhat to do
EXPIRED_GRACEExpired, within the 14-day grace periodInstall a renewed license; agents can't be added meanwhile
EXPIREDExpired, grace period overInstall a renewed license
REVOKED · REVOKED_BY_CRLRevoked by EvenTierContact EvenTier support for a new license
ORG_MISMATCHIssued for a different organizationCheck the organization slug on the license
EDITION_MISMATCHA cloud-edition keyUse a self-hosted license
NOT_YET_ACTIVEIts start date is in the futureWait; it starts working on that date
SIGNATURE_INVALID · FORMAT_INVALID · CLAIMS_INCOMPLETEThe key text is altered, incomplete or corruptedPaste the whole file again, or ask for it to be issued again
UNKNOWN_KIDSigned with a key this release doesn't trustUpgrade EvenTier
DECRYPT_FAILEDThe stored license can't be decryptedRestore the original SECRET_ENCRYPTION_KEY
CLOCK_ROLLBACK_DETECTEDThe system time went backwardsCorrect the server clock
CRL_ROLLBACK_DETECTEDThis release has an older revocation list than one already appliedUpgrade to the current release
INSTANCE_FINGERPRINT_MISMATCHBound to a different instanceAsk for it to be issued again if the install moved

Good to know

  • Point your uptime monitor at /api/health/ready?require=worker,scanner: it fails when the background worker stops or clamd stops answering.
  • Back up the settings file with the database. Without SECRET_ENCRYPTION_KEY, stored credentials can't be read.
  • Run upgrades on a staging install first.