MapCTF

Map-based CTF/cyber-range platform.

MapCTF is a map-based CTF/cyber-range platform with:

• A Go backend (API + map service)
• A React + TypeScript frontend
• PostgreSQL and Redis for state/session storage

Warning

MapCTF is under active development. Review configuration and deployment settings before running in production.

Architecture

The development stack is split into four main runtime components:

• mapctf-api on :8081 (REST/API workflows)
• mapctf-map on :8082 (map/gameboard and template/static serving)
• mapctf-postgres on :5432 (persistent relational data)
• mapctf-redis on :6379 (cache and session store)

In this repository, frontend development runs separately with Vite (default :3000).

Project Structure

mapctf/
├── backend/
│   ├── cmd/
│   │   ├── api/            # API service entrypoint
│   │   ├── map/            # Map service entrypoint + handlers/templates
│   │   └── cli/            # CLI utilities
│   ├── pkg/
│   │   ├── backend/        # DB layer
│   │   ├── cache/          # Redis/cache primitives
│   │   ├── challenges/     # Challenge domain logic
│   │   ├── config/         # Config types/flags/validation
│   │   ├── teams/          # Team domain logic
│   │   ├── users/          # User/auth domain logic
│   │   └── version/        # Version metadata
│   └── Makefile            # Backend build/run/test targets
├── frontend/
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/          # Route/page components
│   │   ├── services/       # API client calls
│   │   ├── contexts/       # React context state
│   │   ├── styles/         # SCSS/CSS modules
│   │   ├── types/          # TS models/types
│   │   └── utils/          # UI helpers
│   ├── public/             # Public assets
│   └── htmls/              # Legacy/static map HTML assets
├── deploy/
│   ├── config/             # Example configuration files
│   └── docker/
│       ├── conf/
│       └── dockerfiles/    # Dev Dockerfiles for api/map/frontend
├── docker-compose-dev.yml  # Dev services (api, map, postgres, redis)
├── Makefile                # Root convenience targets
└── ARCHITECTURE.md         # Deeper architecture notes

Quick Start (Docker)

1. Copy environment defaults:

cp .env.example .env

2. Start backend services:

docker compose -f docker-compose-dev.yml up --build

3. Start frontend (separate terminal):

cd frontend
npm install
npm run dev

4. Open:

• Frontend: http://localhost:3000
• API: http://localhost:8081
• Map service: http://localhost:8082

Local Development (No Docker for Go Services)

Start only DB/Redis with Docker:

make up-backend

Run services locally:

# API
cd backend
make run_api

# Map service
cd backend
make run_map

# Frontend
cd frontend
npm install
npm run dev

Useful Commands

Root Makefile:

• make docker_dev_build build dev images
• make docker_dev_up run compose stack
• make docker_dev_down stop compose stack
• make docker_dev_logs_api tail API logs
• make docker_dev_logs_map tail map logs

Backend Makefile (backend/):

• make build build API + map binaries
• make run_api run API with go run
• make run_map run map service with go run
• make test run backend package tests

Frontend (frontend/):

• npm run dev start Vite dev server
• npm run build production build
• npm run lint lint TS/React code

Configuration

Primary development variables are in .env (see .env.example), including:

• Toolchain/image versions (GOLANG_VERSION, NODE_VERSION)
• Database credentials/ports
• Redis settings
• Bootstrap admin credentials
• Map UUID (MAP_UUID)

Backend also supports CLI flags and YAML configuration (example: deploy/config/mapctf.example.yaml).

Additional Docs

• ARCHITECTURE.md deeper dives into design decisions, data models, and service interactions.

License

GPL-3.0. See LICENSE.