Docker Deployment

Docker is the recommended way to run Homepage in production.

Quick start

# Clone the repo
git clone https://codeberg.org/thelinuxcast/Homepage.git
cd Homepage

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Build and start
docker compose up -d

The app will be available at http://localhost:3001.

Note: if you have other containers running, you may need to change the port

docker-compose.yml

The included docker-compose.yml builds the image locally and mounts the data directory:

Note: The included compose file has a section for nginx, this can be deleted. It is for hosting the docs and you don't need that

services:
  homepage:
    build: .
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    env_file:
      - .env
    restart: unless-stopped

Key points:

• ./data:/app/data — persists the SQLite database across container rebuilds
• /var/run/docker.sock — required for the Docker widget; omit if not using it
• restart: unless-stopped — auto-restarts on system reboot

Updating

git pull
docker compose up -d --build

The database is preserved because it lives in the mounted data/ volume.

Running behind a reverse proxy

Caddy

homepage.example.com {
    reverse_proxy localhost:3001
}

nginx

server {
    listen 80;
    server_name homepage.example.com;

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Manual build (no Docker)

# Install all dependencies
npm install
cd client && npm install && cd ..
cd server && npm install && cd ..

# Build
cd client && npm run build && cd ..
cd server && npm run build && cd ..

# Copy built client into server's public directory
cp -r client/dist/* server/public/

# Start
cd server && npm start