Come fare il self-hosting di Actual Budget nel 2026: sync, HTTPS e backup dei dati finanziari

Un deployment di Actual Budget che non funziona non va necessariamente in crash. Potrebbe mostrare una pagina di login mentre la directory di sync è effimera oppure un proxy rimuove le richieste di sync di grandi dimensioni. Inizia invece con un controllo end-to-end: crea o importa un budget, aggiungi alcune transazioni, sincronizza un secondo browser e genera un export a livello applicazione.

Questo controllo riflette lo scopo documentato di Actual Budget: il budgeting a buste con i dati conservati sul tuo disco. Inoltre mette in evidenza prima che un semplice uptime probe le dipendenze mancanti, le ipotesi errate sul proxy e i dati effimeri.

Separa Actual Budget dalle sue dipendenze

Inizia dal namespace di rete di Actual Budget: il suo web listener usa la porta 5006, non una host port copiata da un tutorial per laptop. Il requisito del runtime locale consiste in un volume di dati persistente e in un browser supportato per la configurazione iniziale. Mantieni esplicito il suo lifecycle, così spostare Actual Budget tra host diversi non ne modifica il comportamento senza che tu te ne accorga.

Dopo aver soddisfatto il requisito, esegui lo scenario completo — crea o importa un budget, aggiungi alcune transazioni, sincronizza un secondo browser e genera un export a livello applicazione. Registra log e misurazioni relativi alla dimensione dei file del budget, al traffico di sync e allo storage del server, invece di concentrarti su calcoli pesanti lato server. Queste informazioni diventano la prima architettura verificata e rendono testabili gli spostamenti successivi tra il compute di Dockup e un server collegato.

Esegui la prima istanza con caratteristiche simili alla produzione

Un comando minimale è utile quando mostra cosa verrà poi gestito dalla piattaforma.

docker run -d \
  --name actual-budget \
  --restart unless-stopped \
  -p 127.0.0.1:5006:5006 \
  -v actual-budget-data:/data \
  -e ACTUAL_PORT=5006 \
  actualbudget/actual-server:latest

In questo modo la porta 5006 resta privata sull'host e ogni path richiesto è esplicito. Verifica il requisito locale prima dell'esposizione: un volume di dati persistente e un browser supportato per la configurazione iniziale. Verifica l'avvio usando sia i log sia la prova specifica dell'applicazione: crea o importa un budget, aggiungi alcune transazioni, sincronizza un secondo browser e genera un export a livello applicazione. Dopo la verifica, fissa la versione dell'immagine, così una sostituzione ordinaria non ne modifica il comportamento senza che tu te ne accorga.

Rendi inequivocabile l'origine pubblica

Scegli l'hostname definitivo di Actual Budget prima che gli utenti salvino callback o impostazioni del client, quindi usa un URL HTTPS stabile affinché i client di sync si fidino del server. La route della piattaforma deve terminare TLS una sola volta e puntare alla porta privata 5006.

Esegui la transazione di accettazione dall'esterno. Se il client non raggiunge mai Actual Budget, usa la checklist per la validazione SSL per i controlli DNS e del certificato. Se la richiesta raggiunge Actual Budget ma la directory di sync è effimera oppure un proxy rimuove le richieste di sync di grandi dimensioni, smetti di modificare i redirect del proxy e analizza invece il confine specifico dell'applicazione.

Rendi misurabile il ripristino di Actual Budget

Crea un recovery manifest per Actual Budget: i file del server più export periodici del budget a livello applicazione. Monta /data prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel path è effettivamente persistente. Controlla subito permessi e spazio libero, perché un path montato ma non scrivibile equivale a nessuna persistenza.

Esegui il backup in un failure domain separato dal server in esecuzione. Ricrea Actual Budget a partire dalla sua immagine fissata e verifica che il server ripristinato sincronizzi gli stessi account e saldi e che anche l'export indipendente possa essere importato. La guida ai persistent volume aiuta a trasformare questo esercizio in una policy di snapshot e retention.

Metti in sicurezza Actual Budget dopo il bootstrap

Le credenziali di bootstrap sono temporanee; il modello di trust è permanente. Con Actual Budget, presta attenzione a non pubblicare un server finanziario prima di aver configurato la password e imposta la password del server prima dell'esposizione; usa inoltre HTTPS perché l'istanza contiene l'intera cronologia finanziaria.

ACTUAL_PORT controlla il comportamento, non la riservatezza; verifica il suo tipo e il suo valore e conserva separatamente le credenziali reali di Actual Budget. Esegui l'immagine senza capability Linux non necessarie ed esponi solo la route pubblica dell'applicazione. Mantieni visibili le attività degli amministratori senza registrare valori segreti.

Gestisci Actual Budget in base al suo vero collo di bottiglia

