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 19:03:25 -05:00
parent fccc7902ed
commit de66eeec2d
1 changed files with 56 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,32 +1,31 @@
# kopia Stack
description: NetGrimoire Kopia Service
--- ---
title: kopia Stack title: kopia Stack
description: Snapshot backup and deduplication service in NetGrimoire.
published: true
date: 2026-04-30T23:46:07.706Z
tags: docker,swarm,kopia,netgrimoire
editor: markdown
dateCreated: 2026-04-30T23:46:07.706Z
--- ---
# kopia
## Overview ## Overview
The kopia stack is a Docker Swarm service that provides snapshot backup and deduplication capabilities in NetGrimoire. It includes the kopia container, which runs as the root user with a password set by the environment variable KOPIA_PASSWORD. 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.
---
## Architecture ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-----|-----|------| |---------|-------|------|------|
- **Host:** docker4 | Host | docker4 | | Docker Swarm Worker Node |
- **Network:** netgrimoire | Network | netgrimoire | | Overlay Network for Kopia Services |
- **Exposed via:** kopia.netgrimoire.com, Internal only | 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
No specific prerequisites are required for this stack. - Docker installed and running on the host node.
- Caddy reverse proxy setup with TLS enabled.
### Volume Setup ### Volume Setup
```bash ```bash
@ -36,9 +35,10 @@ chown -R 1964:1964 /DockerVol/kopia/config
### Environment Variables ### Environment Variables
```bash ```bash
KOPIA_PASSWORD=$(openssl rand -hex 32) # generate: openssl rand -hex 32
PUID=1964 KOPIA_PASSWORD=F@lcon13
PGID=1964 KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13
``` ```
### Deploy ### Deploy
@ -52,7 +52,7 @@ docker stack services kopia
``` ```
### First Run ### First Run
After deployment, access the kopia web interface at https://kopia.netgrimoire.com and login with username admin and password F@lcon13. - After initial deployment, run `./deploy.sh` to perform any necessary configuration tasks.
--- ---
@ -61,28 +61,58 @@ After deployment, access the kopia web interface at https://kopia.netgrimoire.co
### Accessing kopia ### Accessing kopia
| Service | URL | Purpose | | Service | URL | Purpose |
|---------|-----|---------| |---------|-----|---------|
- **Host:** kopia.netgrimoire.com, Internal only - https://kopia.netgrimoire.com | Kopia Web Interface |
- **Purpose:** Access the kopia web interface.
### Primary Use Cases ### Primary Use Cases
To use kopia in NetGrimoire, deploy this stack and access its web interface at https://kopia.netgrimoire.com. Configure your backup destinations using the UI. 1. **Backup**: Run regular backups using the Kopia service.
2. **Deduplication**: Utilize deduplicated storage to reduce storage requirements.
### NetGrimoire Integrations ### NetGrimoire Integrations
This service connects to Vault for backup storage and Kuma for monitoring. - Connects to Uptime Kuma for monitoring.
- Exposed via Caddy reverse proxy for secure access.
--- ---
## Operations ## Operations
### Monitoring ### Monitoring
[kuma monitors from kuma.* labels]
```bash ```bash
docker stack services kopia docker stack services kopia
docker service logs -f kopia docker service logs -f kopia
``` ```
### Backups ### Backups
The critical volume paths are /DockerVol/kopia/config, /DockerVol/kopia/cache, and /data/nfs/znas/Docker/kopia/logs. - Store backups in the `/DockerVol/kopia/logs` directory for critical files.
- Reconstructable data will be stored in a separate, non-critical location.
### Restore ### Restore
To restore a backup, deploy this stack and use the `--restore` option with the kopia command-line interface. ```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.
---
## Changelog
| 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 |
---
## Notes
- Generated by Gremlin on 2026-05-01T00:02:07.612Z
- Source: swarm/kopia.yaml
- Review User Guide and Changelog sections