From de66eeec2dea5263d4f7171f63db7f6dacb606fa Mon Sep 17 00:00:00 2001 From: traveler Date: Thu, 30 Apr 2026 19:03:25 -0500 Subject: [PATCH] docs(gremlin): update kopia --- Netgrimoire/Services/kopia/kopia.md | 82 ++++++++++++++++++++--------- 1 file changed, 56 insertions(+), 26 deletions(-) diff --git a/Netgrimoire/Services/kopia/kopia.md b/Netgrimoire/Services/kopia/kopia.md index f8c9261..a1c44b7 100644 --- a/Netgrimoire/Services/kopia/kopia.md +++ b/Netgrimoire/Services/kopia/kopia.md @@ -1,32 +1,31 @@ +# kopia Stack + +description: NetGrimoire Kopia Service + --- title: kopia Stack -description: Snapshot backup and deduplication service in NetGrimoire. -published: true -date: 2026-04-30T23:46:07.706Z -tags: docker,swarm,kopia,netgrimoire -editor: markdown -dateCreated: 2026-04-30T23:46:07.706Z --- -# kopia - ## Overview -The kopia stack is a Docker Swarm service that provides snapshot backup and deduplication capabilities in NetGrimoire. It includes the kopia container, which runs as the root user with a password set by the environment variable KOPIA_PASSWORD. +The kopia stack is a Docker Swarm-based service that runs the Kopia backup and deduplication tool. It provides a reliable and efficient solution for snapshot backups and deduplication, making it an essential component of the NetGrimoire homelab. + +--- ## Architecture | Service | Image | Port | Role | -|---------|-----|-----|------| -- **Host:** docker4 -- **Network:** netgrimoire -- **Exposed via:** kopia.netgrimoire.com, Internal only -- **Homepage group:** Backup +|---------|-------|------|------| +| Host | docker4 | | Docker Swarm Worker Node | +| Network | netgrimoire | | Overlay Network for Kopia Services | +| Exposed via | kopia.netgrimoire.com | | Public URL for Caddy Reverse Proxy | +| Homepage group | Backup | | Kopia Service Group in NetGrimoire | --- ## Build & Configuration ### Prerequisites -No specific prerequisites are required for this stack. +- Docker installed and running on the host node. +- Caddy reverse proxy setup with TLS enabled. ### Volume Setup ```bash @@ -36,9 +35,10 @@ chown -R 1964:1964 /DockerVol/kopia/config ### Environment Variables ```bash -KOPIA_PASSWORD=$(openssl rand -hex 32) -PUID=1964 -PGID=1964 +# generate: openssl rand -hex 32 +KOPIA_PASSWORD=F@lcon13 +KOPIA_SERVER_USERNAME=admin +KOPIA_SERVER_PASSWORD=F@lcon13 ``` ### Deploy @@ -52,7 +52,7 @@ docker stack services kopia ``` ### First Run -After deployment, access the kopia web interface at https://kopia.netgrimoire.com and login with username admin and password F@lcon13. +- After initial deployment, run `./deploy.sh` to perform any necessary configuration tasks. --- @@ -61,28 +61,58 @@ After deployment, access the kopia web interface at https://kopia.netgrimoire.co ### Accessing kopia | Service | URL | Purpose | |---------|-----|---------| -- **Host:** kopia.netgrimoire.com, Internal only -- **Purpose:** Access the kopia web interface. +- https://kopia.netgrimoire.com | Kopia Web Interface | ### Primary Use Cases -To use kopia in NetGrimoire, deploy this stack and access its web interface at https://kopia.netgrimoire.com. Configure your backup destinations using the UI. +1. **Backup**: Run regular backups using the Kopia service. +2. **Deduplication**: Utilize deduplicated storage to reduce storage requirements. ### NetGrimoire Integrations -This service connects to Vault for backup storage and Kuma for monitoring. +- Connects to Uptime Kuma for monitoring. +- Exposed via Caddy reverse proxy for secure access. --- ## Operations ### Monitoring -[kuma monitors from kuma.* labels] ```bash docker stack services kopia docker service logs -f kopia ``` ### Backups -The critical volume paths are /DockerVol/kopia/config, /DockerVol/kopia/cache, and /data/nfs/znas/Docker/kopia/logs. +- Store backups in the `/DockerVol/kopia/logs` directory for critical files. +- Reconstructable data will be stored in a separate, non-critical location. ### Restore -To restore a backup, deploy this stack and use the `--restore` option with the kopia command-line interface. \ No newline at end of file +```bash +cd services/swarm/stack/kopia +./deploy.sh +``` + +--- + +## Common Failures +1. **Symptom**: Kopia service fails to start. +2. **Cause**: Insufficient resources or misconfigured environment variables. +3. **Fix**: Check the `env` section and adjust settings as necessary. + +--- + +## Changelog + +| Date | Commit | Summary | +|------|--------|---------| +| 2026-04-30 | 9bc4c652 | Initial kopia stack configuration | +| 2026-04-30 | 9b143d26 | Added Docker Swarm deployment script | +| 2026-04-30 | 63206bb4 | Updated environment variable for KOPIA_PASSWORD | +| 2026-04-30 | ef044b3a | Fixed Kopia TLS setup | +| 2026-04-30 | 2a6755f4 | Corrected Docker Swarm deployment order | + +--- + +## Notes +- Generated by Gremlin on 2026-05-01T00:02:07.612Z +- Source: swarm/kopia.yaml +- Review User Guide and Changelog sections \ No newline at end of file