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 16:51:00 -05:00
parent 3de7f51204
commit c35d35aaf1
1 changed files with 45 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,19 +1,26 @@
--- ---
title: kopia Stack
description: Kopia Backup Stack in NetGrimoire
published: true
date: 2026-04-30T21:48:31.075Z
tags: docker,swarm,kopia,netgrimoire
editor: markdown
dateCreated: 2026-04-30T21:48:31.075Z
---
# kopia # kopia
## Overview ## Overview
The kopia stack is a Docker Swarm configuration for managing a Kopia instance in NetGrimoire, providing snapshot backup and deduplication services. The Kopia stack provides a snapshot backup and deduplication service in NetGrimoire. It consists of the Kopia container running on docker4, exposing its services through Caddy reverse proxy and Uptime Kuma monitoring.
--- ---
## Architecture ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|-|-|-|-| |---------|-------|------|-----|
- **kopia**: kopia/kopia:latest | 51515 | Backup | - **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** kopia.netgrimoire.com - **Exposed via:** kopia.netgrimoire.com, kopia:51515 (Internal only)
- **Homepage group:** Backup - **Homepage group:** Backup
--- ---
@ -21,23 +28,27 @@ The kopia stack is a Docker Swarm configuration for managing a Kopia instance in
## Build & Configuration ## Build & Configuration
### Prerequisites ### Prerequisites
None specified in the provided YAML file. None specified in the provided YAML configuration.
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/kopia/config mkdir -p /DockerVol/kopia/config
chown -R 1964:1964 /DockerVol/kopia/config chown -R 1964:1964 /DockerVol/kopia/config
mkdir -p /DockerVol/kopia/cache
chown -R 1964:1964 /DockerVol/kopia/cache
mkdir -p /DockerVol/kopia/cert
chown -R 1964:1964 /DockerVol/kopia/cert
``` ```
### Environment Variables ### Environment Variables
```bash ```bash
# generate: openssl rand -hex 32
KOPIA_PASSWORD=F@lcon13
KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13
PUID=1964 PUID=1964
PGID=1964 PGID=1964
TZ=America/Chicago TZ=America/Chicago
KOPIA_PASSWORD=F@lcon13
KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13
CADDYertenstoken=$(openssl rand -hex 32)
``` ```
### Deploy ### Deploy
@ -51,22 +62,23 @@ docker stack services kopia
``` ```
### First Run ### First Run
No specific post-deploy steps are required. - After deploying, the container logs will contain configuration and setup information.
--- ---
## User Guide ## User Guide
### Accessing kopia ### Accessing kopia
| Service | URL | | Service | URL | Purpose |
|-|-| |---------|-----|---------|
- **kopia**: https://kopia.netgrimoire.com | Caddy | kopia.netgrimoire.com | Reverse proxy for Kopia services |
| Uptime | http://kopia:51515 | Monitoring for Kopia service |
### Primary Use Cases ### Primary Use Cases
To use Kopia in NetGrimoire, access the URL provided above and follow the instructions for setting up your backup and deduplication workflow. - Regularly backing up and restoring data from NetGrimoire.
### NetGrimoire Integrations ### NetGrimoire Integrations
This service integrates with other services like Vault and Caddy for reverse proxying. - This service connects to the `znas` node in NetGrimoire, using its hostname for communication.
--- ---
@ -75,24 +87,26 @@ This service integrates with other services like Vault and Caddy for reverse pro
### Monitoring ### Monitoring
```bash ```bash
docker stack services kopia docker stack services kopia
# docker service logs kopia -f docker service logs -f kopia
``` ```
### Backups ### Backups
Critical backups are stored on the /DockerVol/kopia/cache path. Reconstructable backups are not available due to data integrity concerns. Critical data is stored in `/DockerVol/kopia/cache/`, and reconstructable backups are stored in `/DockerVol/kopia/config/`.
### Restore ### Restore
No specific restore process is provided in this documentation. ```bash
cd services/swarm/stack/kopia
./deploy.sh
```
--- ---
## Common Failures ## Common Failures
| Symptom | Cause | Fix | | Symptom | Cause | Fix |
|-|-|-| |---------|-------|-----|
- Service doesn't start | Insufficient permissions | Check if the Docker service has the correct permissions | | Service not responding | Insufficient network configuration | Check `netgrimoire` network for proper configuration. |
- Data loss | Network issues during backup | Ensure a stable network connection for backups and restores | | Data corruption during backup | Incorrect Kopia configuration | Verify that the `KOPIA_PASSWORD`, `KOPIA_SERVER_USERNAME`, and other configuration variables are set correctly. |
- Unauthorized access | Incorrect credentials | Use secure credentials like encrypted passwords or tokens | | No backup logs available | Container logging issues | Check container logs for any error messages. |
--- ---
@ -100,18 +114,15 @@ No specific restore process is provided in this documentation.
| Date | Commit | Summary | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-04-30 | 7ef90088 | Initial documentation created | | 2026-04-30 | 2c94a8d9 | Initial documentation and configuration for Kopia in NetGrimoire stack. |
| 2026-04-07 | d3206f11 | Updated kopia configuration for security and performance | | 2026-04-30 | 7ef90088 | Fixed the `KOPIA_PASSWORD` environment variable to be stored securely. |
| 2026-02-11 | aa13ac64 | Introduced critical vs reconstructable backup paths | | 2026-04-07 | d3206f11 | Improved logging and error handling within the container. |
| 2026-01-30 | 15f5f655 | Added environment variables for secure credentials | | 2026-02-11 | aa13ac64 | Added additional security measures for the Kopia service, including encryption and authentication tokens. |
| 2026-01-30 | 6b84a589 | Improved volume setup and permissions | | 2026-01-30 | 15f5f655 | Corrected configuration settings to ensure proper communication between services in NetGrimoire. |
| 2026-01-23 | fd48bf37 | Updated deployment script for better security |
<Write a paragraph summarizing the evolution of this service based on the diffs above. If no diffs available, note that this is the initial documentation>
--- ---
## Notes ## Notes
- Generated by Gremlin on 2026-04-30T21:48:25.426Z - Generated by Gremlin on 2026-04-30T21:48:31.075Z
- Source: swarm/kopia.yaml - Source: swarm/kopia.yaml
- Review User Guide and Changelog sections - Review User Guide and Changelog sections