152 lines
4.5 KiB
Markdown
152 lines
4.5 KiB
Markdown
# k-boris website — Claude context
|
|
|
|
Django project serving **k-boris.tech** and **killmybacklog.com**.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
website/
|
|
backlogger/ # Main app: game/book/movie backlog tracker
|
|
core/ # Landing page and shared views
|
|
dailystone/ # Daily mineral fact feature
|
|
kboris/ # Django project settings & URLs
|
|
nginx/ # Nginx site configs (for reference; deployed on VPS)
|
|
Dockerfile
|
|
entrypoint.sh # Runs migrate + loaddata, then gunicorn on :8080
|
|
requirements.txt
|
|
.woodpecker.yml
|
|
```
|
|
|
|
- Database: SQLite at `/data/db.sqlite3` (volume-mounted on VPS, not committed)
|
|
- Static files: collected to `staticfiles/`, served by WhiteNoise
|
|
- Auth env vars: `DJANGO_SECRET_KEY`, `STEAM_API_KEY`
|
|
|
|
## CI/CD — Woodpecker
|
|
|
|
Woodpecker CI runs at **https://ci.k-boris.tech** (Gitea OAuth, admin: boris).
|
|
|
|
Pipeline defined in `.woodpecker.yml`:
|
|
1. **test** step: runs `python manage.py test backlogger` (all branches)
|
|
2. **build-and-deploy** (main only): builds `k-boris-website` image, restarts `django` container
|
|
3. **build-and-deploy-dev** (dev only): builds `k-boris-website-dev` image, restarts `django-dev` container
|
|
|
|
Push to `main` → production. Push to `dev` → staging (DEBUG=true, port 8081).
|
|
|
|
The agent shares the host Docker socket, so it builds directly on the VPS.
|
|
|
|
## VPS access & Docker logs
|
|
|
|
```bash
|
|
ssh boris@46.202.143.107 # key: ~/.ssh/id_ed25519
|
|
|
|
# Production logs
|
|
ssh boris@46.202.143.107 "docker logs django --tail=50"
|
|
ssh boris@46.202.143.107 "docker logs django -f"
|
|
|
|
# Dev/staging logs
|
|
ssh boris@46.202.143.107 "docker logs django-dev --tail=50"
|
|
|
|
# Woodpecker / Gitea logs
|
|
ssh boris@46.202.143.107 "docker logs woodpecker-agent --tail=50"
|
|
ssh boris@46.202.143.107 "docker logs gitea --tail=30"
|
|
|
|
# All services
|
|
ssh boris@46.202.143.107 "docker ps"
|
|
ssh boris@46.202.143.107 "cd /opt/services && docker compose ps"
|
|
```
|
|
|
|
Compose file lives at `/opt/services/docker-compose.yml` on the VPS.
|
|
|
|
## Running locally with Docker (preferred)
|
|
|
|
Avoid setting up a Python venv locally — use Docker instead for quick checks:
|
|
|
|
```bash
|
|
cd website
|
|
|
|
# Build
|
|
docker build --build-arg DJANGO_SECRET_KEY=local-dev-key -t k-boris-local .
|
|
|
|
# Run (no persistent data)
|
|
docker run --rm -p 8080:8080 \
|
|
-e DJANGO_SECRET_KEY=local-dev-key \
|
|
-e STEAM_API_KEY=your_key_here \
|
|
-e DEBUG=true \
|
|
k-boris-local
|
|
|
|
# Run with a persistent local DB volume
|
|
docker run --rm -p 8080:8080 \
|
|
-e DJANGO_SECRET_KEY=local-dev-key \
|
|
-e DEBUG=true \
|
|
-v "$(pwd)/.local-data:/data" \
|
|
k-boris-local
|
|
```
|
|
|
|
Then open http://localhost:8080.
|
|
|
|
## Running tests locally
|
|
|
|
Tests don't need a running server — use the Docker image or a venv:
|
|
|
|
```bash
|
|
# Via Docker (no setup needed)
|
|
docker run --rm \
|
|
-e DJANGO_SECRET_KEY=test-key \
|
|
k-boris-local \
|
|
python manage.py test backlogger --verbosity=2
|
|
|
|
# Or directly if you have a venv active
|
|
python manage.py test backlogger
|
|
```
|
|
|
|
Tests live in `backlogger/tests.py` only. The CI only tests the `backlogger` app.
|
|
|
|
## Key URLs
|
|
|
|
| Environment | URL | Container | Port |
|
|
|---|---|---|---|
|
|
| Production | https://k-boris.tech / https://killmybacklog.com | `django` | 8080 |
|
|
| Staging/dev | https://debug.killmybacklog.com | `django-dev` | 8081 |
|
|
| Gitea | https://git.k-boris.tech | `gitea` | 3000 |
|
|
| Woodpecker | https://ci.k-boris.tech | `woodpecker-server` | 8000 |
|
|
| Dozzle (logs) | https://logs.k-boris.tech | `dozzle` | 8888 |
|
|
|
|
## Monitoring & Logs
|
|
|
|
**Dozzle** at https://logs.k-boris.tech provides a web UI for all Docker container logs.
|
|
Login: username `boris` (password in 1Password / your password manager).
|
|
Use this instead of SSH log-tailing during development.
|
|
|
|
Auth config lives at `/opt/services/dozzle/users.yml` on the VPS.
|
|
To update password: `docker run --rm httpd:alpine htpasswd -nbB boris 'newpassword'` → paste hash into users.yml.
|
|
|
|
## Claude Code tooling
|
|
|
|
### Playwright MCP (browser + screenshots)
|
|
|
|
Allows Claude to browse the live sites and take screenshots without manual intervention.
|
|
|
|
Add to `~/.claude/settings.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"playwright": {
|
|
"command": "npx",
|
|
"args": ["@playwright/mcp@latest", "--headless"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Requires Node.js / npx available on the machine. `@playwright/mcp` is downloaded on first use.
|
|
Restart Claude Code after editing settings.json.
|
|
|
|
## Workflow
|
|
|
|
1. Develop locally, test with Docker
|
|
2. Push to `dev` → CI runs tests + deploys to staging automatically
|
|
3. Check staging at https://debug.killmybacklog.com
|
|
4. Merge/push to `main` → CI deploys to production
|
|
5. Check logs at https://logs.k-boris.tech instead of SSH if something looks wrong
|