STEMBlock.ai - Local Testing with Docker

This guide provides comprehensive instructions for setting up and testing the STEMBlock.ai application locally using Docker.

📋 Prerequisites

Before you begin, ensure you have the following installed on your system:

Docker Desktop (version 20.10 or later)
- Download from: https://www.docker.com/products/docker-desktop
- Includes Docker Engine, Docker CLI, and Docker Compose
Git (for cloning repositories if needed)
At least 4GB of available RAM for all containers

Verify Installation

# Check Docker version
docker --version
# Output: Docker version 20.10.x or later

# Check Docker Compose version
docker compose version
# Output: Docker Compose version v2.x.x or later

🏗️ Project Structure

The STEMBlock.ai application consists of two main components:

~/Documents/GitHub/
├── stemblockai-backend/     # NestJS backend API
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── ...
└── stemblockai-frontend/    # Next.js frontend
    ├── Dockerfile
    ├── docker-compose.yml
    └── ...

🚀 Quick Start (Recommended)

Step 1: Start the Backend

The backend includes both the NestJS API and PostgreSQL database.

# Navigate to backend directory
cd ~/Documents/GitHub/stemblockai-backend

# Start backend and database
docker compose up -d

# View logs (optional)
docker compose logs -f

What this does:

Creates a PostgreSQL database container
Builds and starts the NestJS backend
Runs database migrations automatically
Exposes backend on http://localhost:3001

Step 2: Verify Backend is Running

# Check if containers are healthy
docker compose ps

# Test the backend API
curl http://localhost:3001/health
# Should return: {"status":"ok"}

Step 3: Start the Frontend

# Navigate to frontend directory
cd ~/Documents/GitHub/stemblockai-frontend

# Start frontend
docker compose up -d

# View logs (optional)
docker compose logs -f

What this does:

Builds and starts the Next.js frontend
Connects to the backend API
Exposes frontend on http://localhost:3000

Step 4: Access the Application

Open your browser and navigate to:

Frontend: http://localhost:3000
Backend API: http://localhost:3001

📊 Environment Variables

Backend Environment Variables

The backend uses these environment variables (set in docker-compose.yml):

DATABASE_URL: postgresql://stemblock:stemblock_dev_password@postgres:5432/stemblock_db
JWT_SECRET: your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN: 7d
PORT: 3001

Optional variables (for additional features):

# For AI evaluation features
OPENAI_API_KEY=your-openai-api-key

# For Google OAuth login
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

To add these, create a .env file in the backend directory:

cd ~/Documents/GitHub/stemblockai-backend
cat > .env << EOF
OPENAI_API_KEY=sk-your-key-here
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
EOF

Frontend Environment Variables

The frontend requires the backend API URL:

NEXT_PUBLIC_API_URL: http://localhost:3001

To customize, create a .env.local file:

cd ~/Documents/GitHub/stemblockai-frontend
echo "NEXT_PUBLIC_API_URL=http://localhost:3001" > .env.local

🔄 Docker Commands Reference

Starting Services

# Start in detached mode (recommended)
docker compose up -d

# Start with live logs
docker compose up

# Start only specific service
docker compose up -d backend

Viewing Logs

# View all logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# View logs for specific service
docker compose logs backend
docker compose logs postgres

# View last 100 lines
docker compose logs --tail=100

Stopping Services

# Stop all services (keeps data)
docker compose stop

# Stop and remove containers (keeps data volumes)
docker compose down

# Stop and remove everything including volumes (⚠️ deletes database data)
docker compose down -v

Rebuilding Containers

When you make code changes, rebuild the containers:

# Rebuild and restart
docker compose up -d --build

# Force rebuild without cache
docker compose build --no-cache
docker compose up -d

Checking Status

# View running containers
docker compose ps

# Check container health
docker ps --format "table {{.Names}}\t{{.Status}}"

# View resource usage
docker stats

🗄️ Database Management

Accessing the Database

# Connect to PostgreSQL container
docker exec -it stemblock-postgres psql -U stemblock -d stemblock_db

# Example queries
\dt                    # List all tables
SELECT * FROM "User";  # View users
\q                     # Quit

Running Migrations

Migrations run automatically on container startup. To run manually:

