Installation

Prerequisites

Before installing KnowledgeCheckr, ensure you have the following installed:

Docker & Docker Compose (for containerized deployment)
Node.js 20+ and Yarn (for local development)
MySQL 8.0+ (if running without Docker)

Quick start with Docker

The fastest way to get KnowledgeCheckr running is using Docker Compose.

Clone the repository

git clone https://github.com/yourusername/knowledgecheckr.git
cd knowledgecheckr

Configure environment variables

Create a .env file in the root directory with the required configuration:

# Application URL
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Authentication Secret (base64 encoded)
AUTH_SECRET=your-base64-secret-here

# Database Configuration
DATABASE_HOST=db
DATABASE_PORT=3306
DATABASE_NAME=KnowledgeCheckr
DATABASE_USER=root
DATABASE_PASSWORD=123

# GitHub OAuth (optional)
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret

# Google OAuth (optional)
AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret

# Custom OAuth with Dex (optional)
DEX_PROVIDER_URL=http://dex:5556
DEX_CLIENT_ID=nextjs-client
DEX_CLIENT_SECRET=dev-secret

# Application Mode
NEXT_PUBLIC_MODE=production

# Logging
ENABLE_FILE_LOGGING=true
CAPTURE_CLIENT_LOGS=false

OAuth providers (GitHub, Google, Dex) are optional. KnowledgeCheckr will automatically disable any provider without complete credentials.

Start the services

Launch all services using Docker Compose:

docker-compose up -d

This will start three services:

db - MySQL database on port 3305
knowledgeCheckr - Application on port 3000
dex - OAuth provider on port 5556 (optional)

The database service includes automatic initialization scripts. Your schema will be set up on first launch.

Access the application

Open your browser and navigate to:

http://localhost:3000

You should see the KnowledgeCheckr landing page and be able to sign in.

Docker Compose configuration

The docker-compose.yml file defines the complete application stack:

docker-compose.yml

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

The database volume ./mysql_data persists data between container restarts. To completely reset your database, stop the containers and remove this directory.

Local development setup

For active development, run KnowledgeCheckr directly with Node.js.

Install dependencies

yarn install

This will install all dependencies from package.json:

Next.js 16 - React framework
Better Auth - Authentication library
Drizzle ORM - Database toolkit
Tailwind CSS - Styling
Cypress - Testing framework

Set up the database

Start a MySQL database using Docker:

docker-compose up db -d

Or use your local MySQL installation. Ensure it’s running on port 3305 (or update your .env).

Run database migrations

Generate and push the database schema:

# Generate migrations
yarn drizzle-kit generate

# Push schema to database
yarn drizzle-kit push

The schema is defined in database/drizzle/schema.ts using Drizzle ORM:

database/drizzle/schema.ts

// Key tables
export const db_user = mysqlTable('User', { ... })
export const db_knowledgeCheck = mysqlTable('KnowledgeCheck', { ... })
export const db_question = mysqlTable('Question', { ... })
export const db_answer = mysqlTable('Answer', { ... })
export const db_category = mysqlTable('Category', { ... })

Start the development server

yarn dev

This runs the Next.js development server with:

Turbopack - Fast bundler for development
Hot reloading - Instant updates on file changes
i18n preparation - Automatic locale updates

The dev script runs two concurrent processes:

package.json

