frappe_docker/LOCAL_TESTING.md

Local Testing Guide for Pre-built Images

This guide explains how to run the Academy LMS stack locally using images from GitHub Container Registry.

Prerequisites

1. Docker and Docker Compose installed
2. Access to the GitHub Container Registry (for private images)

Quick Start

1. Clone this repository

git clone https://github.com/ExarLabs/academy_docker.git
cd academy_docker

2. Set up environment variables

# Copy the example environment file
cp .env.example .env

# Edit the .env file with your actual values
nano .env

Required variables to update:

• MARIADB_ROOT_PASSWORD - Set a secure password
• OPENAI_API_KEY - Your OpenAI API key
• ANTHROPIC_API_KEY - Your Anthropic API key (optional)
• LANGCHAIN_DB_PASSWORD - Password for LangChain database

3. Login to GitHub Container Registry (if images are private)

# Using GitHub Personal Access Token
echo $GITHUB_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

# Or using GitHub CLI
gh auth token | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

4. Pull and run the services

# Pull the latest images
docker compose pull

# Start all services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

5. Create your first site (after services are running)

# Create a new site
docker compose exec backend bench new-site academy.local \
  --admin-password admin \
  --db-root-password $MARIADB_ROOT_PASSWORD

# Install the LMS app
docker compose exec backend bench --site academy.local install-app lms

# Install the AI Tutor Chat app
docker compose exec backend bench --site academy.local install-app ai_tutor_chat

# Set the site as default
docker compose exec backend bench use academy.local

6. Access the application

1. Add to your hosts file:

   • Windows: C:\Windows\System32\drivers\etc\hosts
   • Linux/Mac: /etc/hosts

   Add this line:

   127.0.0.1 academy.local
   

2. Open in browser: http://academy.local

What's included?

The compose.yaml file includes:

• Frappe/ERPNext with Academy LMS and AI Tutor apps (single image: ghcr.io/exarlabs/ignis-academy-lms)
• LangChain service for AI functionality (image: ghcr.io/exarlabs/academy-langchain)
• MariaDB for Frappe database
• PostgreSQL for LangChain database
• Redis for caching and queues
• Nginx reverse proxy

Troubleshooting

"manifest unknown" error

This means the image hasn't been built yet. Either:

1. Wait for GitHub Actions to build and push the images
2. Build locally (see development guide)

Environment variable warnings

Ensure your .env file exists and contains all required variables. Use .env.example as reference.

Cannot access the site / 404 errors on assets

If you see 404 errors for CSS/JS files:

1. Rebuild assets:

   docker compose exec backend bench --site academy.local build
   

2. Clear cache:

   docker compose exec backend bench --site academy.local clear-cache
   

3. Set current site:

   docker compose exec backend sh -c "echo 'academy.local' > /home/frappe/frappe-bench/sites/currentsite.txt"
   

4. Restart services:

   docker compose restart backend frontend nginx-proxy
   

5. Hard refresh your browser (Ctrl+F5 or Cmd+Shift+R)

Cannot access the site

1. Check if all services are running: docker compose ps
2. Ensure you've added the hostname to your hosts file
3. Check nginx logs: docker compose logs nginx-proxy

Database connection errors

1. Ensure MariaDB is fully started before creating sites
2. Check the password in .env matches what you use in commands

LangChain service errors (student_ai_profiles table missing)

If you get errors about missing database tables in the LangChain service:

# Create the required tables
docker compose exec langchain-service sh -c "cd /app && PYTHONPATH=/app python app/create_tables.py"

This will create all necessary tables including:

• student_ai_profiles
• chat_conversations
• chat_messages

Login issues

Default credentials after site creation:

• Username: Administrator
• Password: The password you set with --admin-password flag

Stopping the services

# Stop all services
docker compose down

# Stop and remove all data (careful!)
docker compose down -v

Next Steps

• For production deployment, see DEPLOYMENT.md
• For development setup, see README.md
• For environment configuration, see docs/environment-secrets-explained.md