docs(gremlin): create actualbudget

Netgrimoire/Services/actualbudget/actualbudget.md

@@ -0,0 +1,114 @@
+---
+title: actualbudget Stack
+description: NetGrimoire budgeting service
+published: true
+date: 2026-04-29T18:20:54.861Z
+tags: docker,swarm,actualbudget,netgrimoire
+editor: markdown
+dateCreated: 2026-04-29T18:20:54.861Z
+---
+
+# actualbudget
+
+## Overview
+The `actualbudget` stack is a NetGrimoire service responsible for managing budgeting data and uploading it to the cloud. It consists of two services: `actual-server` and `diun`. The `actual-server` service handles user input and uploads, while `diun` provides disaster recovery capabilities.
+
+## Architecture
+| Service | Image | Port | Role |
+|---------|-------|------|-----|
+- **Host:** docker4
+- **Network:** netgrimoire
+- **Exposed via:** budget.netgrimoire.com:5006
+- **Homepage group:** PNCHarris Apps
+
+---
+
+## Build & Configuration
+
+### Prerequisites
+This stack requires Docker Swarm, Caddy reverse proxy, Uptime Kuma monitoring, and a Caddy configuration file (`swarm/actualbudget.yaml`).
+
+### Volume Setup
+```bash
+mkdir -p /DockerVol/actual
+chown $USER:$USER /DockerVol/actual
+```
+
+### Environment Variables
+```bash
+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
+
+# generate: openssl rand -hex 32 for secrets like ACTUAL_API_KEY
+```
+
+### 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
+After deploying, the `diun` service needs to be updated with the new IP address.
+
+---
+
+## User Guide
+
+### Accessing actualbudget
+| Service | URL | Purpose |
+|---------|-----|---------|
+- **Actual Server:** https://budget.netgrimoire.com/actual
+- **DIUN (Disaster Recovery):** https://budget.netgrimoire.com/diun
+
+### Primary Use Cases
+Use the `actual` service to upload budgeting data and use the `diun` service as a backup.
+
+### NetGrimoire Integrations
+This stack integrates with other services like Uptime Kuma monitoring and Caddy reverse proxy.
+
+---
+
+## Operations
+
+### Monitoring
+```bash
+docker stack services actualbudget
+docker stack logs -f actualbudget
+```
+
+### Backups
+Use the `diun` service to backup budgeting data. The `/DockerVol/actual` volume needs to be backed up regularly.
+
+### Restore
+```bash
+cd services/swarm/stack/actualbudget
+./deploy.sh
+```
+
+---
+
+## Common Failures
+| Failure Mode | Symptoms | Cause | Fix |
+|-------------|----------|------|-----|
+| No internet connection | Error messages | Insufficient network connectivity | Check network settings and make sure the service is reachable from all nodes. |
+
+| No data upload | Data not uploading | Insufficient disk space or permissions on /DockerVol/actual | Ensure that the disk has enough space and the user running the service has the necessary permissions. |
+
+| Error connecting to DIUN | Error messages | Incorrect IP address for DIUN | Update the `diun.enable` variable with the correct IP address.
+
+---
+
+## Changelog
+
+| Date | Commit | Summary |
+|------|--------|---------|
+| 2026-04-29 | d5f26841 | Initial documentation creation. |
+| 2026-04-29 | a91a2ded | Updated the Caddy reverse proxy labels and added more error handling in deploy.sh. |
+
+<Note: This stack's history is still evolving, as indicated by the recent commits above.