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

docs(gremlin): create actualbudget

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

114
Netgrimoire/Services/actualbudget/actualbudget.md Normal file
View file

@ -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.