Skip to main content
KnowledgeCheckr can be easily deployed using Docker and Docker Compose. The application uses a multi-stage build process to create optimized container images.

​
Prerequisites

  • Docker Engine 20.10 or later
  • Docker Compose v3.8 or later
  • At least 2GB of available RAM
  • Port 3000, 3306, and 5556 available on your host machine

​
Architecture Overview

The Docker Compose setup includes three main services:
  • knowledgeCheckr: The main Next.js application
  • db: MySQL 8.0+ database with pre-initialized schema
  • dex: OpenID Connect identity provider for authentication

​
Quick Start

1

Clone the repository

git clone <repository-url>
cd knowledgecheckr
2

Create environment file

Create a .env file in the root directory with the required environment variables. See the Environment Variables page for details.
touch .env
3

Start the services

docker-compose up -d
This will:
  • Pull the pre-built images from GitHub Container Registry
  • Start the MySQL database with automatic schema initialization
  • Start the Dex authentication server
  • Launch the KnowledgeCheckr application
4

Verify the deployment

Check that all services are running:
docker-compose ps
Access the application at http://localhost:3000

​
Docker Compose Configuration

The default docker-compose.yml configuration: 
version: "3.8"

services:
  db:
    image: ghcr.io/master-thesis-188199/knowledgecheckr-database:1.0.0
    restart: on-failure
    environment:
      MYSQL_ROOT_PASSWORD: "123"
      MYSQL_ROOT_HOST: "%"
      MYSQL_DATABASE: KnowledgeCheckr
      MYSQL_USER: test
      MYSQL_PASSWORD: pass
    volumes:
      - ./mysql_data:/var/lib/mysql
    ports:
      - "3305:3306"

  knowledgeCheckr:
    image: ghcr.io/master-thesis-188199/knowledgecheckr:latest
    restart: no
    ports:
      - 3000:3000
    environment:
      DATABASE_HOST: mysql
      DATABASE_PORT: 3306
      DATABASE_USER: root
      DATABASE_PASSWORD: 123
      DATABASE_NAME: KnowledgeCheckr
    env_file:
      - .env

  dex:
    restart: on-failure
    image: ghcr.io/dexidp/dex:latest
    container_name: dex
    ports:
      - "5556:5556"
    volumes:
      - ./dex/dex.config.yaml:/etc/dex/config.docker.yaml:ro

​
Building from Source

If you want to build the Docker images locally instead of using pre-built images:
1

Build the application image

docker build -t knowledgecheckr:local .
The Dockerfile uses a multi-stage build:
  • Stage 1: Install dependencies using Yarn
  • Stage 2: Build the Next.js application
  • Stage 3: Create minimal runtime image with standalone output
2

Build the database image

docker build -t knowledgecheckr-db:local -f database/Dockerfile .
This creates a MySQL image with:
  • All Drizzle migrations concatenated into a single init script
  • Automatic schema initialization on first run
3

Update docker-compose.yml

Modify the image references to use your local builds:
services:
  db:
    image: knowledgecheckr-db:local
  knowledgeCheckr:
    image: knowledgecheckr:local

​
Dockerfile Details

The application Dockerfile (~/workspace/source/Dockerfile:1-49) uses Node.js 24.11.1 Alpine and implements:

​
Multi-Stage Build

  1. Package Installer Stage: Installs dependencies with frozen lockfile for reproducible builds
  2. Builder Stage: Compiles the Next.js application with production optimizations
  3. Production Stage: Copies only necessary artifacts for minimal image size

​
Runtime Environment Validation

The production image includes environment validation at runtime: 
COPY --from=builder app/src/lib/Shared/Env.ts /app/src/lib/Shared/Env.ts
COPY --from=builder app/node_modules/ts-node /app/node_modules/ts-node
COPY --from=builder app/node_modules/dotenv /app/node_modules/dotenv
COPY --from=builder app/node_modules/zod /app/node_modules/zod
This ensures that all required environment variables are validated before the application starts.

​
Volume Management

​
Database Persistence

The MySQL database data is persisted using a named volume: 
volumes:
  - ./mysql_data:/var/lib/mysql
Important: Always back up the mysql_data directory before upgrading or migrating.

​
Dex Configuration

The Dex authentication server requires a configuration file: 
volumes:
  - ./dex/dex.config.yaml:/etc/dex/config.docker.yaml:ro
Create this file in ./dex/dex.config.yaml with your Dex configuration.

​
Port Mapping

ServiceContainer PortHost PortPurpose
knowledgeCheckr30003000Web application
db33063305MySQL database (external access)
dex55565556Dex OIDC provider

​
Common Commands

​
View logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f knowledgeCheckr

​
Restart services

# All services
docker-compose restart

# Specific service
docker-compose restart knowledgeCheckr

​
Stop and remove containers

docker-compose down

# Remove volumes as well (⚠️ deletes database data)
docker-compose down -v

​
Update to latest images

docker-compose pull
docker-compose up -d

​
Troubleshooting

​
Container won’t start

Check the logs for specific error messages: 
docker-compose logs knowledgeCheckr
Common issues:
  • Missing or invalid environment variables (see validation errors in logs)
  • Port conflicts on host machine
  • Insufficient system resources

​
Database connection errors

Verify the database is ready: 
docker-compose exec db mysql -u root -p123 -e "SHOW DATABASES;"
Ensure the DATABASE_HOST environment variable matches the database service name in Docker Compose (default: mysql).

​
Environment validation failures

The application validates all environment variables at startup. Check the error message for specific missing or invalid variables, then update your .env file accordingly.

​
Production Considerations

The default docker-compose.yml includes development credentials. Always change these values in production:
  • MySQL root password
  • Database user credentials
  • AUTH_SECRET (must be base64-encoded)

​
Security Best Practices

  1. Use strong, unique passwords for all database credentials
  2. Change the AUTH_SECRET to a securely generated base64 string
  3. Run containers as non-root user where possible
  4. Keep Docker images updated regularly
  5. Use Docker secrets for sensitive data instead of environment variables
  6. Restrict database port exposure (remove port mapping if not needed externally)

​
Performance Optimization

  1. Configure MySQL memory settings based on available RAM
  2. Enable database query caching
  3. Use a reverse proxy (nginx, Traefik) for SSL termination
  4. Set appropriate restart policies for automatic recovery

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us