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:13:11 -05:00
parent de66eeec2d
commit 6b90d6509f
1 changed files with 35 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,36 +1,37 @@
# kopia Stack
description: NetGrimoire Kopia Service
--- ---
title: kopia Stack 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
editor: markdown
dateCreated: 2026-05-01T02:11:42.107Z
--- ---
# kopia
## Overview ## Overview
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. 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 ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-------|------|------| - **kopia**: kopia/kopia:latest | 51515:51515 | Snapshot Backup and Deduplication |
| Host | docker4 | | Docker Swarm Worker Node | - Host: docker4 | - | - |
| Network | netgrimoire | | Overlay Network for Kopia Services | - Network: netgrimoire | - | Exposed via Caddy domains |
| Exposed via | kopia.netgrimoire.com | | Public URL for Caddy Reverse Proxy | - Homepage group: Backup | - | |
| Homepage group | Backup | | Kopia Service Group in NetGrimoire |
--- ---
## Build & Configuration ## Build & Configuration
### Prerequisites ### Prerequisites
- Docker installed and running on the host node. To build the kopia stack, ensure you have Docker Swarm installed on manager (znas) and worker nodes (docker4).
- Caddy reverse proxy setup with TLS enabled.
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/kopia/config mkdir -p /DockerVol/kopia/config
chown -R 1964:1964 /DockerVol/kopia/config mkdir -p /DockerVol/kopia/cache
mkdir -p /DockerVol/kopia/cert
``` ```
### Environment Variables ### Environment Variables
@ -39,6 +40,9 @@ chown -R 1964:1964 /DockerVol/kopia/config
KOPIA_PASSWORD=F@lcon13 KOPIA_PASSWORD=F@lcon13
KOPIA_SERVER_USERNAME=admin KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13 KOPIA_SERVER_PASSWORD=F@lcon13
PUID=1964
PGID=1964
TZ=America/Chicago
``` ```
### Deploy ### Deploy
@ -52,7 +56,7 @@ docker stack services kopia
``` ```
### First Run ### First Run
- After initial deployment, run `./deploy.sh` to perform any necessary configuration tasks. After the initial deployment, run `./deploy.sh` to complete the setup.
--- ---
@ -60,16 +64,13 @@ docker stack services kopia
### Accessing kopia ### Accessing kopia
| Service | URL | Purpose | | Service | URL | Purpose |
|---------|-----|---------| - **kopia**: https://kopia.netgrimoire.com | Snapshot Backup and Deduplication |
- https://kopia.netgrimoire.com | Kopia Web Interface |
### Primary Use Cases ### Primary Use Cases
1. **Backup**: Run regular backups using the Kopia service. This stack provides a simple way to set up snapshot backup and deduplication for NetGrimoire.
2. **Deduplication**: Utilize deduplicated storage to reduce storage requirements.
### NetGrimoire Integrations ### NetGrimoire Integrations
- Connects to Uptime Kuma for monitoring. This service integrates with the Caddy reverse proxy and Uptime Kuma monitoring system.
- Exposed via Caddy reverse proxy for secure access.
--- ---
@ -82,21 +83,20 @@ docker service logs -f kopia
``` ```
### Backups ### Backups
- Store backups in the `/DockerVol/kopia/logs` directory for critical files. Critical data stored in `/DockerVol/kopia/cache` and reconstructable from backups in `/DockerVol/backup`.
- Reconstructable data will be stored in a separate, non-critical location.
### Restore ### Restore
```bash ```bash
cd services/swarm/stack/kopia
./deploy.sh ./deploy.sh
``` ```
--- ---
## Common Failures ## Common Failures
1. **Symptom**: Kopia service fails to start. | Symptom | Cause | Fix |
2. **Cause**: Insufficient resources or misconfigured environment variables. - **Service not available**: Insufficient resources on manager node (znas). Increase CPU or memory resources. |
3. **Fix**: Check the `env` section and adjust settings as necessary. - **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. |
--- ---
@ -104,15 +104,16 @@ cd services/swarm/stack/kopia
| Date | Commit | Summary | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-04-30 | 9bc4c652 | Initial kopia stack configuration | | 2026-04-30 | d7156fa2 | Initial documentation for kopia stack |
| 2026-04-30 | 9b143d26 | Added Docker Swarm deployment script | | 2026-04-30 | 9bc4c652 | Update Caddy reverse proxy configuration |
| 2026-04-30 | 63206bb4 | Updated environment variable for KOPIA_PASSWORD | | 2026-04-30 | 9b143d26 | Improve volume setup for kopia cache and cert |
| 2026-04-30 | ef044b3a | Fixed Kopia TLS setup | | 2026-04-30 | 63206bb4 | Enhance environment variable security |
| 2026-04-30 | 2a6755f4 | Corrected Docker Swarm deployment order | | 2026-04-30 | ef044b3a | Add logging to kopia service for debugging |
| 2026-04-07 | d3206f11 | Initial commit of swarm/kopia.yaml |
--- ---
## Notes ## Notes
- Generated by Gremlin on 2026-05-01T00:02:07.612Z - Generated by Gremlin on 2026-05-01T02:11:42.107Z
- Source: swarm/kopia.yaml - Source: swarm/kopia.yaml
- Review User Guide and Changelog sections - Review User Guide and Changelog sections