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

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

### 2. Set up environment variables

```bash
# 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)

```bash
# 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

```bash
# 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)

```bash
# 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**:
   ```bash
   docker compose exec backend bench --site academy.local build
   ```

2. **Clear cache**:
   ```bash
   docker compose exec backend bench --site academy.local clear-cache
   ```

3. **Set current site**:
   ```bash
   docker compose exec backend sh -c "echo 'academy.local' > /home/frappe/frappe-bench/sites/currentsite.txt"
   ```

4. **Restart services**:
   ```bash
   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:

```bash
# 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

```bash
# Stop all services
docker compose down

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

## Next Steps

- For production deployment, see [DEPLOYMENT.md](DEPLOYMENT.md)
- For development setup, see [README.md](README.md)
- For environment configuration, see [docs/environment-secrets-explained.md](docs/environment-secrets-explained.md)