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:

test step: runs python manage.py test backlogger (all branches)
build-and-deploy (main only): builds k-boris-website image, restarts django container
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

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:

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:

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

{
  "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

Develop locally, test with Docker
Push to dev → CI runs tests + deploys to staging automatically
Check staging at https://debug.killmybacklog.com
Merge/push to main → CI deploys to production
Check logs at https://logs.k-boris.tech instead of SSH if something looks wrong

4.5 KiB Raw Blame History