New Grimoire

Vault-Grimoire/Kopia/Kopia-Service.md

@@ -0,0 +1,113 @@
+# kopia
+
+## Overview
+The kopia stack is a Docker Swarm configuration for the Kopia backup service in NetGrimoire. It provides snapshot backups and deduplication capabilities.
+
+---
+
+## Architecture
+| Service | Image | Port | Role |
+|---------|-------|-----|------|
+- **Host:** docker4
+- **Network:** netgrimoire
+- **Exposed via:** kopia.netgrimoire.com, 51515 (via Caddy reverse proxy)
+- **Homepage group:** Backup
+
+---
+
+## Build & Configuration
+
+### Prerequisites
+None specified.
+
+### Volume Setup
+```bash
+mkdir -p /DockerVol/kopia/config
+mkdir -p /DockerVol/kopia/cache
+mkdir -p /DockerVol/kopia/cert
+```
+
+### Environment Variables
+```bash
+# generate: openssl rand -hex 32 for secrets
+POUID=1964
+PGID=1964
+KOPIA_PASSWORD=F@lcon13
+KOPIA_SERVER_USERNAME=admin
+KOPIA_SERVER_PASSWORD=F@lcon13
+TZ=America/Chicago
+```
+
+### Deploy
+```bash
+cd services/swarm/stack/kopia
+set -a && source .env && set +a
+docker stack config --compose-file kopia-stack.yml > resolved.yml
+docker stack deploy --compose-file resolved.yml kopia
+rm resolved.yml
+docker stack services kopia
+```
+
+### First Run
+After deployment, check the status of the Kopia service and verify that backups are being created.
+
+---
+
+## User Guide
+
+### Accessing kopia
+| Service | URL | Purpose |
+|---------|-----|---------|
+- **kopia**: https://kopia.netgrimoire.com (via Caddy reverse proxy)
+
+### Primary Use Cases
+To use Kopia in NetGrimoire, create a new backup set and configure the service to run as desired.
+
+### NetGrimoire Integrations
+This service integrates with Uptime Kuma for monitoring and other services through environment variables and labels.
+
+---
+
+## Operations
+
+### Monitoring
+```bash
+docker stack services kopia
+docker service logs -f kopia
+```
+
+### Backups
+Critical backups are stored at `/DockerVol/kopia/config` and `/DockerVol/kopia/cache`. Reconstructable backups can be restored from `/DockerVol/kopia/cache`.
+
+### Restore
+To restore a backup, run the following command:
+```bash
+./deploy.sh
+```
+
+---
+
+## Common Failures
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Backups not being created | Insufficient storage or network issues | Check storage and network conditions. |
+| Service not starting | Incorrect environment variables or Docker configuration | Review `.env` file and `docker-compose.yml`. |
+
+---
+
+## Changelog
+
+| Date | Commit | Summary |
+|------|--------|---------|
+| 2026-04-07 | d3206f11 | Initial documentation for kopia stack. |
+| 2026-02-11 | aa13ac64 | Minor adjustments to environment variables and volume setup. |
+| 2026-01-30 | 15f5f655 | Initial commit with basic configuration and service setup. |
+
+<No changelog entries available from diffs above>
+
+---
+
+## Notes
+- Generated by Gremlin on 2026-04-07T19:20:00.179Z
+- Source: swarm/kopia.yaml
+- Review User Guide and Changelog sections