Crea dashboard incentrate sulla dimensione dei file del budget, sul traffico di sync e sullo storage del server, invece di concentrarti su calcoli pesanti lato server. Un grafico della CPU privo del contesto del workload non può spiegare perché Actual Budget sia lento. Aggiungi un controllo sintetico o pianificato che provi a creare o importare un budget, aggiungere transazioni, sincronizzare un secondo browser e generare un export a livello applicazione usando dati di test innocui.

Prima di un upgrade, considera questo rischio specifico dell'applicazione: le data migration di Actual devono essere testate con i file del server e un budget esportato disponibili per il rollback. Ripristina un backup recente in un deployment isolato, esegui lì le migration e confronta il comportamento. Se la directory di sync è effimera oppure un proxy rimuove le richieste di sync di grandi dimensioni, analizza il confine coinvolto — origine pubblica, storage o dipendenza — prima di modificare impostazioni non correlate.

Raccogli le evidenze prima di mettere Actual Budget online

Crea un fixture Actual Budget piccolo e usa e getta e conservalo per ogni release. Il fixture deve coprire il workflow reale: crea o importa un budget, aggiungi transazioni, sincronizza un secondo browser e genera un export a livello applicazione. Registra il digest dell'immagine, l'hostname esterno, l'indirizzo della dipendenza e il risultato atteso, così un operatore successivo potrà ripetere il test senza dover interpretare questa guida.

Esegui il fixture tre volte. Per prima cosa, usa il deployment appena creato. Poi sostituisci il container senza modificare lo stato persistente. Infine, ripristina il backup in un ambiente vuoto. La terza esecuzione ha esito positivo solo quando il server ripristinato sincronizza gli stessi account e saldi e anche l'export indipendente può essere importato. Durante ogni esecuzione, acquisisci latenza e utilizzo delle risorse relativi alla dimensione dei file del budget, al traffico di sync e allo storage del server, invece di concentrarti su calcoli pesanti lato server; questi dati diventano la baseline per gli alert, anziché una percentuale CPU arbitraria.

Infine, testa deliberatamente il negative path: invia input innocui vicino al limite di risorse o di formato associato a questo confine: la directory di sync è effimera oppure un proxy rimuove le richieste di sync di grandi dimensioni. Verifica che Actual Budget fallisca in modo visibile senza corrompere lo stato, ripristina la condizione corretta e ripeti la transazione con esito positivo. Un release record contenente questi quattro risultati costituisce un'evidenza più solida degli screenshot di una dashboard o della risposta ottenuta con un curl eseguito una sola volta.

Sposta su Dockup il lavoro infrastrutturale ripetibile

Dockup può gestire i componenti sostituibili della piattaforma: instradare il traffico verso la porta 5006, emettere il dominio e il certificato, iniettare i secret, collegare lo storage persistente e connettere Actual Budget a servizi gestiti o collegati privatamente. Può farlo sull'infrastruttura Dockup o su un server che colleghi tu.

Il lavoro di accettazione di Actual Budget resta esplicito. Dopo il deployment one-click, usa un URL HTTPS stabile affinché i client di sync si fidino del server, conferma il requisito locale — un volume di dati persistente e un browser supportato per la configurazione iniziale — ed esegui questo scenario: crea o importa un budget, aggiungi transazioni, sincronizza un secondo browser e genera un export a livello applicazione. Questa divisione è intenzionale: Dockup elimina la configurazione infrastrutturale ripetitiva senza fingere che ruoli applicativi, credenziali del provider o policy di ripristino si definiscano da soli.

Domande frequenti

Di cosa ha bisogno Actual Budget per un deployment in produzione?

Instrada il container di Actual Budget sulla porta 5006 attraverso un'unica origine HTTPS. Il requisito del runtime locale consiste in un volume di dati persistente e in un browser supportato per la configurazione iniziale. Non considerare Actual Budget pronto finché non puoi creare o importare un budget, aggiungere transazioni, sincronizzare un secondo browser e generare un export a livello applicazione.

Quali dati di Actual Budget devono essere inclusi in un backup?

Rendi persistente /data e includi nel recovery manifest i file del server più export periodici del budget a livello applicazione. Un ripristino pulito di Actual Budget ha esito positivo solo quando il server ripristinato sincronizza gli stessi account e saldi e anche l'export indipendente può essere importato.

Actual Budget richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Actual Budget e mantieni la porta 5006 sulla route interna. Applica correttamente l'impostazione di Actual Budget: usa un URL HTTPS stabile affinché i client di sync si fidino del server. Per Actual Budget, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come si deve testare un upgrade di Actual Budget?

Ripristina lo stato corrente di Actual Budget in un deployment isolato, applica la versione candidata e ripeti la transazione di accettazione. Presta particolare attenzione perché le data migration di Actual devono essere testate con i file del server e un budget esportato disponibili per il rollback. Conserva l'immagine precedente di Actual Budget finché non avrai compreso il confine tra data migration e rollback.