# 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:

```yaml
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`:**
```yaml
- VITE_API_URL=http://46.202.92.250:8000
```

### Starting the Dev Environment

SSH into host as root:

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

### Running Migrations (Fresh Database)

```bash
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

```bash
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):
```bash
cd /var/lib/docker/volumes/vscode_vscode-data/_data/resolutionflow
docker compose -f docker-compose.dev.yml up -d --build frontend
```

**Backend** (restart only):
```bash
docker compose -f docker-compose.dev.yml restart backend
```

**Full restart:**
```bash
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):
```bash
sudo apt update && sudo apt install -y <tool>
```

## SSH Access

```bash
ssh root@46.202.92.250
```

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

## Useful Commands

### Check all running containers
```bash
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```

### View container logs
```bash
docker logs <container_name> --tail 30 -f
```

### Restart VS Code Server
```bash
cd /docker/vscode && docker compose restart
```

### Restart Traefik
```bash
cd /docker/traefik && docker compose restart
```

### Restart dev stack
```bash
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
```bash
free -h && swapon --show
```

### Check disk
```bash
df -h
```

### Check memory + container usage
```bash
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`