resolutionflow/DEV-ENV.md

DevServer01 Environment Setup & Operations Guide

Server Overview

• Hostname: devserver01
• IP Address: 192.168.0.9
• OS: Ubuntu 25.10 (Questing Quokka)
• CPU: AMD Ryzen 3 PRO 3200GE w/ Radeon Vega Graphics
• RAM: ~5.2GB (some reserved by Vega iGPU)
• Disk: 57GB LVM volume (/dev/mapper/ubuntu--vg-ubuntu--lv), ~47GB free
• Hardware: Lenovo ThinkCentre Micro Tower

Docker Setup

Docker was installed via the official convenience script:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker michael

Docker Compose is included with this installation.

Code-Server

Overview

Code-server (codercom/code-server) runs in a Docker container, providing a browser-accessible VS Code instance at https://192.168.0.9:8080. It uses a custom Dockerfile to include additional tools like gh (GitHub CLI).

Custom Dockerfile

Location: ~/docker/Dockerfile.code-server

FROM codercom/code-server:latest

USER root
RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && \
    chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg && \
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
    apt update && apt install -y gh && \
    rm -rf /var/lib/apt/lists/*
USER coder

Docker Compose File

Location: ~/docker/docker-compose.yml

services:
  code-server:
    build:
      context: .
      dockerfile: Dockerfile.code-server
    container_name: code-server
    environment:
      - PASSWORD=<password>
    volumes:
      - ./code-server/config/data:/home/coder/.local/share/code-server
      - ./code-server/config/extensions:/home/coder/.local/share/code-server/extensions
      - ./code-server/config/.config/code-server:/home/coder/.config/code-server
      - ./projects:/projects
      - ./code-server/certs:/certs
      - /home/michael/.claude:/home/coder/.claude
    ports:
      - 8080:8443
    command: --bind-addr 0.0.0.0:8443 --cert /certs/cert.pem --cert-key /certs/key.pem /projects
    user: "1000:1000"
    restart: unless-stopped

Key Details

• Container user: coder (UID 1000)
• Home directory inside container: /home/coder
• Projects mount: Host ~/docker/projects → Container /projects
• Claude Code config mount: Host /home/michael/.claude → Container /home/coder/.claude
• HTTPS: Self-signed certs via a custom Homelab CA
• Internal port: 8443 (code-server listens here)
• External port: 8080 (mapped to 8443 internally)
• Access URL: https://192.168.0.9:8080

SSL Certificates

Location: ~/docker/code-server/certs/

A custom Certificate Authority (CA) was created for the homelab:

• ca.key — CA private key
• ca.crt — CA certificate (imported into browsers to trust all homelab certs)
• key.pem — code-server private key
• cert.pem — code-server certificate (signed by CA)
• server.cnf — OpenSSL config with SANs for devserver01

The CA cert (ca.crt) has been imported into Firefox on client machines under Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import → "Trust this CA to identify websites."

Volume Mapping Reference

Host Path	Container Path	Purpose
~/docker/code-server/config/data	/home/coder/.local/share/code-server	VS Code user data, settings
~/docker/code-server/config/extensions	/home/coder/.local/share/code-server/extensions	VS Code extensions
~/docker/code-server/config/.config/code-server	/home/coder/.config/code-server	code-server config
~/docker/projects	/projects	All project repos
~/docker/code-server/certs	/certs	SSL certificates
/home/michael/.claude	/home/coder/.claude	Claude Code config, plugins, skills, history

Patherly / ResolutionFlow Dev Environment

Docker Compose (Dev)

Location: ~/docker/projects/patherly/docker-compose.dev.yml

This runs the full Patherly/ResolutionFlow stack:

• PostgreSQL (pgvector/pgvector:pg16) on port 5432
• Backend (FastAPI/Uvicorn) on port 8000
• Frontend (Vite/React) on port 5173

Environment Files

• ~/docker/projects/patherly/.env — Backend secrets (SECRET_KEY, API keys, etc.)
• ~/docker/projects/patherly/frontend/.env — Frontend config (VITE_API_URL)

Critical Configuration for Remote Access

Since the dev environment is accessed from other machines on the LAN (not localhost), these settings are required:

Frontend .env:

VITE_API_URL=http://192.168.0.9:8000

Backend CORS_ORIGINS in docker-compose.dev.yml:

- CORS_ORIGINS=["http://localhost:3000","http://localhost:5173","http://127.0.0.1:3000","http://127.0.0.1:5173","http://192.168.0.9:5173","http://192.168.0.9:3000"]

The 192.168.0.9 entries are required because browsers make requests from the client machine, where localhost refers to the client — not devserver01.

Starting the Dev Environment

cd ~/docker/projects/patherly
docker compose -f docker-compose.dev.yml up -d

Running Migrations (Fresh Database)

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

Rebuilding After Frontend .env Changes

Vite bakes environment variables at build time, so changes to VITE_API_URL require a rebuild:

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

Backend environment changes (like CORS_ORIGINS) only need a restart, not a rebuild.

Access URLs

• Frontend: http://192.168.0.9:5173
• Backend API: http://192.168.0.9:8000
• API Docs: http://192.168.0.9:8000/docs

Known Issues & Fixes

iptables DROP Rules Blocking Docker Traffic

Docker routes container traffic through the FORWARD chain. Rogue DROP rules in the DOCKER chain can block all container networking.

Symptoms: Container shows as running, port is listening via ss, but curl returns "Connection reset by peer" or "Connection refused" from other machines.

Diagnosis:

sudo iptables -L DOCKER -n --line-numbers

Look for blanket DROP rules:

2    DROP       all  --  0.0.0.0/0            0.0.0.0/0
3    DROP       all  --  0.0.0.0/0            0.0.0.0/0

Fix:

# Remove DROP rules (remove highest numbered first)
sudo iptables -D DOCKER 3
sudo iptables -D DOCKER 2

If the FORWARD chain has policy DROP and Docker containers can't communicate:

sudo systemctl restart docker

Docker rebuilds its iptables chains on restart. These rules don't persist across reboots by default — if they come back, something else is creating them.

Code-Server Port Mismatch

The codercom/code-server image listens on port 8443 internally, not 8080. The compose file must map 8080:8443:

ports:
  - 8080:8443

The code-server config file (/home/coder/.config/code-server/config.yaml) must bind to 0.0.0.0, not 127.0.0.1:

bind-addr: 0.0.0.0:8443

If it says 127.0.0.1, it will only accept connections from inside the container.

Permission Issues Inside Container

The container runs as user coder (UID 1000). Host files mounted into the container must be owned by UID 1000:

# Fix project permissions
sudo chown -R 1000:1000 ~/docker/projects

# Fix code-server config permissions
sudo chown -R 1000:1000 ~/docker/code-server/config/

# Fix Claude Code config permissions
sudo chown -R 1000:1000 ~/.claude/

GitHub CLI (gh) Auth

gh stores its config at /home/coder/.config/gh/. If it fails with permission denied:

docker exec -u root code-server mkdir -p /home/coder/.config/gh
docker exec -u root code-server chown -R 1000:1000 /home/coder/.config

Useful Commands

Check all running containers

docker ps

View logs for a specific container

docker logs <container_name> --tail 30

Restart code-server

cd ~/docker
docker compose up -d

Rebuild code-server (after Dockerfile changes)

cd ~/docker
docker compose down
docker compose up -d --build

Restart dev environment

cd ~/docker/projects/patherly
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up -d

SSH into devserver01

ssh michael@192.168.0.9

Check what's listening on ports

sudo ss -tlnp | grep <port>

Check firewall / iptables

sudo ufw status
sudo iptables -L -n --line-numbers
sudo iptables -L DOCKER -n --line-numbers

Execute commands inside containers

# As default user
docker exec code-server <command>

# As root
docker exec -u root code-server <command>

# Interactive shell
docker exec -it code-server bash

Network Info

• Server IP: 192.168.0.9
• Docker bridge network: 172.17.0.0/16 and 172.18.0.0/16
• Host user: michael (UID 1000)
• Container user: coder (UID 1000) — same UID allows seamless file sharing via volume mounts

Code-Server Browser Tips

• Command Palette: F1 (not Ctrl+Shift+P, which opens Firefox private window)
• Context Menu (right-click): Alt + Right Click
• Terminal: Ctrl+`
• Rename file: F2
• Go to definition: F12
• Find references: Shift+F12

Adding New Tools to Code-Server

To permanently add tools (survive container restarts), add them to ~/docker/Dockerfile.code-server:

USER root
RUN apt update && apt install -y <new-tool> && rm -rf /var/lib/apt/lists/*
USER coder

Then rebuild:

cd ~/docker
docker compose down
docker compose up -d --build

For temporary installs (gone after restart):

docker exec -u root code-server apt update
docker exec -u root code-server apt install -y <new-tool>