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
- 01
install.sh --check lists problems
The server install checks
eventier.envbefore it changes anything. Each line names a setting to fix, and nothing is installed until the list is empty.NEXT_PUBLIC_APP_URLmust be the full https address people openDATABASE_URLmust start withpostgresql://and hold no placeholder such as<password>- With
EVENTIER_BUNDLED_POSTGRES=true,POSTGRES_PASSWORDmust be set - With
EMAIL_DELIVERY_MODE=smtp,SMTP_HOSTandSMTP_FROMare required. Withauto,SMTP_FROMis required onceSMTP_HOSTis set SMS_PROVIDERmust beoff,sns(with the AWS settings) orwebhook(withSMS_WEBHOOK_URLandSMS_WEBHOOK_SECRET)- With scanning on,
CLAMAV_HOSTandCLAMAV_PORTmust point at clamd - A blank secret such as
SECRET_ENCRYPTION_KEY: restore it from your copy of this install'seventier.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 - 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" - 03
EvenTier doesn't start
The process stopped or never opened its port. The log says why. On a server,
install.shends with “did not answer … within two minutes” and names the command to read it.- Docker Compose refuses to start while
EVENTIER_DOMAINis blank - The database must answer: check
DATABASE_URL, and on Docker Compose that the postgres service is healthy - Kubernetes: each pod runs the
migrateinit container before the app; a failure there stops the pod - An
errorline 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 - Docker Compose refuses to start while
- 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-configerror 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_KEYon 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_URLsets the address. Docker Compose builds it fromEVENTIER_DOMAIN, Kubernetes fromapp.url
Find the errorbash docker compose logs app | grep security-config journalctl -u eventier | grep security-config - 05
The health check fails
/api/health/readyanswers 503 until the database answers and every migration in this release is applied. WithMETRICS_TOKEN, the answer lists each check./api/health/liveonly says the process runs; use it for livenessmigrationssays “pending: …”: run the migrate step for your path (see the upgrade problems below)migrationssays “failed: …”: a migration stopped partway; restore your pre-upgrade backup and roll back?require=workeralso fails when the background worker's heartbeat is more than 180 seconds old?require=scanneralso fails while clamd doesn't answer/api/healthadds storage, outbox,secret_key,smtp,email_sender,app_urlandconfig
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 - 06
HTTPS fails on an internal hostname (Docker Compose)
The bundled Caddy gets a Let's Encrypt certificate, which needs
EVENTIER_DOMAINto resolve to the host from the public internet, with ports 80 and 443 reachable.- For a name only reachable inside your network, add
tls internalto the site block and trust Caddy's local certificate authority on your clients - Or point
tlsat your own certificate and key
- {$EVENTIER_DOMAIN} {
- tls internal
- For a name only reachable inside your network, add
- 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_HOPSsays (default 1). With the wrong count, no address can be read.- The log has a
client-ipwarning: X-Forwarded-For has fewer hops thanTRUSTED_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 - The log has a
- 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) orsecrets.yaml(Kubernetes) - A wrong token gets “That setup token does not match this installation.”
- Once an organization exists,
/get-startedsends you to/loginfor 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, orautowith noSMTP_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 - The token is
- 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-alerterror 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
- Admin → Billing → Self-hosted license
- Install or replace license key → paste the license file's text → Install license
- From 14 days before expiry, the log carries a
- 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_KEYchanged after the license was installed; put the original key backCLOCK_ROLLBACK_DETECTED: the server clock went backwards; correct the timeUNKNOWN_KID: the license was signed with a newer key; upgrade EvenTier
- 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/readyanswers 503.- Docker Compose: run
docker compose run --rm migratebeforedocker compose up -d, exactly as written - Adding a
--profileflag replacesCOMPOSE_PROFILES, so the bundled database is not started - Kubernetes: read the
migrateinit container's log; don't pass--reuse-valuestohelm upgrade, which keeps the old image digest - Server:
install.shapplies migrations and stops before switching/opt/eventier/currentif 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 - Docker Compose: run
- 12
Integrations, SSO or MFA stop working after a settings change
SECRET_ENCRYPTION_KEYencrypts 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_keycheck of/api/healthsays “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-upgradeoreventier.env.before-upgrade, then restart - Keep the first bundle's settings file for the life of the install
- The
- 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
.envin the bundle folder, then rundocker 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 upgradewith it - Kubernetes: after changing
secrets.yaml, apply it and runkubectl rollout restart deployment/eventier deployment/eventier-worker - Kubernetes: a name set in both
env.configand 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 - Docker Compose: edit
- 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_PROVIDERtoopenai_compatiblewithAI_BASE_URL, or tobedrockwithAWS_REGION - Any other
AI_EMBEDDING_PROVIDERvalue 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_MODELbefore 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 - Every bundle sets
- 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_DAYSthat isn't a whole number of days orunlimitedis ignored, and the change log is kept for good- The same applies to
AUTH_AUDIT_RETENTION_DAYSandSECURITY_AUDIT_RETENTION_DAYS TRUSTED_PROXY_HOPSoutside 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 unsetorSMTP_FROM is unset: email fails until each is setNEXT_PUBLIC_APP_URL is unset: links in email fall back toNEXTAUTH_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.
| Code | Meaning | What to do |
|---|---|---|
| EXPIRED_GRACE | Expired, within the 14-day grace period | Install a renewed license; agents can't be added meanwhile |
| EXPIRED | Expired, grace period over | Install a renewed license |
| REVOKED · REVOKED_BY_CRL | Revoked by EvenTier | Contact EvenTier support for a new license |
| ORG_MISMATCH | Issued for a different organization | Check the organization slug on the license |
| EDITION_MISMATCH | A cloud-edition key | Use a self-hosted license |
| NOT_YET_ACTIVE | Its start date is in the future | Wait; it starts working on that date |
| SIGNATURE_INVALID · FORMAT_INVALID · CLAIMS_INCOMPLETE | The key text is altered, incomplete or corrupted | Paste the whole file again, or ask for it to be issued again |
| UNKNOWN_KID | Signed with a key this release doesn't trust | Upgrade EvenTier |
| DECRYPT_FAILED | The stored license can't be decrypted | Restore the original SECRET_ENCRYPTION_KEY |
| CLOCK_ROLLBACK_DETECTED | The system time went backwards | Correct the server clock |
| CRL_ROLLBACK_DETECTED | This release has an older revocation list than one already applied | Upgrade to the current release |
| INSTANCE_FINGERPRINT_MISMATCH | Bound to a different instance | Ask 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.