262 lines
7.1 KiB
Markdown
262 lines
7.1 KiB
Markdown
# 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` |