Skip to main content

Self-hosted installation

Self-hosted Evercom runs from Docker images published to GitHub Container Registry. You do not need the application source repositories on the server.

Before you start​

Prepare:

  • a Linux server with Docker and Docker Compose;
  • a domain pointed to the server;
  • a signed Evercom license key;
  • the Evercom license public key;
  • an admin email for the first workspace owner.
  • an admin password for the first workspace owner.

Create DNS records for the domains you plan to use. The default self-hosted layout keeps customer traffic on one primary domain and uses paths for API, webhooks, realtime, and the widget:

example.com
app.example.com
cdn.example.com
help.example.com
knowledge.example.com
mcp.example.com

The primary domain serves these public paths:

https://example.com/api
https://example.com/webhooks/v1
wss://example.com/ws
https://example.com/widget.js
https://example.com/{workspace-code}.js
https://example.com/widget/v1

https://example.com/webhooks/v1 must be reachable from Telegram, VK, email bridges, and other providers. Evercom registers provider callbacks against that public origin.

Install​

Download the deployment bundle provided by Evercom and run the installer:

tar -xzf evercom-self-hosted.tar.gz
cd evercom-self-hosted
make self-hosted-install

The installer asks for the base domain, public URL scheme, webhook origin, TLS settings, license data, first admin email, and first admin password. It creates .env, nginx routes, browser runtime config, and Docker Compose files for the local installation.

When you choose HTTPS, the installer starts Caddy in front of nginx. Caddy obtains and renews certificates automatically, so ports 80 and 443 must be open and pointed at the server.

To generate files without starting containers:

./scripts/install-self-hosted.sh --no-start

To start an already generated install:

make self-hosted-images-up

What the installer runs​

The self-hosted stack starts these public GHCR images:

ghcr.io/evercomapp/evercom/backend:latest
ghcr.io/evercomapp/evercom/app-web:latest
ghcr.io/evercomapp/evercom/widget:latest
ghcr.io/evercomapp/evercom/help:latest
ghcr.io/evercomapp/evercom/knowledge:latest

It also starts Postgres, Redis, Kafka, MinIO, Meilisearch, Ollama, Mailpit, and nginx. SaaS platform routes are disabled in self-hosted installs.

Verify​

After startup, check the containers:

docker compose -f docker-compose.self-hosted.images.yml -f docker-compose.self-hosted.generated.yml ps

Then check the public routes:

make self-hosted-smoke

Open https://app.example.com and sign in with the admin account from the installer.

Updating​

Back up, pull the latest images, apply migrations, restart public runtimes, roll workers, and run smoke checks:

make self-hosted-upgrade

The backend migrations are copied from the backend image and applied before the runtime services start. Worker services are updated with a short rolling restart: the upgrade script starts a second replica, waits until it is running, stops the previous replica with a graceful timeout, then scales back to one. Realtime websocket clients may reconnect during the public runtime restart.

Backups​

Create a maintenance backup:

make self-hosted-backup

The backup contains a Postgres dump, MinIO object data, and generated config. Store it encrypted because it contains customer data and secrets.