# 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