Agent Games

This project is a monorepo containing both the frontend and backend for the Agent Games application.

Frontend

The frontend is built with React and Redux, offering a user interface for game submission, league management, and result viewing. It features code editing capabilities and responsive design.

For more details, see the Frontend README.

Backend

The backend is powered by FastAPI, handling game logic, user authentication, and data management. It uses SQLModel for database interactions, Pydantic for data validation, and includes Docker integration for secure code execution and simulations. The system features comprehensive game feedback in both Markdown and structured JSON formats. SQLite is used for data storage.

For more information, check out the Backend README.

🚀 Getting Started

⚡ One-Command Local Setup (Recommended)

Run the entire platform locally with a single Docker Compose command - no configuration files needed!

1. Clone the repository:

   git clone https://github.com/SanjinDedic/agent_games.git
   cd agent_games

2. Launch everything with one command:

   docker compose --profile dev up --build

That's it! This single command will:

• ✅ Build and start all services (API, validator, simulator, frontend, database)
• ✅ Set up the PostgreSQL database with proper initialization
• ✅ Start the React frontend on http://localhost:3000
• ✅ Start the FastAPI backend on http://localhost:8000
• ✅ Automatically handle all dependencies and networking between services
• ✅ No .env file configuration required for local development!

Alternative Setup

For instructions on manual setup or detailed deployment options, please refer to the respective README files in the frontend and backend directories.

🐳 Docker Compose Deployment

Quick Start: For the fastest local development setup, see the Getting Started section above for a single-command deployment that requires no configuration files.

The following section provides detailed information about Docker Compose deployment options for different environments and advanced configurations.

Prerequisites

• Docker and Docker Compose installed on your system
• Git (to clone the repository)

Environment Configuration

For local development: No .env file is required! Just use the quick start command above.

For production deployment: Create a .env file in the project root with the following variables:

# Database Configuration
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
DB_NAME=agent_games
TEST_DB_NAME=agent_games_test

# Security
SECRET_KEY=your_secure_secret_key

# Frontend Configuration (if building frontend within Docker)
REACT_APP_AGENT_API_URL=http://localhost:8000

Deployment Steps

1. Clone the repository:

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

2. Launch the services:

# For production deployment
docker-compose --profile prod up -d

# For development deployment (includes test database)
docker-compose --profile dev up -d

# For testing only
docker-compose --profile test up -d

This will start the following services:

• API backend (FastAPI) on port 8000
• Validator service on port 8001
• Simulator service on port 8002
• PostgreSQL database on port 5432
• PostgreSQL test database on port 5433 (only in dev and test profiles)

3. Initialize the database:

The first time you run the application, you need to initialize the database:

docker-compose exec api python -m backend.docker_utils.init_db

4. Access the application:
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs
   • Frontend (if deployed separately): http://localhost:3000

Service Management

# View logs
docker-compose logs -f

# View logs for a specific service
docker-compose logs -f api

# Stop all services
docker-compose down

# Stop and remove volumes (caution: this will delete database data)
docker-compose down -v

Resource Limits

Each service has memory and process limits configured to ensure stability:

• API: 400MB memory limit, 50 processes
• Validator: 500MB memory limit, 50 processes
• Simulator: 500MB memory limit, 50 processes
• PostgreSQL: 700MB memory limit

💻 Manual Local Development

💡 Tip: For most users, we recommend using the one-command Docker setup above instead of manual setup.

For detailed instructions on setting up the backend and frontend manually for local development, please see the Backend README.

📝 Notes

• Recommended: Use the single Docker Compose command for the easiest local development experience
• For manual setup: Make sure you have Python, Docker, Node.js, and npm installed on your machine
• Docker is required for running game simulations in secure containers
• The commands for manual setup assume you're using a Unix-based system (Linux or macOS). Windows commands may differ slightly, especially for activating the virtual environment
• The backend server runs on port 8000 by default, and the frontend runs on port 3000
• Use different terminals for running backend and frontend processes when doing manual setup