diff --git a/src/app/docs/catalog/actual-budget/page.tsx b/src/app/docs/catalog/actual-budget/page.tsx index fe40fee..888307c 100644 --- a/src/app/docs/catalog/actual-budget/page.tsx +++ b/src/app/docs/catalog/actual-budget/page.tsx @@ -16,111 +16,111 @@ export default function actualBudgetDocsPage() { intro="Privacy-focused budgeting app with envelope budgeting" >
- Category: Productivity - Difficulty: Easy - Docker image: actualbudget/actual-server:latest -
+ Category: Productivity + Difficulty: Easy + Docker image: actualbudget/actual-server:latest + -

What is Actual Budget?

-

Privacy-focused budgeting app with envelope budgeting

-

Actual Budget ships as a self-contained Docker image that DashCaddy provisions with one click. The platform handles the container lifecycle, DNS, reverse proxy, HTTPS certificate, and persistent storage so you can focus on using Actual Budget, not installing it.

+

What is Actual Budget?

+

Privacy-focused budgeting app with envelope budgeting

+

Actual Budget ships as a self-contained Docker image that DashCaddy provisions with one click. DashCaddy handles the container lifecycle, DNS record, Caddy reverse-proxy entry, and HTTPS certificate so you can focus on using Actual Budget, not installing it.

-

Prerequisites

- +

Prerequisites

+ -

Install via the DashCaddy dashboard

-
    -
  1. Sign in at https://status.sami (or your host's dashboard URL).
    2. -
  2. Open Apps → Catalog and select Actual Budget from the Productivity category.
    3. -
  3. Choose your host (or pick Local if you have one host).
    4. -
  4. Fill in any required fields (notably the media library path and any claim token).
    5. -
  5. Click Deploy. DashCaddy will: -
      -
    1. Pull the actualbudget/actual-server:latest image.
      2. -
    2. Create persistent volumes for config and data.
      3. -
    3. Reserve a host port and wire it through Caddy.
      4. -
    4. Issue a Let's Encrypt certificate for budget.<your-domain>.
      5. -
    5. Wait for the container health check (/) to pass.
      6. -
    -
    6. -
  6. After ~30–60 seconds the dashboard will turn the row Running and the URL will become clickable.
    7. -
+

Install via the DashCaddy dashboard

+
    +
  1. Sign in at https://status.sami (or your host's dashboard URL).
    2. +
  2. Click the 📱 App Selector button on the dashboard home page.
    3. +
  3. Pick Actual Budget from the Productivity category.
    4. +
  4. Fill in the deployment form: subdomain (default suggestion: budget), host port (default: 5006).
    5. +
  5. Click Deploy. DashCaddy will pull the image, create persistent volumes, write a Caddy route, create the DNS record, and wait up to 30 seconds for the container's health check (/) to pass.
    6. +
  6. When the dashboard shows the service as Running, the URL (built from your subdomain and configured TLD) is clickable. The deploy API returns a synchronous response with {success, containerId, url, message, setupInstructions} — there is no separate status-poll endpoint; the dashboard updates live.
    7. +
-

Install via the REST API

-

If you script deployments or use the MCP / AI Intent Router, install with:

- 
curl -X POST https://your-dashcaddy-host/api/v1/apps/deploy \\
-  -H "Authorization: Bearer $DASHCADDY_API_TOKEN" \\
+
Install via the REST API

+
Authenticate with an API key (or a JWT minted via POST /api/v1/auth/jwt). Send as X-API-Key: dk_... or Authorization: Bearer <jwt>.

+
curl -X POST https://status.sami/api/v1/apps/deploy \\
+  -H "X-API-Key: dk_your_api_key" \\
   -H "Content-Type: application/json" \\
   -d '{
-    "template": "actual-budget",
-    "host": "local",
-    "subdomain": "budget",
-    "port": "{{PORT}}",
-    
-    "labels": { "managed-by": "dashcaddy" }
+    "appId": "actual-budget",
+    "config": {
+      "subdomain": "budget",
+      "port": 5006
+    }
   }'

-        
Response returns a deployment ID. Poll GET /api/v1/apps/{id}/status until state === "running".

+
The full body schema is in src/utilities/validate.js (Joi schema appDeploy). All config.* fields except subdomain are optional. Notable options:

+
 
-        
Install via the AI Intent Router

-        
From any chat surface wired to DashCaddy's MCP server, just say:

-        

-          
"Deploy Actual Budget on my home host and expose it at budget.sami"

-        

-        
The Intent Router will pick the right template, prompt you for any missing fields, and start the deployment.

+
Install via the AI Intent Router (returns a structured intent)

+
The Intent Router returns a structured intent, not a deployed container. To deploy via AI, send natural language to:

