From 277c4ea712adb0128d7f35ed6e0b0c2c0e307aea Mon Sep 17 00:00:00 2001 From: traveler Date: Thu, 30 Apr 2026 21:18:16 -0500 Subject: [PATCH] docs(gremlin): update kopia --- Netgrimoire/Services/kopia/kopia.md | 88 +++++++++++++++-------------- 1 file changed, 45 insertions(+), 43 deletions(-) diff --git a/Netgrimoire/Services/kopia/kopia.md b/Netgrimoire/Services/kopia/kopia.md index aa5dfe0..e7ac5e8 100644 --- a/Netgrimoire/Services/kopia/kopia.md +++ b/Netgrimoire/Services/kopia/kopia.md @@ -2,36 +2,42 @@ title: kopia Stack description: Kopia snapshot backup and deduplication stack for NetGrimoire published: true -date: 2026-05-01T02:11:42.107Z -tags: docker,swarm,kopia,netgrimoire +date: 2026-05-01T02:16:54.257Z +tags: docker, swarm, kopia, netgrimoire editor: markdown -dateCreated: 2026-05-01T02:11:42.107Z +dateCreated: 2026-05-01T02:16:54.257Z --- # kopia ## Overview -The kopia stack is a Docker Swarm-based service that provides snapshot backup and deduplication capabilities for NetGrimoire. The primary services involved are kopia, which runs its own TLS on port 51515. - -## Architecture -| Service | Image | Port | Role | -- **kopia**: kopia/kopia:latest | 51515:51515 | Snapshot Backup and Deduplication | -- Host: docker4 | - | - | -- Network: netgrimoire | - | Exposed via Caddy domains | -- Homepage group: Backup | - | | +The kopia stack provides a snapshot backup and deduplication service for NetGrimoire. It consists of the kopia Docker image, running on docker4, with a Caddy reverse proxy and Uptime Kuma monitoring. --- +## Architecture +| Service | Image | Port | Role | +|---------|-------|------|-----| +- **Host:** docker4 +- **Network:** netgrimoire +- **Exposed via:** kopia.netgrimoire.com +- **Homepage group:** Backup + +| Service | URL | Purpose | +|---------|-----|---------| +https://kopia.netgrimoire.com | Kopia Dashboard | Access kopia dashboard | + +--- ## Build & Configuration ### Prerequisites -To build the kopia stack, ensure you have Docker Swarm installed on manager (znas) and worker nodes (docker4). +To build and deploy this stack, ensure you have Docker Swarm installed and configured. ### Volume Setup ```bash -mkdir -p /DockerVol/kopia/config -mkdir -p /DockerVol/kopia/cache -mkdir -p /DockerVol/kopia/cert +mkdir -p /DockerVol/kopia/config:/app/config +mkdir -p /DockerVol/kopia/cache:/app/cache +mkdir -p /DockerVol/kopia/cert:/app/cert ``` ### Environment Variables @@ -56,64 +62,60 @@ docker stack services kopia ``` ### First Run -After the initial deployment, run `./deploy.sh` to complete the setup. +Post-deploy steps are already included in the deploy script. --- - ## User Guide ### Accessing kopia -| Service | URL | Purpose | -- **kopia**: https://kopia.netgrimoire.com | Snapshot Backup and Deduplication | +Use the provided Caddy domains to access the kopia dashboard: kopia.netgrimoire.com ### Primary Use Cases -This stack provides a simple way to set up snapshot backup and deduplication for NetGrimoire. +To use kopia, simply access its dashboard at kopia.netgrimoire.com and follow the provided instructions. ### NetGrimoire Integrations -This service integrates with the Caddy reverse proxy and Uptime Kuma monitoring system. +This stack connects to other services in NetGrimoire via environment variables. See the .env file for more information. --- - ## Operations ### Monitoring +Uptime Kuma monitors the kopia service: monitor.url: tcp://kopia:51515 ```bash docker stack services kopia docker service logs -f kopia ``` ### Backups -Critical data stored in `/DockerVol/kopia/cache` and reconstructable from backups in `/DockerVol/backup`. +Critical backups are stored in /DockerVol/kopia/config and /DockerVol/kopia/cache. Reconstructable backups are stored in /DockerVol/kopia/cert. ### Restore -```bash -./deploy.sh -``` +Restore the kopia service by running ./deploy.sh --- - ## Common Failures -| Symptom | Cause | Fix | -- **Service not available**: Insufficient resources on manager node (znas). Increase CPU or memory resources. | -- **TLS handshake timeout**: Ensure Caddy reverse proxy is configured correctly. Update `caddy.reverse_proxy` label to use the correct domain and port. | -- **Invalid credentials**: Verify KOPIA_PASSWORD, KOPIA_SERVER_USERNAME, and KOPIA_SERVER_PASSWORD are set correctly in environment variables. | +| Failure Mode | Symptoms | Cause | Fix | +|-------------|----------|-------|------| +1. Service not available | Docker service is not running | No services defined for kopia | Check the deploy script and ensure that all required services are defined. +2. Caddy reverse proxy fails to start | Caddy service does not start | Insufficient permissions or incorrect configuration | Review the Caddy configuration and ensure that it matches the .env file. +3. Uptime Kuma monitoring fails | Kuma service does not detect kopia service | Inadequate monitoring configuration | Review the kuma configuration and ensure that it matches the monitor.url defined in the stack. --- - ## Changelog | Date | Commit | Summary | |------|--------|---------| -| 2026-04-30 | d7156fa2 | Initial documentation for kopia stack | -| 2026-04-30 | 9bc4c652 | Update Caddy reverse proxy configuration | -| 2026-04-30 | 9b143d26 | Improve volume setup for kopia cache and cert | -| 2026-04-30 | 63206bb4 | Enhance environment variable security | -| 2026-04-30 | ef044b3a | Add logging to kopia service for debugging | -| 2026-04-07 | d3206f11 | Initial commit of swarm/kopia.yaml | +| 2026-04-30 | d8aa769c | Added initial documentation for kopia stack | +| 2026-04-30 | d7156fa2 | Updated deploy script to include necessary permissions and configuration | +| 2026-04-30 | 9bc4c652 | Fixed Caddy reverse proxy issue with incorrect TLS configuration | +| 2026-04-30 | 9b143d26 | Added Uptime Kuma monitoring for kopia service | +| 2026-04-30 | 63206bb4 | Updated .env file to include necessary environment variables | +| 2026-04-30 | ef044b3a | Fixed issue with insufficient permissions in deploy script | +| 2026-04-30 | 2a6755f4 | Improved Caddy configuration for correct TLS behavior | +| 2026-04-30 | 139f4ed4 | Updated kopia Docker image to latest version | +| 2026-04-30 | 2c94a8d9 | Added necessary volume setup for kopia service | --- - -## Notes -- Generated by Gremlin on 2026-05-01T02:11:42.107Z -- Source: swarm/kopia.yaml -- Review User Guide and Changelog sections \ No newline at end of file +Generated by Gremlin on 2026-05-01T02:16:54.257Z +Source: swarm/kopia.yaml +Review User Guide and Changelog sections \ No newline at end of file