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 ASP.NET Core environment variables that override appsettings.json.

Variable	Default	Description
`Server__Name`	My EchoHub Server	Display name for your server
`Server__Description`	A self-hosted EchoHub chat server	Server description
`Server__PublicServer`	`false`	List on the public directory
`Server__PublicHost`	(empty)	Public address for the directory listing
`Server__Admins__0`	(empty)	Admin username (use `__1`, `__2` for more)
`Jwt__Secret`	(auto-generated)	JWT signing key. Auto-generated on first run
`Encryption__Key`	(auto-generated)	AES encryption key. Auto-generated on first run
`Encryption__EncryptDatabase`	`false`	Encrypt message content in the database
`Storage__CleanupIntervalHours`	`1`	How often to clean expired uploads
`Storage__RetentionDays`	`30`	Days to keep uploaded files
`Irc__Enabled`	`false`	Enable the IRC gateway
`Irc__Port`	`6667`	IRC plain-text port
`Irc__TlsEnabled`	`false`	Enable IRC over TLS
`Irc__TlsPort`	`6697`	IRC TLS port
`Irc__ServerName`	`echohub`	IRC server name shown to clients
`Irc__Motd`	Welcome to EchoHub IRC Gateway!	Message of the day
`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