nextcloud-selfhosted/CLAUDE.md

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

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