Lichen Docker Compose Deployment #

Deploy lichen to any VPS with Docker.

Quick start #

1. Copy this directory to your server
2. Create .env from the example:

   cp .env.example .env
   # edit .env — set DOMAIN and ADMIN_PASSWORD
   

3. Point your domain's DNS A record to the server IP
4. Start:

   docker compose up -d
   

5. Caddy automatically obtains a TLS certificate via Let's Encrypt

Custom binary (optional) #

To run a custom-built lichen instead of the image default:

mkdir -p bin
# build locally and copy, or scp from your dev machine:
scp your-machine:path/to/target/release/lichen bin/
docker compose restart app

The entrypoint checks for bin/lichen and uses it for both admin commands and hosted startup (lichen server --multi --root-dir /data run). Update entrypoint.sh together with the binary; the image fallback must also supply lichen. Remove the file and restart to revert to the standard image.

tmpfs for preview builds (optional) #

Lichen uses /tmp for temporary preview builds. You can mount it as tmpfs (RAM-backed) for faster previews and reduced SSD wear:

docker compose -f docker-compose.yml -f docker-compose.tmpfs.yml up -d

Set LICHEN_TMPFS_SIZE in .env to adjust the size (default: 512m):

LICHEN_TMPFS_SIZE=1g

Verify it's working inside the container:

docker compose exec app mount | grep /tmp
# should show: tmpfs on /tmp type tmpfs ...

Files #

• docker-compose.yml — service definitions (app + caddy)
• docker-compose.tmpfs.yml — optional override to mount /tmp as tmpfs
• entrypoint.sh — startup script (admin user, custom binary check)
• Caddyfile — HTTPS with on-demand TLS via Let's Encrypt
• .env.example — configuration template
• bin/ — drop a custom lichen binary here (gitignored)