# Enter backend container
docker exec -it stemblock-backend sh

# Run migrations
npx prisma migrate deploy

# Generate Prisma client (if needed)
npx prisma generate

# Exit container
exit

Resetting the Database

cd ~/Documents/GitHub/stemblockai-backend

# Stop and remove all data
docker compose down -v

# Start fresh
docker compose up -d

# The database will be recreated with migrations applied

Database Backup

# Create backup
docker exec stemblock-postgres pg_dump -U stemblock stemblock_db > backup.sql

# Restore from backup
docker exec -i stemblock-postgres psql -U stemblock stemblock_db < backup.sql

🧪 Testing the Application

1. Create Test Users

The application requires users with different roles. You can create them via the registration page or directly in the database:

Via Registration UI:

Go to http://localhost:3000/register
Create accounts with different roles:
- Student account
- Coach account
- Parent account
- Admin account

Via Database:

docker exec -it stemblock-postgres psql -U stemblock -d stemblock_db

-- View existing users
SELECT id, email, role, "firstName", "lastName" FROM "User";

2. Test Workflows

Student Workflow:

Login as student: http://localhost:3000/login
Navigate to student dashboard
View and submit assignments

Coach Workflow:

Login as coach
Create a class
Add students to the class
Create assignments
Review submissions

Parent Workflow:

Login as parent
View children's progress
Download PDF reports (requires backend implementation)

Admin Workflow:

Login as admin
Manage users
Manage classes
Reassign coaches

3. API Testing

Test backend endpoints directly:

# Register a new user
curl -X POST http://localhost:3001/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123",
    "firstName": "Test",
    "lastName": "User",
    "role": "STUDENT"
  }'

# Login
curl -X POST http://localhost:3001/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

# Use the returned accessToken for authenticated requests
export TOKEN="your-access-token-here"

# Get classes
curl http://localhost:3001/classes \
  -H "Authorization: Bearer $TOKEN"

🐛 Troubleshooting

Container Won't Start

Problem: Container exits immediately

Solution:

# Check logs for errors
docker compose logs backend

# Check if port is already in use
lsof -i :3001  # Backend port
lsof -i :3000  # Frontend port
lsof -i :5432  # Database port

# Kill process if needed
kill -9 <PID>

Database Connection Error

Problem: Backend can't connect to database

Solution:

# Ensure postgres is healthy
docker compose ps

# Check postgres logs
docker compose logs postgres

# Restart services in order
docker compose down
docker compose up -d postgres
# Wait 10 seconds
docker compose up -d backend

Frontend Can't Connect to Backend

Problem: API calls fail with network errors

Solution:

Verify backend is running: curl http://localhost:3001/health

Check NEXT_PUBLIC_API_URL in frontend container:

docker exec stemblock-frontend env | grep NEXT_PUBLIC_API_URL

Rebuild frontend if environment variable changed:

cd ~/Documents/GitHub/stemblockai-frontend
docker compose up -d --build

Out of Disk Space

Problem: "No space left on device"

Solution:

# Remove unused images and containers
docker system prune -a

# Remove unused volumes (⚠️ deletes data)
docker volume prune

Permission Issues

Problem: Permission denied errors

Solution:

# Fix file permissions
cd ~/Documents/GitHub/stemblockai-backend
sudo chown -R $USER:$USER .

cd ~/Documents/GitHub/stemblockai-frontend
sudo chown -R $USER:$USER .

🔧 Development Tips

Hot Reload (Optional)

For development with hot reload, you can mount source code as volumes:

Backend (docker-compose.yml):

volumes:
  - ./src:/app/src
  - ./uploads:/app/uploads

Frontend: Already uses standalone mode - rebuild for changes.

Viewing Real-Time Logs

# Multiple terminals approach
# Terminal 1: Backend logs
cd ~/Documents/GitHub/stemblockai-backend
docker compose logs -f

# Terminal 2: Frontend logs
cd ~/Documents/GitHub/stemblockai-frontend
docker compose logs -f

Accessing Container Shell

# Backend
docker exec -it stemblock-backend sh

# Frontend
docker exec -it stemblock-frontend sh

# Database
docker exec -it stemblock-postgres sh

📝 Common Tasks

