resolutionflow/DEV-ENV.md

ResolutionFlow Dev Environment Setup & Operations Guide

Server Overview

• Provider: Hostinger KVM VPS (srv1522117)
• IP Address: 46.202.92.250
• OS: Ubuntu 24.04 LTS
• CPU: 2 vCPU cores
• RAM: 8GB
• Disk: 100GB NVMe SSD
• Swap: 4GB (/swapfile, swappiness=10)

Architecture

All services run as Docker containers on the host, managed via SSH or from the VS Code Server integrated terminal.

Host (root@srv1522117)
├── Traefik                       → reverse proxy + auto SSL (Let's Encrypt)
├── VS Code Server                → browser IDE at https://code.resolutionflow.com
└── ResolutionFlow Stack
    ├── resolutionflow_frontend   → Vite/React on port 5173
    ├── resolutionflow_backend    → FastAPI/Uvicorn on port 8000
    └── resolutionflow_postgres   → PostgreSQL 16 + pgvector on port 5432

Access URLs

Service	URL
VS Code Server	https://code.resolutionflow.com
Frontend (dev)	http://46.202.92.250:5173
Backend API	http://46.202.92.250:8000
API Docs	http://46.202.92.250:8000/docs

Docker Layout

/docker/
├── traefik/
│   ├── docker-compose.yml    → Traefik reverse proxy
│   └── .env                  → ACME_EMAIL for Let's Encrypt
└── vscode/
    ├── docker-compose.yml    → VS Code Server
    └── .env                  → CODE_PASSWORD

Project lives inside the VS Code Server Docker volume:

/var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow/

VS Code Server

• Container user: coder (UID 1000)
• Home directory: /home/coder
• Project location: /home/coder/resolutionflow
• Host volume path: /var/lib/docker/volumes/vscode_vscode-data/_data
• Access URL: https://code.resolutionflow.com
• HTTPS: Auto-provisioned via Traefik + Let's Encrypt

Compose File Location

/docker/vscode/docker-compose.yml

Traefik

Handles reverse proxying and automatic SSL for all services. HTTP automatically redirects to HTTPS.

Adding A New Service Behind Traefik

Add these labels to any new Docker service:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.<n>.rule=Host(`subdomain.resolutionflow.com`)"
  - "traefik.http.routers.<n>.entrypoints=websecure"
  - "traefik.http.routers.<n>.tls.certresolver=letsencrypt"
  - "traefik.http.services.<n>.loadbalancer.server.port=<port>"

Also create an A record in DNS pointing the subdomain to 46.202.92.250.

ResolutionFlow Dev Stack

Important: No Docker Inside VS Code Container

The VS Code Server container does NOT have Docker. All docker compose commands must be run via SSH as root on the host.

Environment Files

File	Purpose
.env	Root — Docker Compose interpolation (SECRET_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_API_KEY, POSTGRES_PORT)
backend/.env	Backend source of truth — all FastAPI settings, API keys, DB URLs, CORS
frontend/.env	Frontend — VITE_API_URL pointing to backend

Critical Remote Access Config

frontend/.env:

VITE_API_URL=http://46.202.92.250:8000

backend/.env:

CORS_ORIGINS=["http://localhost:3000","http://localhost:5173","http://127.0.0.1:3000","http://127.0.0.1:5173","http://46.202.92.250:5173","http://46.202.92.250:3000","https://resolutionflow.com","https://www.resolutionflow.com"]
FRONTEND_URL=http://46.202.92.250:5173
DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/resolutionflow
DATABASE_URL_SYNC=postgresql://postgres:postgres@db:5432/resolutionflow

Note: DATABASE_URL uses @db:5432 (Docker service name), not @localhost.

docker-compose.dev.yml:

- VITE_API_URL=http://46.202.92.250:8000

Starting the Dev Environment

SSH into host as root:

cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
docker compose -f docker-compose.dev.yml up -d

Running Migrations (Fresh Database)

cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
docker compose -f docker-compose.dev.yml run --rm backend alembic upgrade head

Seeding Test Users

docker exec resolutionflow_backend python -m scripts.seed_test_users

Test accounts (password: TestPass123!):

Email	Role	Plan
admin@resolutionflow.example.com	Owner	Team
pro@resolutionflow.example.com	Owner	Pro
teamadmin@resolutionflow.example.com	Owner	Team
engineer@resolutionflow.example.com	Engineer	Shared

Rebuilding After Config Changes

Frontend (Vite bakes env vars at build time — requires rebuild):

cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
docker compose -f docker-compose.dev.yml up -d --build frontend

Backend (restart only):

docker compose -f docker-compose.dev.yml restart backend

Full restart:

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

Installed Tools (Inside VS Code Server Container)

Installed in /home/coder — persists via Docker volume:

• nvm — Node version manager
• Node.js 20.x — via nvm, default alias set
• npm — latest
• GitHub CLI (gh) — authenticated via personal access token
• Claude Code CLI — @anthropic-ai/claude-code (global npm)

Permanent Tool Installs

Tools installed via apt inside the container do NOT survive container rebuilds. To add permanently, modify the VS Code Server Docker image and rebuild.

Temporary (session only):

sudo apt update && sudo apt install -y <tool>

SSH Access

ssh root@46.202.92.250

Key auth configured via ~/.ssh/authorized_keys on host.

Useful Commands

Check all running containers

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

View container logs

docker logs <container_name> --tail 30 -f

Restart VS Code Server

cd /docker/vscode && docker compose restart

Restart Traefik

cd /docker/traefik && docker compose restart

Restart dev stack

cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up -d

Check swap

free -h && swapon --show

Check disk

df -h

Check memory + container usage

free -h && docker stats --no-stream

DNS Records (resolutionflow.com)

Type	Name	Value	Purpose
A	code	46.202.92.250	VS Code Server

Security Notes

• UFW is inactive — Traefik and Docker manage port exposure
• All public-facing services run through Traefik with valid HTTPS certs
• PostgreSQL port 5432 is exposed on all interfaces — restrict if needed in production
• Rotate API keys (Anthropic, Voyage) if ever exposed in logs or chat
• Never commit .env files to Git

VS Code Server Browser Tips

• Command Palette: F1
• Terminal: Ctrl+`
• Rename file: F2
• Go to definition: F12
• Find references: Shift+F12
• Context Menu: Alt + Right Click