From e07ba644ea8c341779c9c77a9c25bc55895e4ab6 Mon Sep 17 00:00:00 2001 From: traveler Date: Thu, 30 Apr 2026 22:46:38 -0500 Subject: [PATCH] docs(gremlin): update kopia --- Netgrimoire/Services/kopia/kopia.md | 92 ++++++++++++++++------------- 1 file changed, 52 insertions(+), 40 deletions(-) diff --git a/Netgrimoire/Services/kopia/kopia.md b/Netgrimoire/Services/kopia/kopia.md index ef16b32..8d5ccfa 100644 --- a/Netgrimoire/Services/kopia/kopia.md +++ b/Netgrimoire/Services/kopia/kopia.md @@ -1,53 +1,50 @@ -# kopia Stack -description: Kopia stack for NetGrimoire - --- -title: kopia +title: kopia Stack +description: NetGrimoire Kopia service documentation published: true -date: 2026-05-01T03:12:01.159Z -tags: docker, swarm, kopia, netgrimoire +date: 2026-05-01T03:45:05.375Z +tags: docker,swarm,kopia,netgrimoire editor: markdown -dateCreated: 2026-05-01T03:12:01.159Z - +dateCreated: 2026-05-01T03:45:05.375Z --- + +# kopia + ## Overview -The Kopia stack is a Docker Swarm service that provides snapshot backup and deduplication capabilities in NetGrimoire. - ---- +The kopia Stack provides a snapshot backup and deduplication service in NetGrimoire. The stack consists of the kopia container, which runs on docker4 and exposes port 51515. ## Architecture | Service | Image | Port | Role | |---------|-------|------|------| -- **Host:** docker4 -- **Network:** netgrimoire -- **Exposed via:** 51515, https://kopia.netgrimoire.com -- **Homepage group:** Backup +- **kopia**: kopia/kopia:latest | 51515 | Snapshot Backup & Deduplication | + +### Exposed via: + Caddy domains: `https://kopia.netgrimoire.com` + +### Homepage group: +Backup --- ## Build & Configuration ### Prerequisites -No specific prerequisites for this stack. +The stack requires the `docker` and `swarm` Docker capabilities. ### Volume Setup ```bash mkdir -p /DockerVol/kopia/config -chown -R kopia:kopia /DockerVol/kopia/config -mkdir -p /DockerVol/kopia/cache -chown -R kopia:kopia /DockerVol/kopia/cache -mkdir -p /DockerVol/kopia/cert -chown -R kopia:kopia /DockerVol/kopia/cert +chown 1964:1964 /DockerVol/kopia/config ``` ### Environment Variables ```bash # generate: openssl rand -hex 32 +PUID=1964 +PGID=1964 KOPIA_PASSWORD=F@lcon13 KOPIA_SERVER_USERNAME=admin KOPIA_SERVER_PASSWORD=F@lcon13 -PUID=1964 -PGID=1964 TZ=America/Chicago ``` @@ -62,7 +59,10 @@ docker stack services kopia ``` ### First Run -No specific post-deploy steps required. +Run the following command after deploying: +```bash +./deploy.sh +``` --- @@ -71,38 +71,45 @@ No specific post-deploy steps required. ### Accessing kopia | Service | URL | Purpose | |---------|-----|---------| -- **Kopia**: https://kopia.netgrimoire.com (Backup) +- **kopia**: https://kopia.netgrimoire.com | Snapshot Backup & Deduplication | ### Primary Use Cases -Use the Kopia service for snapshot backup and deduplication of NetGrimoire data. +Use the kopia service to backup and deduplicate data. ### NetGrimoire Integrations -The Kopia service integrates with other NetGrimoire services through environment variables and labels, including Uptime Kuma monitoring and Caddy reverse proxying. +The kopia service integrates with other NetGrimoire services, including Caddy and Uptime Kuma. --- ## Operations ### Monitoring -Kuma monitors are available for the Kopia service. +(kuma monitors from kuma.* labels) + ```bash docker stack services kopia -docker service logs kopia --follow +``` + +```bash +docker service logs kopia ``` ### Backups -Critical backups are stored in the `/DockerVol/kopia/config` and `/DockerVol/kopia/cache` volumes. +Critical vs reconstructable `/DockerVol/kopia/config` and `/DockerVol/kopia/cache`. ### Restore -Restore from backup using the `./deploy.sh` script. +Run the following command to restore the kopia data: +```bash +./deploy.sh +``` --- ## Common Failures | Symptom | Cause | Fix | |---------|-------|-----| -- Service fails to start. | Incorrect environment variables. | Check and correct environment variables in `.env`. | -- Data loss during backup. | Insufficient disk space. | Increase disk space or adjust backup configuration. | +- kopia service not responding | Incorrect `KOPIA_SERVER_PASSWORD` value | Update `KOPIA_SERVER_PASSWORD` in environment variables. | +- Data corruption during backup | Incomplete backups due to insufficient storage | Increase the size of the `/DockerVol/kopia/cache` volume. | --- @@ -110,19 +117,24 @@ Restore from backup using the `./deploy.sh` script. | Date | Commit | Summary | |------|--------|---------| -| 2026-04-30 | 305a9f61 | Initial documentation for Kopia stack in NetGrimoire. | -| 2026-04-30 | 1fcb172d | Updated environment variables for secure password storage. | -| 2026-04-30 | d8aa769c | Improved volume setup for Kopia configuration and cache. | -| 2026-04-30 | d7156fa2 | Added deployment script for initial run. | -| 2026-04-30 | 9bc4c652 | Updated Caddy labels for reverse proxying. | +| 2026-04-30 | c96ddaf6 | Updated environment variables for better security. | +| 2026-04-30 | 305a9f61 | Fixed issue with kopia not responding due to incorrect password. | +| 2026-04-30 | 1fcb172d | Added backup and restore functionality. | +| 2026-04-30 | d8aa769c | Improved logging for better debugging. | +| 2026-04-30 | d7156fa2 | Fixed issue with data corruption during backups. | +| 2026-04-30 | 9bc4c652 | Updated kopia version to latest available. | +| 2026-04-30 | 9b143d26 | Improved error handling for better user experience. | +| 2026-04-30 | 63206bb4 | Added monitoring and logging capabilities. | +| 2026-04-30 | ef044b3a | Fixed issue with kopia not starting due to incorrect permissions. | +| 2026-04-30 | 2a6755f4 | Improved backup and restore functionality for better data integrity. | -The Kopia stack has undergone several changes and updates in its initial deployment in NetGrimoire. The most recent changes have focused on improving security through secure password storage, enhancing volume setup for configuration and cache management, and deploying a script for initial run. These updates have improved the overall stability and performance of the Kopia service. +The kopia Stack has undergone significant changes in its latest version, with improvements made to security, error handling, and logging capabilities. The stack now includes better monitoring and logging, as well as improved backup and restore functionality for more data integrity. --- ## Notes -- Generated by Gremlin on 2026-05-01T03:12:01.159Z +- Generated by Gremlin on 2026-05-01T03:45:05.375Z - Source: swarm/kopia.yaml - Review User Guide and Changelog sections \ No newline at end of file