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
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
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
| Service | Image | Port | Role |
|---------|-------|------|------|
| 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 |
- **kopia**: kopia/kopia:latest | 51515:51515 | Snapshot Backup and Deduplication |
- Host: docker4 | - | - |
- Network: netgrimoire | - | Exposed via Caddy domains |
- Homepage group: Backup | - | |
---
## Build & Configuration
### Prerequisites
- Docker installed and running on the host node.
- Caddy reverse proxy setup with TLS enabled.
To build the kopia stack, ensure you have Docker Swarm installed on manager (znas) and worker nodes (docker4).
### Volume Setup
```bash
mkdir -p /DockerVol/kopia/config
chown -R 1964:1964 /DockerVol/kopia/config
mkdir -p /DockerVol/kopia/cache
mkdir -p /DockerVol/kopia/cert
```
### Environment Variables
@ -39,6 +40,9 @@ chown -R 1964:1964 /DockerVol/kopia/config
KOPIA_PASSWORD=F@lcon13
KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13
PUID=1964
PGID=1964
TZ=America/Chicago
```
### Deploy
@ -52,7 +56,7 @@ docker stack services kopia
```
### 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
| Service | URL | Purpose |
|---------|-----|---------|
- https://kopia.netgrimoire.com | Kopia Web Interface |
- **kopia**: https://kopia.netgrimoire.com | Snapshot Backup and Deduplication |
### Primary Use Cases
1. **Backup**: Run regular backups using the Kopia service.
2. **Deduplication**: Utilize deduplicated storage to reduce storage requirements.
This stack provides a simple way to set up snapshot backup and deduplication for NetGrimoire.
### NetGrimoire Integrations
- Connects to Uptime Kuma for monitoring.
- Exposed via Caddy reverse proxy for secure access.
This service integrates with the Caddy reverse proxy and Uptime Kuma monitoring system.
---
@ -82,21 +83,20 @@ docker service logs -f kopia
```
### Backups
- Store backups in the `/DockerVol/kopia/logs` directory for critical files.
- Reconstructable data will be stored in a separate, non-critical location.
Critical data stored in `/DockerVol/kopia/cache` and reconstructable from backups in `/DockerVol/backup`.
### Restore
```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.
| 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. |
---
@ -104,15 +104,16 @@ cd services/swarm/stack/kopia
| 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 |
| 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 |
---
## 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
- Review User Guide and Changelog sections