# actualbudget

## Overview
The actualbudget Stack provides a Docker Swarm-based service for envelope budgeting in NetGrimoire, utilizing the Actual Budget server as its primary application. This stack also integrates with CrowdSec and Authentik through Caddy reverse proxy.

---

## Architecture
| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** budget.netgrimoire.com, actual:5006
- **Homepage group:** PNCHarris Apps

---

## Build & Configuration

### Prerequisites
Ensure you have Docker installed and running on your swarm nodes.

### Volume Setup
```bash
mkdir -p /DockerVol/actual
chown $PUID:$PGID /DockerVol/actual
```

### Environment Variables
```bash
# generate: openssl rand -hex 32
PUID=1964
PGID=1964
ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB=20
ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB=50
ACTUAL_UPLOAD_FILE_SIZE_LIMIT_MB=20
```

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

### First Run
On the first deployment, please wait for the Caddy reverse proxy to stabilize.

---

## User Guide

### Accessing actualbudget
| Service | URL | Purpose |
|---------|-----|---------|
- Actual Budget: https://budget.netgrimoire.com

### Primary Use Cases
To use this service in NetGrimoire, you would access it through the Caddy reverse proxy. Configure your wallet to use this service for budgeting.

### NetGrimoire Integrations
This stack connects with other services such as CrowdSec and Authentik via Caddy's import functionality.

---

## Operations

### Monitoring
```bash
docker stack services actualbudget
<docker service logs commands>
```

### Backups
Critical data is stored within the Docker Volume at /DockerVol/actual. Regular backups of this volume are essential for data recovery.

### Restore
Restore the stack by running `./deploy.sh` in the actualbudget directory.

---

## Common Failures
1. **Service not responding**: Ensure Caddy is configured correctly and running on the correct node.
2. **Volume permissions issue**: Verify that your $PUID:$PGID have proper write access to /DockerVol/actual.
3. **Service not deployed**: Check for any errors during the deployment process.

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-29 | b23a05d6 | Initial documentation creation based on swarm/actualbudget.yaml. |
| 2026-04-29 | 30e2edae | Minor adjustments to formatting and layout for better readability. |
| 2026-04-29 | d5f26841 | Adjustments made for the first production deployment. |
| 2026-04-29 | a91a2ded | Error handling improvements during the deploy process. |
| 2026-04-11 | 4e7cb8f9 | Initial version based on existing swarm configuration files. |

<Write a paragraph summarizing the evolution of this service based on the diffs above.>
This stack underwent significant changes as part of its initial deployment. Minor adjustments were made to improve readability, and major updates ensured that all configurations are compatible with the current Docker Swarm setup.

---

## Notes
- Generated by Gremlin on 2026-04-29T18:56:30.378Z
- Source: swarm/actualbudget.yaml
- Review User Guide and Changelog sections