61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
GitOps-style Docker Compose setup for a self-hosted VPS running Nextcloud, Gitea, and monitoring on domain `t-gstone.de`. Not a code project — it's infrastructure-as-config with shell scripts.
|
|
|
|
## Architecture
|
|
|
|
A root `docker-compose.yml` uses `include` to compose four service stacks, each with its own `docker-compose.yml`:
|
|
|
|
- **caddy/** — Reverse proxy with auto HTTPS. All services route through the shared `proxy` Docker network.
|
|
- **nextcloud/** — Nextcloud 29 + PostgreSQL 16 + Redis 7 + cron container. Has its own `.env` for DB credentials and Nextcloud config. Uses internal `nextcloud-internal` network for DB/Redis isolation.
|
|
- **gitea/** — Gitea (rootless, SQLite). Exposes SSH on port 2222. Has its own `.env`.
|
|
- **monitoring/** — Grafana Alloy collecting Docker logs (Loki) and node metrics (Prometheus) to Grafana Cloud. Has its own `.env` for cloud credentials.
|
|
|
|
Key design patterns:
|
|
- Root `docker-compose.yml` includes all stacks via `include:` — single command to manage everything
|
|
- All stacks share the external `proxy` Docker network for Caddy routing
|
|
- Root `.env` provides `DATA_ROOT` and `DOMAIN` (pass via `--env-file .env`)
|
|
- Service-specific secrets live in per-service `.env` files (loaded via `env_file:` in compose)
|
|
- All persistent data under `${DATA_ROOT}` (default `/opt/docker-data/`)
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Deploy everything (installs Docker if needed, creates dirs, starts all stacks)
|
|
./scripts/deploy.sh
|
|
|
|
# Manage all services
|
|
docker compose --env-file .env up -d
|
|
docker compose --env-file .env logs -f
|
|
docker compose --env-file .env down
|
|
|
|
# Manage individual services
|
|
docker compose -f <service>/docker-compose.yml --env-file .env up -d
|
|
docker compose -f <service>/docker-compose.yml --env-file .env logs -f
|
|
docker compose -f <service>/docker-compose.yml --env-file .env down
|
|
|
|
# Reload Caddy after Caddyfile changes
|
|
docker exec caddy caddy reload --config /etc/caddy/Caddyfile
|
|
|
|
# Backup / Restore
|
|
./scripts/backup.sh
|
|
./scripts/restore.sh <YYYY-MM-DD>
|
|
```
|
|
|
|
## Adding a New Service
|
|
|
|
1. Create `myapp/docker-compose.yml` joining the `proxy` external network, with data under `${DATA_ROOT}/myapp/`
|
|
2. Add `- path: myapp/docker-compose.yml` to root `docker-compose.yml`
|
|
3. Add reverse proxy entry in `caddy/Caddyfile`
|
|
4. Add data directory creation to `scripts/deploy.sh`
|
|
5. Add backup steps to `scripts/backup.sh` if it has persistent data
|
|
6. Create DNS A record for the subdomain
|
|
|
|
## Environment Files
|
|
|
|
Root `.env` provides `DOMAIN` and `DATA_ROOT`. Each service directory has its own `.env` (copied from `.env.example`) for service-specific secrets. The `.env` files are gitignored.
|