Task: Add Test Data

# Connect to database
docker exec -it stemblock-postgres psql -U stemblock -d stemblock_db

# Create test users, classes, assignments
-- SQL commands here

Task: Reset Everything

# Stop and remove all containers and data
cd ~/Documents/GitHub/stemblockai-backend
docker compose down -v

cd ~/Documents/GitHub/stemblockai-frontend
docker compose down

# Remove network
docker network rm stemblock_network

# Start fresh
cd ~/Documents/GitHub/stemblockai-backend
docker compose up -d

cd ~/Documents/GitHub/stemblockai-frontend
docker compose up -d

Task: Update to Latest Code

# Pull latest changes
cd ~/Documents/GitHub/stemblockai-backend
git pull origin main

cd ~/Documents/GitHub/stemblockai-frontend
git pull origin main

# Rebuild and restart
cd ~/Documents/GitHub/stemblockai-backend
docker compose up -d --build

cd ~/Documents/GitHub/stemblockai-frontend
docker compose up -d --build

📚 Additional Resources

Docker Documentation: https://docs.docker.com
Docker Compose Reference: https://docs.docker.com/compose/compose-file
Next.js Docker Deployment: https://nextjs.org/docs/deployment#docker-image
NestJS Documentation: https://docs.nestjs.com
Prisma Documentation: https://www.prisma.io/docs

🆘 Getting Help

If you encounter issues:

Check the logs: docker compose logs -f
Verify all containers are healthy: docker compose ps
Review this documentation
Check the troubleshooting section
Create an issue on GitHub with:
- Error messages from logs
- Steps to reproduce
- Docker version
- Operating system

✅ Success Checklist

Your local environment is ready when:

Backend container is running and healthy
Frontend container is running and healthy
Database container is running and healthy
http://localhost:3000 shows the login page
http://localhost:3001/health returns \{"status":"ok"\}
You can register and login as a user
Database migrations have been applied

Happy Testing! 🚀

📋 Prerequisites​

Verify Installation​

🏗️ Project Structure​

🚀 Quick Start (Recommended)​

Step 1: Start the Backend​

Step 2: Verify Backend is Running​

Step 3: Start the Frontend​

Step 4: Access the Application​

📊 Environment Variables​

Backend Environment Variables​

Frontend Environment Variables​

🔄 Docker Commands Reference​

Starting Services​

Viewing Logs​

Stopping Services​

Rebuilding Containers​

Checking Status​

🗄️ Database Management​

Accessing the Database​

Running Migrations​

Resetting the Database​

Database Backup​

🧪 Testing the Application​

1. Create Test Users​

2. Test Workflows​

3. API Testing​

🐛 Troubleshooting​

Container Won't Start​

Database Connection Error​

Frontend Can't Connect to Backend​

Out of Disk Space​

Permission Issues​

🔧 Development Tips​

Hot Reload (Optional)​

Viewing Real-Time Logs​

Accessing Container Shell​

📝 Common Tasks​

Task: Add Test Data​

Task: Reset Everything​

Task: Update to Latest Code​

📚 Additional Resources​

🆘 Getting Help​

✅ Success Checklist​

📋 Prerequisites

Verify Installation

🏗️ Project Structure

🚀 Quick Start (Recommended)

Step 1: Start the Backend

Step 2: Verify Backend is Running

Step 3: Start the Frontend

Step 4: Access the Application

📊 Environment Variables

Backend Environment Variables

Frontend Environment Variables

🔄 Docker Commands Reference

Starting Services

Viewing Logs

Stopping Services

Rebuilding Containers

Checking Status

🗄️ Database Management

Accessing the Database

Running Migrations

Resetting the Database

Database Backup

🧪 Testing the Application

1. Create Test Users

2. Test Workflows

3. API Testing

🐛 Troubleshooting

Container Won't Start

Database Connection Error

Frontend Can't Connect to Backend

Out of Disk Space

Permission Issues

🔧 Development Tips

Hot Reload (Optional)

Viewing Real-Time Logs

Accessing Container Shell

📝 Common Tasks

Task: Add Test Data

Task: Reset Everything

Task: Update to Latest Code

📚 Additional Resources

🆘 Getting Help

✅ Success Checklist