traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gremlin): update actualbudget

Browse source
This commit is contained in:
traveler 2026-04-29 13:23:22 -05:00
parent d6feeb1891
commit 2b112ec73c
1 changed files with 23 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

64
Netgrimoire/Services/actualbudget/actualbudget.md
View file

@ -1,37 +1,35 @@
---
title: actualbudget Stack
description: NetGrimoire budgeting service
description: Envelope budgeting
published: true
date: 2026-04-29T18:20:54.861Z
date: 2026-04-29T18:20:53.359Z
tags: docker,swarm,actualbudget,netgrimoire
editor: markdown
dateCreated: 2026-04-29T18:20:54.861Z
dateCreated: 2026-04-29T18:20:53.359Z
---
# 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.
The actualbudget stack is a Docker Swarm configuration for the Actual Budget service in NetGrimoire. It provides envelope budgeting capabilities and is deployed on the docker4 host.
## Architecture
| Service | Image | Port | Role |
|---------|-------|------|-----|
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** budget.netgrimoire.com:5006
- **Homepage group:** PNCHarris Apps
---
- Exposed via: budget.netgrimoire.com, actual:5006 (Caddy reverse proxy)
- 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`).
This stack requires a Docker Swarm manager and worker environment with Docker installed. The `.env` file should be present in the root directory of the service.
### Volume Setup
```bash
mkdir -p /DockerVol/actual
chown $USER:$USER /DockerVol/actual
chown -R actual:actual /DockerVol/actual
```
### Environment Variables
@ -39,8 +37,6 @@ chown $USER:$USER /DockerVol/actual
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
@ -54,61 +50,47 @@ docker stack services actualbudget
```
### First Run
After deploying, the `diun` service needs to be updated with the new IP address.
---
After the initial deployment, verify that the service is up and running by checking the Docker Stack Services output.
## User Guide
### Accessing actualbudget
| Service | URL | Purpose |
|---------|-----|---------|
- **Actual Server:** https://budget.netgrimoire.com/actual
- **DIUN (Disaster Recovery):** https://budget.netgrimoire.com/diun
- **Actual Budget**: https://budget.netgrimoire.com (Homepage)
### 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.
---
To use this stack in NetGrimoire, integrate it with other services as needed. This may involve configuring API connections or sharing data through the network.
## Operations
### Monitoring
Check the Uptime Kuma monitors for the `kuma.actual.http.name: "Actual Budget"` label.
```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.
Critical paths to back up are `/DockerVol/actual`. Make sure to update your backup rotation schedule accordingly.
### Restore
To restore the stack, run the following command:
```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.
---
- Failure Mode 1: Service is not available. Symptom: The URL is unreachable. Cause: The service may be down or behind a proxy. Fix: Check the Caddy reverse proxy configuration and ensure the service is running.
- Failure Mode 2: Uploads are slow or failing. Symptom: Upload speeds are below expected limits. Cause: File size limits may be too low, or uploads are experiencing high latency. Fix: Review upload file size limits and optimize settings as needed.
## 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. |
| 2026-04-29 | a91a2ded | Initial documentation for the actualbudget Stack |
| 2026-04-11 | 4e7cb8f9 | Initial commit of swarm/actualbudget.yaml |
<Note: This stack's history is still evolving, as indicated by the recent commits above.
## Notes
- Generated by Gremlin on 2026-04-29T18:20:53.359Z
- Source: swarm/actualbudget.yaml
- Review User Guide and Changelog sections