+
curl -X POST https://status.sami/api/v1/ai/intent \\
+  -H "X-API-Key: dk_your_api_key" \\
+  -H "Content-Type: application/json" \\
+  -d '{ "message": "Deploy Actual Budget on my home host and expose it at budget.sami" }'

+
The response includes intent, action, parameters, and followup — your client (or the MCP server) must then call POST /api/v1/apps/deploy with those parameters to actually provision the container.

 
-        
Post-install: first-run checklist

-        
    
-          
  1. Create your first budget in the web interface
    2. 
-          
  2. Import transactions from your bank (OFX, QFX, CSV)
    3. 
-          
  3. Set up envelope categories for spending control
    4. 
-        

+
Install via the MCP Server

+
For AI agents (Claude Desktop, Hermes, etc.) configure the MCP server (src/mcp/mcp-server.js) with:

+
DASHCADDY_URL=https://status.sami:3001  # internal API URL, may differ from dashboard URL
+DASHCADDY_API_KEY=dk_your_api_key

+
The server exposes dashcaddy_deploy_app. Note: this tool writes the Caddy route and creates the services.json entry, but it does NOT pull the Docker image or start the container. You must run docker pull actualbudget/actual-server:latest and start the container yourself for the URL to actually serve traffic. For a fully-managed deployment, call POST /api/v1/apps/deploy directly from your agent.

 
+
Post-install: first-run checklist

+
    
+  
  1. Create your first budget in the web interface
    2. 
+  
  2. Import transactions from your bank (OFX, QFX, CSV)
    3. 
+  
  3. Set up envelope categories for spending control
    4. 
+

+
Volumes and persistent data

+
DashCaddy creates these volume mounts in the container spec:

+
+
All paths are host paths (left side) mapped into the container (right side). Restarting the container preserves data; reinstalling the template preserves it unless you explicitly pass config.useExisting: false AND wipe the volume. Bind mounts use the host-path conventions above (e.g. /opt/plex/config becomes a bind mount to the host directory of the same path).

 
+
Environment variables

+
None. The container runs with its upstream defaults.
These are baked into the template at deploy time and shipped to the container. The deploy handler does NOT allow overriding them via the API payload — to change them you must edit the template definition in dashcaddy-api/src/docker/app-templates.js.

 
-        
Volumes and persistent data

-        
DashCaddy creates these volume mounts:

-        
-        
All paths are absolute host paths; the left side is the container-side mount. Restarting the container never deletes the data; reinstalling the template preserves it unless you explicitly check Wipe data on the deploy form.

+
Updating the image

+
There is no built-in auto-update — DashCaddy does NOT poll for new image digests. To pull a new version:

+
    
+  
  1. SSH into the DashCaddy host and run docker pull actualbudget/actual-server:latest.
    2. 
+  
  2. Restart the container: docker restart <containerId> (find the ID via GET /api/v1/services or the dashboard).
    3. 
+  
  3. Or deploy Watchtower from this catalog (separate template that polls Docker Hub and updates other containers automatically, default schedule 0 0 4 * * * = 04:00 daily).
    4. 
+

 
-        
Environment variables

-        
None. The container runs with its upstream defaults.

-        
Override any of these from the deploy form's Environment panel, or programmatically in the API environment object.

+
Backups

+
The default backup policy includes the entire /app/data/ directory (services, config, credentials, stats) AND all Docker volumes. Backups are scheduled via backup-config.json — the default schedule is configurable, not "nightly" out of the box. To restore on a fresh host, redeploy the same template and then call POST /api/v1/apps/{appId}/restore with a backup ID from GET /api/v1/backups/history.

 
-        
Updating

-        
DashCaddy's built-in Watchtower integration will pull actualbudget/actual-server:latest every 24 hours and restart your container with zero downtime if the image digest changes. To force an update immediately, click Apps → Actual Budget → Update.

-
-        
Backups

-        
The config volume for Actual Budget is included in DashCaddy's default nightly snapshot. To restore on a fresh host, redeploy the same template and DashCaddy will prompt to restore from the most recent snapshot during install.

-
-        
Troubleshooting

-        
Common issues with Actual Budget:

-        
-        
For layer-by-layer diagnostics, see the Troubleshooting guide.

-
-        
Related services

-        
Actual Budget is in the Productivity category. Common pairings:

-        
-
-        

-        

-          Last reviewed against DashCaddy product version in dashcaddy-api/src/docker/app-templates.js.
-          Template ID: actual-budget. If anything here looks wrong, edit the file and the change will appear in the next docs rebuild.
-        

+
Troubleshooting

+
Common issues with Actual Budget:

+
+
For layer-by-layer diagnostics, see the Troubleshooting guide.

 
+

+

+Template ID: actual-budget. Source: dashcaddy-api/src/docker/app-templates.js.
+