Docker

Quick Start

cp .env.example .env        # create your config
docker compose up -d         # start the server

On first run the server automatically generates JWT and encryption keys, creates the database, and seeds a #general channel. Connect with the EchoHub client to http://localhost:5000.

Using a Pre-built Image

Instead of building locally, you can pull from GHCR. In docker-compose.yml, replace the build block:

services:
  echohub-server:
    image: ghcr.io/huebyte/echohub-server:latest
    # build:
    #   context: ./src
    #   dockerfile: EchoHub.Server/Dockerfile

Configuration

All settings are configured through the .env file. These are environment variables that override appsettings.json — the __ (double underscore) maps to JSON nesting levels. For example, Server__Name overrides the Server:Name key in appsettings.json.

See the Configuration guide for the full reference of all available settings and how the override hierarchy works.

Common Docker-relevant variables:

Variable	Default	Description
`Server__Name`	My EchoHub Server	Display name for your server
`Server__Admins__0`	(empty)	Admin username (use `__1`, `__2` for more)
`Irc__Enabled`	`false`	Enable the IRC gateway
`Serilog__MinimumLevel__Default`	`Information`	Log level (`Debug`, `Warning`, etc.)

Persistent Data

All server state lives in a single Docker volume mounted at /app/data:

/app/data/
├── appsettings.json   # generated config with JWT/encryption keys
├── echohub.db         # SQLite database
├── uploads/           # uploaded files and avatars
└── logs/              # rolling log files (14-day retention)

Backup

# stop the server to ensure a consistent snapshot
docker compose stop
# copy the data volume to a local directory
docker cp echohub-server:/app/data ./backup
docker compose start

IRC Gateway

To enable IRC, set these in your .env:

Irc__Enabled=true

Then uncomment the port in docker-compose.yml:

ports:
  - "5000:5000"
  - "6697:6697"   # IRC (TLS encrypted, preferred)

For TLS, also set:

Irc__TlsEnabled=true
Irc__TlsCertPath=/app/data/cert.pfx
Irc__TlsCertPassword=your_password

Mount your certificate into the data volume or bind-mount it directly.

IRC users must have an existing EchoHub account. See Getting Started for client connection examples.

Updating

# if using pre-built images
docker compose pull
docker compose up -d

# if building locally
docker compose build
docker compose up -d

Data persists across updates since it lives in the named volume.

Troubleshooting

Port already in use -- Another process is using port 5000. Change the host port in docker-compose.yml:

ports:
  - "8080:5000"   # access via http://localhost:8080

Permission denied on volume -- The container runs as a non-root echohub user (UID 999). If using bind mounts instead of named volumes, ensure the directory is writable.

View logs -- Check the container output:

docker compose logs -f echohub-server

File-based logs are also available inside the volume at /app/data/logs/.

Table of Contents