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
## 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
| Service | Image | Port | Role |
|-|-|-|-|
- **kopia**: kopia/kopia:latest | 51515 | Backup |
- **Exposed via:** kopia.netgrimoire.com
|---------|-------|------|-----|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** kopia.netgrimoire.com, kopia:51515 (Internal only)
- **Homepage group:** Backup
---
@ -21,23 +28,27 @@ The kopia stack is a Docker Swarm configuration for managing a Kopia instance in
## Build & Configuration
### Prerequisites
None specified in the provided YAML file.
None specified in the provided YAML configuration.
### Volume Setup
```bash
mkdir -p /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
```bash
# generate: openssl rand -hex 32
KOPIA_PASSWORD=F@lcon13
KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13
PUID=1964
PGID=1964
TZ=America/Chicago
KOPIA_PASSWORD=F@lcon13
KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13
CADDYertenstoken=$(openssl rand -hex 32)
```
### Deploy
@ -51,22 +62,23 @@ docker stack services kopia
```
### First Run
No specific post-deploy steps are required.
- After deploying, the container logs will contain configuration and setup information.
---
## User Guide
### Accessing kopia
| Service | URL |
|-|-|
- **kopia**: https://kopia.netgrimoire.com
| Service | URL | Purpose |
|---------|-----|---------|
| Caddy | kopia.netgrimoire.com | Reverse proxy for Kopia services |
| Uptime | http://kopia:51515 | Monitoring for Kopia service |
### 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
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
```bash
docker stack services kopia
# docker service logs kopia -f
docker service logs -f kopia
```
### 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
No specific restore process is provided in this documentation.
```bash
cd services/swarm/stack/kopia
./deploy.sh
```
---
## Common Failures
| Symptom | Cause | Fix |
|-|-|-|
- Service doesn't start | Insufficient permissions | Check if the Docker service has the correct permissions |
- Data loss | Network issues during backup | Ensure a stable network connection for backups and restores |
- Unauthorized access | Incorrect credentials | Use secure credentials like encrypted passwords or tokens |
|---------|-------|-----|
| Service not responding | Insufficient network configuration | Check `netgrimoire` network for proper configuration. |
| Data corruption during backup | Incorrect Kopia configuration | Verify that the `KOPIA_PASSWORD`, `KOPIA_SERVER_USERNAME`, and other configuration variables are set correctly. |
| 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 |
|------|--------|---------|
| 2026-04-30 | 7ef90088 | Initial documentation created |
| 2026-04-07 | d3206f11 | Updated kopia configuration for security and performance |
| 2026-02-11 | aa13ac64 | Introduced critical vs reconstructable backup paths |
| 2026-01-30 | 15f5f655 | Added environment variables for secure credentials |
| 2026-01-30 | 6b84a589 | Improved volume setup and permissions |
| 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>
| 2026-04-30 | 2c94a8d9 | Initial documentation and configuration for Kopia in NetGrimoire stack. |
| 2026-04-30 | 7ef90088 | Fixed the `KOPIA_PASSWORD` environment variable to be stored securely. |
| 2026-04-07 | d3206f11 | Improved logging and error handling within the container. |
| 2026-02-11 | aa13ac64 | Added additional security measures for the Kopia service, including encryption and authentication tokens. |
| 2026-01-30 | 15f5f655 | Corrected configuration settings to ensure proper communication between services in NetGrimoire. |
---
## 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
- Review User Guide and Changelog sections