Install KasaDESK and complete the first run
KasaDESK is self-hosted. Each organization runs one installation. That installation serves several brands or products, which KasaDESK calls workspaces. This chapter takes you from an empty Linux host to a signed-in owner with a first workspace and workgroup.
All hostnames below are placeholders. Replace support.example.com with the HTTPS hostname your staff and customers will use.
What you needLink to this section
| Item | Requirement |
|---|---|
| Host | A Linux VM (x86_64 or arm64). Plan for at least 2 vCPU, 4 GB RAM and 40 GB disk, plus more disk for backups and any WAL archive. Expose only SSH, 80 and 443 to the internet. |
| Container runtime | Docker Engine 24 or later with the Compose plugin v2.20 or later. |
| Domain and TLS | A DNS name pointing at the host, and a TLS-terminating reverse proxy (nginx, Caddy, Traefik or a cloud load balancer). |
| Secrets | A database password and a 32-byte encryption key, generated on the host and stored in your own secret manager. |
| Database | PostgreSQL. The supplied Compose file runs PostgreSQL 18 by default in its own container with a persistent volume. |
| Outbound network | TLS egress to any messaging, email, AI or push providers you plan to connect. |
The deployment procedure uses the Docker Compose definition shipped with the release (deploy/docker-compose.yml). One application image contains the API, background workers, the staff console and the customer chat widget. The console, /api/v1 and /widget/* are served from the same origin.
Understand what runsLink to this section
| Service | Purpose | Exposure |
|---|---|---|
db |
PostgreSQL with the pgdata volume. |
Container network only. |
migrate |
One-shot migrate up. It must exit successfully before the app starts. |
None. |
app |
API, console, widget, live update streams and workers, listening on port 4000. | Published on 127.0.0.1:4000 only. Your reverse proxy forwards to it. |
| Metrics listener | /metrics, /healthz and /readyz on port 9464. |
Container network only. Never publish it. |
backup, backup-scheduler |
Optional profiles for scheduled backups. | None. See Back up and restore. |
Persistent volumes: pgdata (database), storage (attachments and private runtime files at /var/lib/kasadesk/storage) and backups. Keep these volumes on durable disk. Chat attachments can also be sent to S3-compatible storage later from Admin → Settings → Storage.
Configure the environmentLink to this section
From the release checkout, copy the template and protect it:
cp deploy/.env.example deploy/.env
chmod 600 deploy/.envFill in the required values. Generate secrets on the host:
openssl rand -hex 24 # POSTGRES_PASSWORD (URL-safe)
openssl rand -base64 32 # ENCRYPTION_KEY
openssl rand -hex 24 # METRICS_TOKEN| Variable | Required | Notes |
|---|---|---|
POSTGRES_PASSWORD |
Yes | Compose builds the database URL from it. |
ENCRYPTION_KEY |
Yes | 32 bytes, base64. Seals channel credentials, widget identity secrets, webhook secrets and staff authenticator seeds. |
PUBLIC_API_ORIGIN |
Yes | The public https:// origin, no trailing slash, for example https://support.example.com. Used for public widget URLs and provider webhook URLs. |
AGENT_CONSOLE_ORIGIN |
Yes | The same origin when the bundled server serves the console, which is the default. Invitation links use this origin. |
METRICS_TOKEN |
Recommended | Bearer token for /metrics. |
ENCRYPTION_KEY_PREVIOUS |
During key rotation | The old key, so existing secrets still open. |
RUN_WORKERS |
Optional | Default true. Keep workers on in exactly one process. |
SESSION_TTL_HOURS |
Optional | Staff session lifetime, default 12. |
Compose stops with a message if a required value is empty. DATABASE_URL, ENCRYPTION_KEY, ENCRYPTION_KEY_PREVIOUS and METRICS_TOKEN also accept a <NAME>_FILE form that points to a mounted secret file.
Key custody comes first. Store
ENCRYPTION_KEYin a secret manager before the first start and record its key ID with the dates it is in use. The key is never included in backups. If it is lost, every staff member must re-enroll their authenticator and every channel secret must be re-entered. See Protect the encryption key.
Never commit deploy/.env and never bake secrets into an image.
Start the stackLink to this section
docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d --build --wait
docker compose --env-file deploy/.env -f deploy/docker-compose.yml psup starts db, waits until PostgreSQL is ready, runs migrate, then starts app. --wait returns once app reports healthy, which means /readyz returned 200. Each migration runs in its own transaction.
Put HTTPS and a reverse proxy in frontLink to this section
The application speaks plain HTTP on 127.0.0.1:4000. Terminate TLS at your proxy.
- In production the server trusts exactly one proxy hop for client IP addresses, which login rate limiting and the audit log use. Do not expose port 4000 directly.
- Staff session cookies are
Secure, so the console works only over HTTPS. Plainhttp://localhostis suitable only for loopback tests. - Two live update streams need buffering off and long read timeouts:
GET /api/v1/inbox/events(staff) andGET /api/v1/widget/events(customers). The server sends a keep-alive every 20 seconds. - The customer stream carries its session token in the query string. Do not log query strings at the proxy, or redact
token=. - Block
/metricsat the public proxy. The application port also answers/metrics(with401unless the request carries theMETRICS_TOKENbearer token, or404when no token is set), so the proxy rule is what keeps it off the public hostname. Scrape the metrics listener from the container network instead. - Allow request bodies of about 15 MB. Attachments are capped at 10 MB.
- Forward
X-Forwarded-For,X-Forwarded-Protoand a request ID so proxy and application logs correlate.
Example nginx locations, to adapt to your own proxy configuration:
location ~* ^/metrics/?$ {
return 404;
}
location ~ ^/api/v1/(inbox|widget)/events$ {
proxy_pass http://127.0.0.1:4000;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 1h;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Request-Id $request_id;
}
location / {
proxy_pass http://127.0.0.1:4000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Request-Id $request_id;
client_max_body_size 15m;
}Serve the console from the root of a dedicated origin. The console uses root-relative paths, and installable desktop app support, browser push and the staff phone app all expect the console and /api/v1 on the same HTTPS origin.
Check health and readinessLink to this section
curl -fsS https://support.example.com/healthz
curl -fsS https://support.example.com/readyz/healthzis liveness only. It returns{"ok":true}whenever the process answers./readyzreturns200 {"status":"ready",…}or503 {"status":"not_ready","reason":"…"}. It checks the database, migrations, the realtime listener and worker heartbeats.
| Reason | Meaning | First action |
|---|---|---|
db_unreachable |
The database did not answer within 2 seconds. | Check the db service and credentials. |
migrations_pending |
The app started without the migrate step. | docker compose --env-file deploy/.env -f deploy/docker-compose.yml run --rm migrate |
migrations_mismatch |
An applied migration differs from the shipped file. | Make sure the image matches the release you migrated with. |
realtime_down |
The PostgreSQL notification round trip failed. Live updates are affected. | Check database connectivity and load. |
workers_stale |
A background worker has not completed a run in time. | Read the app log line readiness failing. |
shutting_down |
The process received a stop signal and is draining. | Expected during restarts. |
Create the owner accountLink to this section
Issue a one-time setup code from the app container:
docker compose --env-file deploy/.env -f deploy/docker-compose.yml exec app node dist/cli.js bootstrap-tokenThe code is single use and valid for 60 minutes. Treat it like a password and do not paste it into tickets or chat logs. Issuing a new code revokes any unredeemed code. Once the installation is initialized, the command refuses to issue codes.
Open https://support.example.com/ in a browser. A fresh installation redirects to /setup, titled Set up KasaDESK. It confirms Database connected and migrated and Encryption key configured. Then:
- Authorize. Enter the code in One-time setup code and choose Continue.
- Owner account (step 2 of 5). Enter Full name, Login email and Password, then choose Create owner account.
- Secure account (step 3 of 5). Scan the QR code with an authenticator app (TOTP) and confirm a code. Save any recovery codes offered in your password manager.
- Organization (step 4 of 5). Enter Organization name and Time zone (IANA), for example
Africa/Accra, then Save and continue. - Review (step 5 of 5). Choose Finish setup. You return to the sign-in page.
Setup cannot be run again after it finishes. The wizard does not create a workspace. You create brands and workgroups after you sign in.
Create the first workspace and workgroupLink to this section
- Sign in with the owner email, password and a current authenticator code. Owners and admins land on Overview at
/admin. - The checklist shows Workspace and workgroup as Required. Choose Configure. This opens Admin → Settings → Workspaces & Teams.
- Under Add workspace, enter a Brand name, optionally pick an Inbox badge colour, and choose Create workspace.
- In the new workspace, type a name in New workgroup in Brand and choose Add. The owner joins this first workgroup automatically.
- Return to Overview. The checklist item now shows Done.
Continue with Workspaces, roles and routing to add staff and further brands, then Channels and provider setup to connect customer channels.
Run first smoke checksLink to this section
Before inviting staff or announcing the installation, confirm:
-
/healthzreturns 200 and/readyzreturnsreadythrough the public HTTPS hostname. -
/metricsreturns 404 through the public hostname. - The owner can sign out, sign back in with password and authenticator, and land on
/admin. - A Web Chat channel for the first workspace accepts a test message from an allowlisted test page, and the message appears in the inbox. See Website embed.
- A reply from the inbox reaches the test page, and an internal note does not.
- One
backup runcompletes andlast-run.jsonreportsok. See Back up and restore. - After
docker compose … downandup --wait, the owner can still sign in and the test conversation and attachments are still present.
Use synthetic customer names and test accounts for these checks.
Evaluate from sourceLink to this section
For local evaluation without containers, the release README describes running from source with Node.js 22.13 or later, pnpm and PostgreSQL 15 or later. That path uses development defaults and plain HTTP on localhost. Use the Compose deployment above for any installation that real staff or customers will use.