Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• app.py
• database/init_db.py
• models/team.py
• services/code_runner.py
• routes/arena_routes.py
• admin_reset.py

Introduction

The Debug Arena is a real-time competitive debugging platform designed for live coding events. It utilizes a Flask-based backend, SQLAlchemy for data persistence, and a multi-layered security system involving both client-side proctoring and server-side code execution isolation.

This guide outlines the technical requirements, environmental configurations, and architectural setup necessary to deploy the platform for production or local development use. The platform supports SQLite for development and is production-ready for PostgreSQL.
Sources: README.md:3-9, app.py:24-28

System Architecture

The application follows a modular architecture where the Flask application acts as the central gatekeeper, managing authentication, session validation, and level access while delegating code execution to a secure evaluation engine.

The architecture ensures that all code submissions are validated against a safety blacklist before execution.
Sources: README.md:58-75, services/code_runner.py:5-9

Environment Configuration

The application is configured through environment variables and local path definitions to ensure portability between development and production environments.

Application Configuration

Variable	Description	Default Value	Source
SECRET_KEY	Flask session encryption key	dev-key-123	app.py:19
DATABASE_URL	SQLAlchemy connection string	sqlite:///instance/db.sqlite3	app.py:24
SQLALCHEMY_TRACK_MODIFICATIONS	Toggle track modifications	False	app.py:29

Directory Structure Requirements

The deployment environment must allow the creation of an instance/ folder at the project root to store the default SQLite database. The application attempts to create this directory automatically during startup.
Sources: app.py:32-36

Database Initialization

The platform requires a schema setup to store team profiles, scores, and violation counts.

Data Model Schema

Setup Procedures

1. Dependency Installation: Install all required packages using pip install -r requirements.txt. Sources: README.md:88
2. Schema Creation: Run python database/init_db.py to initialize the database file and create all tables within the app context. Sources: database/init_db.py:1-18
3. App Context: The application also includes a safety check in app.py that runs db.create_all() on every startup to ensure the environment is consistent. Sources: app.py:48-52

Security & Execution Isolation

Deployment requires the host environment to support subprocess.run as the platform executes user-submitted Python code in a separate process.

Execution Constraints

• Time Limit: Code execution is strictly capped at 2 seconds to prevent infinite loops or resource exhaustion. Sources: services/code_runner.py:18
• Safety Scan: A blacklist prevents the use of dangerous modules like os, sys, and subprocess, and blocks functions like eval() and exec(). Sources: utils/security.py:5-13
• Isolation: shell=False is used in the subprocess call to prevent shell injection attacks. Sources: services/code_runner.py:19

Administrative Operations

Administrators can manage the live event through CLI scripts to override team states.

Reinstating Disqualified Teams

If a team is disqualified due to excessive violations (3 detections), an administrator can manually reset their status:

python admin_reset.py <team_name>

This script sets the violations count to 0 while preserving their current score and level progress.
Sources: admin_reset.py:5-24, routes/arena_routes.py:112-117

Summary

The Debug Arena deployment centers on a Flask application supported by a robust security middleware. Successful deployment requires configuring the SECRET_KEY, initializing the SQLite or PostgreSQL database via the provided init_db.py script, and ensuring the host environment can safely spawn restricted subprocesses for Python code evaluation. Final rankings and team statuses are maintained persistently to allow real-time leaderboard updates during competitive events.
Sources: app.py:1-60, README.md:1-20