---
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 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 |
|---------|-------|------|-----|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** kopia.netgrimoire.com, kopia:51515 (Internal only)
- **Homepage group:** Backup

---

## Build & Configuration

### Prerequisites
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
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
```bash
cd services/swarm/stack/kopia
set -a && source .env && set +a
docker stack config --compose-file kopia-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml kopia
rm resolved.yml
docker stack services kopia
```

### First Run
- After deploying, the container logs will contain configuration and setup information.

---

## User Guide

### Accessing kopia
| Service | URL | Purpose |
|---------|-----|---------|
| Caddy    | kopia.netgrimoire.com | Reverse proxy for Kopia services |
| Uptime   | http://kopia:51515 | Monitoring for Kopia service |

### Primary Use Cases
- Regularly backing up and restoring data from NetGrimoire.

### NetGrimoire Integrations
- This service connects to the `znas` node in NetGrimoire, using its hostname for communication.

---

## Operations

### Monitoring
```bash
docker stack services kopia
docker service logs -f kopia
```

### Backups
Critical data is stored in `/DockerVol/kopia/cache/`, and reconstructable backups are stored in `/DockerVol/kopia/config/`.

### Restore
```bash
cd services/swarm/stack/kopia
./deploy.sh
```

---

## Common Failures
| Symptom | Cause | Fix |
|---------|-------|-----|
| 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. |

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 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:31.075Z
- Source: swarm/kopia.yaml
- Review User Guide and Changelog sections