traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gremlin): update kopia

Browse source
This commit is contained in:
traveler 2026-04-30 21:18:16 -05:00
parent 6b90d6509f
commit 277c4ea712
1 changed files with 45 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

88
Netgrimoire/Services/kopia/kopia.md
View file

@ -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
Generated by Gremlin on 2026-05-01T02:16:54.257Z
Source: swarm/kopia.yaml
Review User Guide and Changelog sections