Peer Group Grading - Setup Guide

This guide will walk you through setting up and running the Peer Group Grading application using Docker and Docker Compose.

⚠️ Important Note: LDAP functionality is currently not supported. The setup uses PostgreSQL and Redis only.

Prerequisites

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

• Docker (version 20.10 or later)
• Docker Compose (version 2.0 or later)
• Git (to clone the repository)

Initial Setup

1. Clone the Repository

git clone https://git.mixel.cloud/Turbo/peer-group-grading/
cd peer-group-grading

2. Create Environment Configuration

Create a .env file in the root directory of the project. You can use the .env.example file as a template:

cp .env.example .env

Then edit the .env file with your desired configuration values.

Important: Replace the placeholder passwords with strong, secure passwords.

3. Verify Project Structure

Ensure your project has the following structure:

.
├── dev-compose.yml
├── backend.Dockerfile
├── .env
├── .env.example
├── Cargo.toml
├── Cargo.lock
└── crates/
    ├── backend/
    │   ├── Cargo.toml
    │   └── src/
    └── migration/
        ├── Cargo.toml
        └── src/

Building and Starting the Application

Build the Docker Images

docker compose build

This command will:

• Build the Rust backend using the multi-stage Dockerfile
• Pull the required images (PostgreSQL, Redis)

Start Database and Redis Services

Since the compose file is named dev-compose.yml, use the -f flag to specify it:

docker compose -f dev-compose.yml up -d db redis

The -d flag runs the containers in detached mode (in the background).

Start the Backend Service

docker compose -f dev-compose.yml up -d backend

Developer Note: Database migrations are executed automatically when the backend starts. You don't need to run them manually.

Verify Services Are Running

docker compose -f dev-compose.yml ps

You should see all services (db, redis, backend) in a "running" state.

View Logs

To monitor the application logs:

# All services
docker compose -f dev-compose.yml logs -f

# Specific service
docker compose -f dev-compose.yml logs -f backend

Accessing the Application

Once all containers are running:

• Web Application: http://localhost:8080/
• API Documentation (Swagger UI): http://localhost:8080/swagger-ui
• API Endpoints: http://localhost:8080/api/{version}/ [current version v1]
• PostgreSQL Database: localhost:5432
• Redis: localhost:6379

Using the Application

Access the Web Interface

1. Navigate to http://localhost:8080/
2. The frontend is served directly by the backend

Default Admin Account

A default admin user is created automatically via migrations:

• Username: admin
• Password: Use the default password, then change it immediately after first login for security

API Documentation

Explore the API documentation at http://localhost:8080/swagger-ui to see all available endpoints and their specifications.

Troubleshooting

Services Not Starting

Check logs for specific services:

docker compose -f dev-compose.yml logs backend
docker compose -f dev-compose.yml logs db
docker compose -f dev-compose.yml logs redis

Database Connection Issues

1. Verify the database is ready:

   docker compose -f dev-compose.yml exec db pg_isready -U postgres
   

2. Check database connectivity from backend:

   docker compose -f dev-compose.yml exec backend ping db
   

Port Conflicts

If ports are already in use on your system:

1. Stop conflicting services, or
2. Modify the port mappings in dev-compose.yml:

   ports:
     - "8081:8080"  # Change host port to 8081
   

Stopping the Application

Stop All Services

docker compose -f dev-compose.yml down

Stop and Remove All Data

Warning: This will delete all data including databases!

docker compose -f dev-compose.yml down -v

Maintenance

Update Application

# Pull latest code
git pull

# Rebuild and restart
docker compose -f dev-compose.yml up -d --build

Backup Database

docker compose -f dev-compose.yml exec db pg_dump -U postgres peer_grading > backup.sql

Restore Database

docker compose -f dev-compose.yml exec -T db psql -U postgres peer_grading < backup.sql

View Resource Usage

docker stats

Production Considerations

For production deployment, consider:

1. Environment Variables: Use Docker secrets instead of .env files
2. SSL/TLS: Configure HTTPS with certificates
3. Reverse Proxy: Use Nginx or Traefik in front of the backend
4. Volumes: Use named volumes or bind mounts for data persistence
5. Monitoring: Add Prometheus and Grafana for monitoring
6. Backups: Implement automated database backup solutions
7. Security: Review and harden database configurations
8. Admin Password: Change the default admin password immediately

Getting Help

If you encounter issues:

1. Check the logs: docker compose -f dev-compose.yml logs -f
2. Verify all services are healthy: docker compose -f dev-compose.yml ps
3. Review the application documentation
4. Check Docker and Docker Compose versions

Cleanup

To completely remove all containers, images, and volumes:

docker compose -f dev-compose.yml down -v --rmi all