Server Installation

Production deployment of Holt using Docker for optimal performance and security. The Keel backend runs as a FastAPI app served by uvicorn inside a python:3.13-slim container, behind NGINX.

For development installation, use Development Installation instead.

Prerequisites

  • Docker (recommended: Ubuntu with Docker CE or Windows with Docker Desktop)
  • Git
  • SSL certificates for HTTPS (production requirement)

Installation Steps

1. Create a directory for Holt and navigate to it

mkdir Holt
cd Holt

2. Install Docker

Linux:

curl -sSL https://get.docker.com/ | bash

In restricted networks, use http_proxy and https_proxy environment variables to install Docker

3. Clone the Repository

git clone https://github.com/holt-chat/keel.git

If git is not found, Install git on Ubuntu using: apt install git

4. (Optional but recommended) Clone the Shore (Frontend) Repository

To also host the Frontend with the Backend clone the Shore (Frontend) Repository:

git clone https://github.com/holt-chat/shore.git

5. Navigate to Keel (Backend) Directory

cd keel

6. Create Configuration File

Create an empty config.toml file (required for Docker to mount it as a file):

Linux:

touch config.toml

Windows:

type nul > config.toml

7. Generate Configuration

Run the Keel backend to create a config file:

docker compose run --build --rm keel

8. Configuration

Open config.toml with a text editor:

Linux:

nano config.toml

Windows:

notepad config.toml

When using Docker to run the Holt server, don’t change the port in config.toml, instead, create a .env file with content like this PORT=YOUR PORT (replace YOUR PORT with your port)

If you have set a URI Prefix, you have to also set it in the docker-compose.yml file health check URL for health check to work properly

It’s highly recommended that you change the port in environments where internet censorship exists

9. SSL Certificates

SSL certificates are required for production use. HTTP is unsupported due to WebCrypto API requirements. (localhost will still work normally on http)

Place your SSL certificates in the certs directory:

  • cert.pem - Your SSL certificate
  • key.pem - Your private key

For detailed instructions on obtaining and configuring SSL certificates, including automatic setup with Let’s Encrypt and certbot, see SSL Certificates.

10. Deploy

Start the services:

docker compose up -d --build

Wait for the build to complete. You can access it at https://your-domain:port/uri-prefix-if-set/

Management Commands

Update

To update the installation:

git pull
docker compose up -d --build

Shutdown

To shut down all services:

docker compose down

Start (without rebuilding)

To start without rebuilding/updating:

docker compose up -d

CLI

To use it:

docker compose run --rm keel python cli.py