Installation

Installation

The easiest way to run a Ceili server is with Docker. The steps below are aimed at a self-hosted deployment and cover the minimum configuration required to get the app running locally or on a VM.

Requirements

Before you begin, make sure you have:

• Docker 24 or later
• Docker Compose v2
• A server or local machine with at least 2 GB of RAM available
• A domain name or local hostname for the service
• A secure secret for app signing and session encryption

1. Prepare a deployment directory

Create a working directory for the Ceili deployment and enter it:

mkdir ceili
cd ceili

2. Create a configuration file

Create a .env file with the required runtime settings:

cat <<'EOF' > .env
CEILI_ENV=production
CEILI_HOST=localhost
CEILI_PORT=8080
CEILI_SECRET_KEY=replace-with-a-long-random-secret
CEILI_DATABASE_URL=postgres://ceili:ceili@db:5432/ceili
EOF

If you are deploying publicly, change CEILI_HOST to the hostname or domain you want clients to use.

3. Start Ceili with Docker Compose

Create a docker-compose.yml file:

version: "3.9"

services:
  ceili:
    image: ceili/server:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      CEILI_ENV: ${CEILI_ENV}
      CEILI_HOST: ${CEILI_HOST}
      CEILI_PORT: ${CEILI_PORT}
      CEILI_SECRET_KEY: ${CEILI_SECRET_KEY}
      CEILI_DATABASE_URL: ${CEILI_DATABASE_URL}
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ceili
      POSTGRES_USER: ceili
      POSTGRES_PASSWORD: ceili
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Then start the service:

docker compose up -d

4. Verify the service

Check the running containers:

docker compose ps

Check the application health endpoint:

curl http://localhost:8080/health

A successful response should return a status indicating the service is running.

5. Create an initial admin account

Once the service is healthy, create your first administrative user. The exact command depends on your server image and version, but the usual pattern is:

docker compose exec ceili ceili admin create

If your deployment uses a different CLI entrypoint, consult the release notes or deployment scripts shipped with your version.

6. Next steps

After the app is up, you can:

• configure your custom domain and TLS termination
• set up account invitations and user policies
• connect webhooks or extension integrations
• review the architecture, API, and extensions sections in this documentation

Production notes

For production deployments, you should also:

• use a managed database or encrypted volume
• configure reverse proxy settings with HTTPS
• rotate secrets regularly
• add monitoring, logs, and backups
• restrict admin access to trusted users

This installation path is intentionally simple and is meant to give you a working self-hosted Ceili deployment quickly.