Skip to content

Docker Compose Quickstart

This guide walks you through deploying openLogForge on a freshly installed Debian 13 (trixie) server using Docker Compose. The entire stack runs as two containers - no database server, no message broker, no additional services required.

Estimated time: 15-20 minutes.

System requirements

Resource Minimum Recommended
CPU 2 cores 4 cores
RAM 2 GB 4 GB
Disk 10 GB 20 GB
OS Debian 13 (trixie) x86_64 or arm64 -
Network Outbound internet (for Docker image pulls and git clone) -

openLogForge listens on port 80 by default. Make sure that port is open in your firewall.

Step 1 - Update the system

Log in as a user with sudo access and update the package index:

sudo apt update && sudo apt upgrade -y

Step 2 - Install Docker Engine

Debian 13 does not ship Docker Engine in its default repositories. Install it from Docker's official apt repository.

2.1 - Install prerequisites:

sudo apt install -y ca-certificates curl gnupg

2.2 - Add Docker's GPG key:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

2.3 - Add the Docker apt repository:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.4 - Install Docker Engine and the Compose plugin:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.5 - Verify the installation:

sudo docker run --rm hello-world

You should see a "Hello from Docker!" message.

2.6 - Allow your user to run Docker without sudo (optional but recommended):

sudo usermod -aG docker $USER
newgrp docker

Step 3 - Install Git

sudo apt install -y git

Step 4 - Clone the repository

git clone https://github.com/openlogforge/openlogforge.git
cd openlogforge

Step 5 - Configure the application

openLogForge is configured through environment variables. Create a .env file in the project root:

cp .env.example .env 2>/dev/null || touch .env

Open .env in a text editor and set the following values:

nano .env

# Path inside the container where the SQLite database is stored.
# The default is fine for most deployments - the volume handles persistence.
OLF_DB_PATH=/data/openlogforge.db

That is all that is required for a basic deployment.

Additional environment variables (JWT secret, session limits, etc.) will be documented here as they are added in upcoming milestones.

Step 6 - Build and start the application

docker compose up --build -d

Docker will:

  1. Build the backend image - Python 3.12 Alpine, install dependencies, copy source
  2. Build the frontend image - Node 20 Alpine, npm ci, vite build, serve via Caddy
  3. Start both containers with restart: unless-stopped
  4. Run Alembic database migrations automatically on first start

The first build takes 3-5 minutes. Subsequent starts are faster because Docker caches the image layers.

Check that both containers are running:

docker compose ps

Expected output:

NAME                     IMAGE               STATUS          PORTS
openlogforge-app-1       openlogforge-app    Up              8000/tcp
openlogforge-web-1       openlogforge-web    Up              0.0.0.0:80->8080/tcp

Step 7 - Access the web interface

Open a browser and navigate to:

http://<your-server-ip>

If you are running this on your local machine:

http://localhost

You should see the openLogForge dashboard.

Step 8 - View application logs

All services:

docker compose logs -f

Backend only:

docker compose logs -f app

Frontend / Caddy only:

docker compose logs -f web

Stopping and starting

Stop the application (containers are removed, data is preserved):

docker compose down

Start again:

docker compose up -d

Stop and remove all data (destructive - deletes the database):

docker compose down -v

Updating to a new version

git pull
docker compose up --build -d

Alembic migrations run automatically on startup. Your data is preserved in the olf-data Docker volume.

Firewall configuration

If you use ufw, open port 80:

sudo ufw allow 80/tcp
sudo ufw reload

For HTTPS (planned for a future milestone), also open port 443:

sudo ufw allow 443/tcp
sudo ufw reload

Troubleshooting

Port 80 is already in use

Another service (commonly Apache or Nginx) is listening on port 80. Stop it or change the openLogForge port in docker-compose.yml:

ports:
  - "8080:8080"   # change 80 to any free port on your host

Then access the app at http://<your-server-ip>:8080.

Backend fails to start - database permission error

The database volume is owned by root on the host. The entrypoint script fixes this automatically, but if you see permission errors, inspect the volume:

docker compose logs app

If the issue persists, reset the volume (this deletes all data):

docker compose down -v
docker compose up -d

Cannot connect to Docker daemon

If you see permission denied while trying to connect to the Docker daemon, either:

  • Prefix commands with sudo, or
  • Add your user to the docker group (Step 2.6) and log out and back in

Build fails - no space left on device

Docker build layers accumulate over time. Free space with:

docker system prune -f

What is next