---
title: vault Stack
description: Kopia Vault Services in NetGrimoire
published: true
date: 2026-05-01T13:09:07.428Z
tags: docker,swarm,vault,netgrimoire
editor: markdown
dateCreated: 2026-05-01T13:09:07.428Z
---

# vault

## Overview
The `vault` stack in NetGrimoire provides a secure Kopia Vault service for snapshot backup and deduplication. This stack consists of the `vault` Docker service, which is configured to run on `znas`.

## Architecture
| Service | Image | Port | Role |
|---------|-------|------|------|
| Host    | docker4    |        | NetGrimoire Node |
| Network  | netgrimoire |        | Internal |

Exposed via: <https://kopia-vault.192.168.5.10>, `tcp://kopia:51516`

Homepage group: Backup

## Build & Configuration
### Prerequisites
You need Docker installed on your system to use this stack.

### Volume Setup
```bash
mkdir -p /DockerVol/vault/config
mkdir -p /DockerVol/vault/cache
mkdir -p /DockerVol/vault/cert
```

### Environment Variables
```bash
# generate: openssl rand -hex 32
PUID=1964
PGID=1964
TZ=America/Chicago
KOPIA_PASSWORD=F@lcon13
KOPIA_SERVER_USERNAME=admin
KOPIA_SERVER_PASSWORD=F@lcon13
```

### Deploy
```bash
cd services/swarm/stack/vault
set -a && source .env && set +a
docker stack config --compose-file vault-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml vault
rm resolved.yml
docker stack services vault
```

### First Run
Run `./deploy.sh` after initial deployment for the first time.

## User Guide

### Accessing vault
| Service | URL | Purpose |
|---------|-----|---------|
- **Host:** <https://kopia-vault.192.168.5.10>
- **Internal only:** <http://kopia:51516>

### Primary Use Cases
This stack provides a secure Kopia Vault service for snapshot backup and deduplication.

### NetGrimoire Integrations
This stack connects to other services via the `netgrimoire` network, using environment variables like `KOPIA_SERVER_USERNAME` and `KOPIA_SERVER_PASSWORD`.

---

## Operations

### Monitoring
| Monitor Name | Monitor URL |
|-|-|
- **Kuma**: <http://kopia:51516>

### Backups
Critical data is stored in `/DockerVol/vault/cache`. All data can be reconstructed from backups stored in `/DockerVol/vault/backup/repository`.

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

---

## Common Failures
| Failure | Symptom | Cause | Fix |
|-|-|-|-|
- **No connection to Kopia Vault** | No response from vault service. | The vault service is not running. | `docker stack services vault` and inspect logs for issues.
- **Kopia server credentials missing**: Error accessing vault due to invalid credentials.  | The Kopia server username or password is incorrect or absent in the environment variables. | Double check that `KOPIA_SERVER_USERNAME` and `KOPIA_SERVER_PASSWORD` are set correctly.

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-30 | 6f7c6f87 | <infer what changed from the diffs above> |
| 2026-04-30 | 72833207 | <infer what changed from the diffs above> |
| 2026-02-22 | 573a7d8f | <infer what changed from the diffs above> |
| 2026-02-13 | 7b2ad934 | <infer what changed from the diffs above> |
| 2026-02-13 | 9209aa98 | <infer what changed from the diffs above> |

This is the initial documentation for the `vault` stack in NetGrimoire.

---

## Notes
- Generated by Gremlin on 2026-05-01T13:09:07.428Z
- Source: swarm/vault.yaml
- Review User Guide and Changelog sections