chihlasm/resolutionflow
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore: clean up root directory — archive completed docs, add marketing assets

Browse Source 
Move 9 completed/historical docs from root to docs/archive/:
- ARCHITECTURE.md, BACKLOG.md, CLAUDE-SETUP.md, MICHAEL-NOTES.md
- IMPLEMENTATION-SUMMARY-ISSUE-34.md, PHASE-2.5-PERSONAL-BRANCHING.md
- REBRAND-IMPLEMENTATION-GUIDE.md, TS-EXAMPLES.md, WORKSPACE-REMOVAL-PLAN.md

Move QUICK-START.md to docs/

Add previously untracked files:
- DEV-ENV.md (devserver01 setup guide)
- docs/marketing/ (one-pager HTML + PDF)
- docs/ResolutionFlow_Pivot_Architecture.docx

Update CLAUDE.md rebrand guide reference path.

Deleted temp files: .temp_fixed.py, .temp_fixed2.py, ai_provider_*.py,
ai_provider.patch, test_write.txt

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
chihlasm
2026-03-21 15:12:07 +00:00
parent 0c51198556
commit a955888acf
17 changed files with 1231 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
DEV-ENV.md Normal file
View File

@@ -0,0 +1,350 @@
# 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:
```bash
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`
```dockerfile
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`
```yaml
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`:**
```yaml
- 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
```bash
cd ~/docker/projects/patherly
docker compose -f docker-compose.dev.yml up -d
```
### Running Migrations (Fresh Database)
```bash
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
```
### Rebuilding After Frontend .env Changes
Vite bakes environment variables at build time, so changes to `VITE_API_URL` require a rebuild:
```bash
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:**
```bash
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:**
```bash
# 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:
```bash
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`:
```yaml
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`:
```yaml
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:
```bash
# 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:
```bash
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
```bash
docker ps
```
### View logs for a specific container
```bash
docker logs <container_name> --tail 30
```
### Restart code-server
```bash
cd ~/docker
docker compose up -d
```
### Rebuild code-server (after Dockerfile changes)
```bash
cd ~/docker
docker compose down
docker compose up -d --build
```
### Restart dev environment
```bash
cd ~/docker/projects/patherly
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up -d
```
### SSH into devserver01
```bash
ssh michael@192.168.0.9
```
### Check what's listening on ports
```bash
sudo ss -tlnp | grep <port>
```
### Check firewall / iptables
```bash
sudo ufw status
sudo iptables -L -n --line-numbers
sudo iptables -L DOCKER -n --line-numbers
```
### Execute commands inside containers
```bash
# 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`:
```dockerfile
USER root
RUN apt update && apt install -y <new-tool> && rm -rf /var/lib/apt/lists/*
USER coder
```
Then rebuild:
```bash
cd ~/docker
docker compose down
docker compose up -d --build
```
For temporary installs (gone after restart):
```bash
docker exec -u root code-server apt update
docker exec -u root code-server apt install -y <new-tool>
```