"dev": "concurrently 
  'NEXT_PUBLIC_MODE=development next dev --turbopack' 
  'nodemon --exec \"yarn tsx src/i18n/scripts/prepare-i18n_ally-locales.ts\" 
    --watch src/i18n/locales/*.json'"

Access the application

Navigate to http://localhost:3000 to see your development instance.The application runs in development mode with:

Detailed error messages
Hot module replacement
Source maps for debugging

Environment variable reference

KnowledgeCheckr uses Zod for environment variable validation. All variables are validated at startup.

Required variables

Variable	Type	Description
`BETTER_AUTH_URL`	URL	Trusted domain for authentication
`NEXT_PUBLIC_BASE_URL`	URL	Base URL of the application
`AUTH_SECRET`	Base64	Secret for session encryption
`DATABASE_HOST`	String	Database host (IP, URL, or service name)
`DATABASE_PORT`	Number	Database port (typically 3306)
`DATABASE_NAME`	String	Database name
`DATABASE_USER`	String	Database user
`DATABASE_PASSWORD`	String	Database password (optional)

Optional OAuth variables

GitHub
Google
Dex (Custom)

AUTH_GITHUB_ID=your-client-id
AUTH_GITHUB_SECRET=your-client-secret

Configure GitHub OAuth in your application settings:

Go to GitHub Settings → Developer settings → OAuth Apps
Create a new OAuth App
Set callback URL: {BETTER_AUTH_URL}/api/auth/callback/github

AUTH_GOOGLE_ID=your-client-id
AUTH_GOOGLE_SECRET=your-client-secret

Configure Google OAuth in Google Cloud Console:

Create a new OAuth 2.0 Client ID
Add authorized redirect URI: {BETTER_AUTH_URL}/api/auth/callback/google

DEX_PROVIDER_URL=http://dex:5556
DEX_CLIENT_ID=nextjs-client
DEX_CLIENT_SECRET=dev-secret

Dex configuration is stored in dex/dex.config.yaml. Required for test mode.

Optional application variables

Variable	Type	Default	Description
`NEXT_PUBLIC_MODE`	Enum	`production`	Application mode: `production`, `development`, or `test`
`ENABLE_FILE_LOGGING`	Boolean	`true`	Enable Winston file logging
`CAPTURE_CLIENT_LOGS`	Boolean	`false`	Send client-side logs to server
`SHOW_APP_VERSION`	Boolean	`false`	Display version in UI

Environment validation is performed in src/lib/Shared/Env.ts using Zod schemas. Missing or invalid variables will prevent the application from starting.

Building for production

Create an optimized production build:

yarn build

The build process:

Compiles TypeScript to JavaScript
Optimizes assets with Next.js compiler
Generates static pages where possible
Creates standalone output in .next/standalone/

package.json

"build": "next build",
"postbuild": "cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/"

The post-build script copies static assets into the standalone folder for self-contained deployment.

Running in production

Start the production server:

yarn start

This runs the standalone server:

package.json

"prestart": "npm run validateEnvironment",
"start": "node .next/standalone/server.js"

The production server validates all environment variables before starting. Ensure your .env file is complete and valid.

Testing

KnowledgeCheckr includes comprehensive test suites:

yarn test:e2e

Tests use:

Cypress for E2E and component testing
Jest for unit tests
Code coverage via Istanbul and NYC

For faster test execution, use parallel testing:

yarn test:parallel

This runs tests across 8 concurrent workers.

Troubleshooting

Database connection errors

If you encounter database connection issues:

Check the database is running:
```
docker-compose ps
```
Verify environment variables:
```
yarn validateEnvironment
```
Check database logs:
```
docker-compose logs db
```

Port conflicts

If ports 3000 or 3305 are already in use:

Change application port in docker-compose.yml:

ports:
  - "3001:3000"  # Use port 3001 instead

Change database port in docker-compose.yml:

ports:
  - "3307:3306"  # Use port 3307 instead

OAuth configuration issues

If OAuth providers aren’t working:

Check environment variables are complete (both ID and SECRET)
Verify callback URLs match OAuth provider settings
Check logs for specific error messages:
```
docker-compose logs knowledgeCheckr
```

The application automatically disables OAuth providers with incomplete credentials. Check startup logs for messages about enabled/disabled providers.

Next steps

Create your first check

Follow the quickstart to create your first knowledge assessment

Development guide

Learn about the codebase structure and contributing

API reference

Explore the authentication and data APIs

Deploy to production

Deploy KnowledgeCheckr to your infrastructure

Getting Started

Core Features

User Guide

Configuration

Prerequisites

Quick start with Docker

Docker Compose configuration

Local development setup

Environment variable reference

Required variables

Optional OAuth variables

Optional application variables

Building for production

Running in production

Testing

Troubleshooting

Database connection errors

Port conflicts

OAuth configuration issues

Next steps

Create your first check

Development guide

API reference

Deploy to production

Build docs developers (and LLMs) love

Getting Started

Core Features

User Guide

Configuration

​Prerequisites

​Quick start with Docker

​Docker Compose configuration

​Local development setup

​Environment variable reference

​Required variables

​Optional OAuth variables

​Optional application variables

​Building for production

​Running in production

​Testing

​Troubleshooting

​Database connection errors

​Port conflicts

​OAuth configuration issues

​Next steps

Create your first check

Development guide

API reference

Deploy to production

Build docs developers (and LLMs) love

Prerequisites

Quick start with Docker

Docker Compose configuration

Local development setup

Environment variable reference

Required variables

Optional OAuth variables

Optional application variables

Building for production

Running in production

Testing

Troubleshooting

Database connection errors

Port conflicts

OAuth configuration issues

Next steps