awesome-app/DOCKER.md

Docker Deployment Guide

This guide covers building and deploying the awesome-app using Docker.

Quick Start

Using Pre-built Image (Recommended)

Pull and run the latest image from GitHub Container Registry:

docker pull ghcr.io/valknarness/awesome-app:latest
docker run -p 3000:3000 ghcr.io/valknarness/awesome-app:latest

The image includes a pre-built database, updated every 6 hours by GitHub Actions.

Using Docker Compose

docker-compose up -d

Build Options

The Dockerfile supports a build argument INCLUDE_DATABASE to control whether the database is embedded in the image or mounted at runtime.

Option 1: Embedded Database (CI Default)

Pros:

• Self-contained image
• No external dependencies
• Faster startup
• Database version matches image version

Cons:

• Larger image size
• Database updates require new image build

docker build --build-arg INCLUDE_DATABASE=true -t awesome-app .
docker run -p 3000:3000 awesome-app

Option 2: Volume-Mounted Database (Local Default)

Pros:

• Smaller image size
• Database can be updated independently
• Easier for development

Cons:

• Requires database setup/volume mount
• Extra configuration needed

docker build --build-arg INCLUDE_DATABASE=false -t awesome-app .
docker run -p 3000:3000 -v $(pwd)/data:/app/data awesome-app

Docker Compose Configuration

Edit docker-compose.yml to control database inclusion:

services:
  awesome-app:
    build:
      args:
        INCLUDE_DATABASE: false  # Change to true to embed database
    volumes:
      - ./data:/app/data  # Only needed when INCLUDE_DATABASE=false

Environment Variables

Variable	Default	Description
NODE_ENV	production	Node.js environment
PORT	3000	Application port
HOSTNAME	0.0.0.0	Bind hostname

Database Location

• Embedded mode: /app/awesome.db
• Volume mode: /app/data/awesome.db (mounted)

The application will automatically detect and use the database from either location.

Multi-Platform Support

Images are built for multiple platforms:

• linux/amd64 (x86_64)
• linux/arm64 (ARM64/Apple Silicon)

Docker will automatically pull the correct architecture for your system.

Health Checks

The image includes a built-in health check that pings the application every 30 seconds:

docker ps  # Check HEALTH status column

Image Metadata

View database metadata embedded in the image:

docker inspect ghcr.io/valknarness/awesome-app:latest | jq '.[0].Config.Labels'

Metadata includes:

• app.database.timestamp - When the database was built
• app.database.hash - SHA256 hash of the database
• app.database.lists_count - Number of awesome lists
• app.database.repos_count - Number of repositories

Production Deployment

Using Pre-built Image

docker pull ghcr.io/valknarness/awesome-app:latest
docker run -d \
  --name awesome-app \
  -p 3000:3000 \
  --restart unless-stopped \
  ghcr.io/valknarness/awesome-app:latest

With Volume Mount

docker run -d \
  --name awesome-app \
  -p 3000:3000 \
  -v awesome-data:/app/data \
  --restart unless-stopped \
  ghcr.io/valknarness/awesome-app:latest

Using Docker Compose

docker-compose up -d

Database Updates

Embedded Database

Pull the latest image to get an updated database:

docker pull ghcr.io/valknarness/awesome-app:latest
docker-compose up -d  # Recreates container with new image

Volume-Mounted Database

Update the database file in the mounted volume:

# Download latest database
wget https://github.com/your-repo/releases/latest/download/awesome.db

# Place in volume
cp awesome.db ./data/

# Restart container
docker-compose restart

Troubleshooting

Database not found

If the application can't find the database:

1. Embedded mode: Ensure INCLUDE_DATABASE=true was set during build
2. Volume mode: Check that the volume is mounted correctly

docker exec awesome-app ls -la /app/awesome.db     # Embedded
docker exec awesome-app ls -la /app/data/awesome.db # Volume

Permission issues

Ensure the database file has correct permissions:

docker exec awesome-app chown nextjs:nodejs /app/data/awesome.db

Rebuild from scratch

Remove cached layers and rebuild:

docker build --no-cache --build-arg INCLUDE_DATABASE=true -t awesome-app .

Development

For local development with hot reload:

# Use the dev server instead of Docker
pnpm dev

For testing the production Docker build locally:

docker build -t awesome-app-test .
docker run -p 3000:3000 awesome-app-test

Security

The container runs as a non-root user (nextjs:nodejs) with UID/GID 1001 for enhanced security.

Support

For issues or questions:

• GitHub Issues: your-repo/issues
• Workflow Docs: .github/workflows/README.md