Hannibal Dev Environments

All dev environments run on a single VPS: hanndev (7.7GB RAM, 4 CPU).

Environment Inventory

Env	Subdomain	Mode	Frontend	Backend	Postgres	Redis	AI Chat	Network	~RAM
staging	hannibaldev.forsyt.io	full	:3000	:3001	hannibal-postgres:5432 / hannibal	hannibal-redis:6379	:8000	hannibaldev_hannibal-network	—
prdev	testhannibal.forsyt.io	light	:3002	:3003	hannibal-postgres / hannibal_testing	hannibal-redis	staging	hannibaldev_hannibal-network	~140MB
pmdev	bbook.forsyt.io	full	:3004	:3005	bbook-postgres:5433 / bbook	bbook-redis:6380	:8001	bbook_bbook-network	~250MB
bhdev	bhdev.forsyt.io	full	:3006	:3007	bhdev-postgres:5434 / hannibal_bhdev	bhdev-redis:6381	:8002	bhdev_bhdev-network	~250MB
badev	badev.forsyt.io	light	:3008	:3009	hannibal-postgres / hannibal_badev	hannibal-redis	staging	hannibaldev_hannibal-network	~140MB

Port Map (Quick Reference)

Port	Service
3000	staging frontend
3001	staging backend
3002	prdev frontend
3003	prdev backend
3004	pmdev frontend
3005	pmdev backend
3006	bhdev frontend
3007	bhdev backend
3008	badev frontend
3009	badev backend
5432	staging postgres (hannibal-postgres)
5433	pmdev postgres (bbook-postgres)
5434	bhdev postgres (bhdev-postgres)
6379	staging redis (hannibal-redis)
6380	pmdev redis (bbook-redis)
6381	bhdev redis (bhdev-redis)
8000	staging ai-chat
8001	pmdev ai-chat
8002	bhdev ai-chat

Isolation Modes

Full Isolation

Own postgres, redis, ai-chat, backend, frontend. ~250MB additional RAM.

• Pros: No interference with other envs, can run destructive DB ops freely
• Cons: More RAM, more containers to manage
• Used by: staging, pmdev, bhdev

Lightweight

Only backend + frontend. Joins staging's Docker network for shared postgres/redis/ai-chat. ~140MB additional RAM.

• Pros: Less RAM, faster to set up
• Cons: Shares DB server (separate database though), shares Redis keyspace, shares AI chat
• Used by: prdev, badev

Adding a New Dev Environment

# On the dev server
cd /root
git clone git@github.com:ForSyt-io/Hannibal.git {devname}
cd {devname}
git checkout feat/{devname}  # or create the branch

# Run the setup script
bash docs/infra/setup-dev-env.sh --name {devname} --mode {full|light}

# Follow the printed instructions (copy .env, nginx config, certbot, etc.)

Or manually:

1. Choose next available port pair (check Port Map above)
2. Copy the appropriate template from docs/infra/
3. Create .env.{devname} for backend (and ai-chat if full mode)
4. Create nginx config from template
5. Run certbot --nginx -d {devname}.forsyt.io
6. docker compose -f docker-compose.{devname}.yml up -d --build
7. Run migrations + seed

Removing a Dev Environment

# Stop and remove containers
docker compose -f docker-compose.{devname}.yml down -v

# Remove nginx config
sudo rm /etc/nginx/sites-enabled/{devname}.forsyt.io
sudo nginx -t && sudo systemctl reload nginx

# For lightweight envs, drop the database
docker exec hannibal-postgres psql -U hannibal -d hannibal -c 'DROP DATABASE hannibal_{devname};'

# Remove the repo clone
rm -rf /root/{devname}

Deploying Updates

Each dev env is a separate git clone on the server. To deploy:

cd /root/{devname}
git pull origin feat/{devname}
docker compose -f docker-compose.{devname}.yml up -d --build
docker compose -f docker-compose.{devname}.yml run --rm backend npx prisma migrate deploy

Shared Resources

• DNS: All *.forsyt.io subdomains point to the VPS via Cloudflare wildcard
• SSL: Certbot with nginx plugin, auto-renewal via systemd timer
• API Keys: Betfair, Pinnacle, BetsAPI, OddsPAPI credentials are shared across all dev envs (same test accounts)
• Web3Auth: Same client ID across all envs (configured for all subdomains)

Troubleshooting

Container won't start

docker compose -f docker-compose.{devname}.yml logs {service}

Port conflict

Check netstat -tlnp | grep {port} — another env may be using it.

Database connection refused (lightweight env)

Verify staging stack is running: docker ps | grep hannibal-postgres

Frontend shows "Authentication service error"

Check that NEXT_PUBLIC_WEB3AUTH_CLIENT_ID build arg matches the Web3Auth dashboard config. Rebuild frontend: docker compose -f docker-compose.{devname}.yml up -d --build frontend