Come fare self-hosting di Vikunja nel 2026: URL pubblico, database e file storage

Se hai già provato a fare self-hosting di Vikunja, probabilmente conosci bene questa situazione frustrante: l'interfaccia compare, ma l'URL pubblico dell'API è errato oppure i file caricati non si trovano su un volume. Ricreare il container raramente risolve un'incoerenza tra URL, stato e dipendenze.

Questa guida usa un unico criterio concreto per considerare completata la configurazione: creare un progetto, un'attività, un allegato e un promemoria, spostare l'attività su una board e verificare l'evento del calendario e la notifica. Ogni scelta di configurazione viene valutata rispetto a questo criterio, non in base a un badge verde del container.

Da cosa dipende Vikunja

Considera tre confini intorno a Vikunja: l'ingress verso la porta 3456, lo stato persistente e i requisiti di supporto. Il container può essere sostituito, ma gli altri due elementi devono avere responsabili espliciti. Il contratto di rete di Vikunja prevede Postgres o MySQL e SMTP per i team in produzione. Mantieni gli endpoint privati su DNS interno, autorizza solo le chiamate outbound necessarie e assegna a Vikunja una credenziale di servizio con scope limitato.

Il diagramma è completo quando un client appena configurato può creare un progetto, un'attività, un allegato e un promemoria, spostare l'attività su una board e verificare l'evento del calendario e la notifica. Raccogli dati su tempi e risorse per il traffico degli allegati, le query al database, i background job e le email outbound, invece di monitorare soltanto il piccolo processo API. Se la transazione fallisce, il primo confine che non si comporta come documentato indica se occorre indagare il routing, la capacità locale o un servizio di supporto.

I volumi sono solo il primo livello di recovery

Elenca lo stato prima di creare il primo record reale: database, file caricati e configurazione. Monta /app/vikunja/files prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è realmente persistente. Conferma il mount scrivendo dati innocui, sostituendo Vikunja e rileggendoli.

Gli snapshot sono utili per un rollback rapido, ma serve un backup indipendente quando l'host o il volume scompare. Esegui il restore in un ambiente vuoto con l'immagine fissata e verifica che progetti, cronologia delle attività, allegati, promemoria e utenti vengano ripristinati e che una notifica pianificata venga ancora inviata. Usa volumi persistenti e snapshot per mantenere distinti questi due meccanismi di recovery.

Proteggi la parte importante di Vikunja

Dopo il primo accesso, verifica cosa può fare un visitatore anonimo, un utente normale e un amministratore. Il problema da evitare in Vikunja è utilizzare un secret JWT invariato o lasciare accidentalmente aperta la registrazione. La policy prevista consiste nell'usare un secret JWT stabile, chiudere la registrazione al termine dell'enrollment e separare gli utenti normali dagli amministratori dei progetti.

Genera VIKUNJA_SERVICE_JWTSECRET come valore lungo e casuale; normalmente la sua rotazione invalida sessioni o token, quindi pianifica l'impatto sugli utenti invece di considerarla una migrazione della cifratura. Mantieni separate le utenze delle dipendenze da quelle umane, nega l'egress non utilizzato dove possibile e limita il lavoro influenzato dal traffico degli allegati, dalle query al database, dai background job e dalle email outbound, invece di limitare soltanto il piccolo processo API.

Trasforma lo smoke test di Vikunja in un controllo di release

Una release candidate di Vikunja si guadagna il traffico completando uno scenario fisso: creare un progetto, un'attività, un allegato e un promemoria, spostare l'attività su una board e verificare l'evento del calendario e la notifica. Raccogli l'image digest, la configurazione effettiva non contenente secret, l'origine pubblica e i timestamp di quello scenario. I dati di test devono essere eliminabili, ma abbastanza realistici da esercitare lo stesso percorso seguito dagli utenti.

Esegui il test dopo aver sostituito il runtime, quindi ricostruisci il servizio a partire da database, file caricati e configurazione. Il recovery ha esito positivo quando progetti, cronologia delle attività, allegati, promemoria e utenti vengono ripristinati e una notifica pianificata viene ancora inviata. Confronta le misurazioni delle risorse per il traffico degli allegati, le query al database, i background job e le email outbound con quelle della release precedente, invece di confrontare soltanto il piccolo processo API, e indaga ogni variazione significativa prima della promozione.

Infine, esegui questo failure controllato: nega temporaneamente all'identità di test l'accesso a Postgres o MySQL e a SMTP per i team in produzione. Verifica che Vikunja descriva il problema, non danneggi lo stato esistente e riprenda a funzionare quando la condizione valida viene ripristinata. Salva un estratto dei log con i dati sensibili rimossi e il tempo di recovery. Nel complesso, questi controlli coprono comportamento, durabilità e operatività, non soltanto l'uptime del processo.

Crea un container Vikunja sostituibile

Il comando seguente rende visibile il confine del container senza fingere di predisporre ogni servizio esterno.

docker run -d \
  --name vikunja \
  --restart unless-stopped \
  -p 127.0.0.1:3456:3456 \
  -v vikunja-data:/app/vikunja/files \
  -e VIKUNJA_SERVICE_JWTSECRET=replace-with-a-long-random-value \
  vikunja/vikunja:latest

Prima di aprire l'ingress, controlla l'ambiente risolto, i mount e il listener. Aggiungi le impostazioni di connessione verificate per Postgres o MySQL e SMTP per i team in produzione; usa nomi privati per i servizi privati. Un avvio riuscito si conclude quando puoi creare un progetto, un'attività, un allegato e un promemoria, spostare l'attività su una board e verificare l'evento del calendario e la notifica, non quando docker ps stampa Up.

Instrada Vikunja senza dichiarare il falso sull'HTTPS

Evita origini pubbliche temporanee e definitive diverse per Vikunja. Imposta invece VIKUNJA_SERVICE_PUBLICURL sull'origine HTTPS esatta, punta il nome DNS scelto alla route della piattaforma e inoltra le richieste soltanto alla porta 3456.

Esegui questa verifica dall'esterno dell'host: crea un progetto, un'attività, un allegato e un promemoria, sposta l'attività su una board e verifica l'evento del calendario e la notifica. Se l'ingress non funziona, la guida alla risoluzione dei problemi 502 tratta gli errori relativi a porte e listener. Se Vikunja riceve la richiesta ma l'URL pubblico dell'API è errato oppure i file caricati non si trovano su un volume, gli elementi disponibili indicano ora una causa oltre il proxy.

Diagnostica di un Vikunja che sembra funzionare

Per Vikunja, monitora una transazione anziché un processo: crea un progetto, un'attività, un allegato e un promemoria, sposta l'attività su una board e verifica l'evento del calendario e la notifica. Combina latenza e tasso di errore con il traffico degli allegati, le query al database, i background job e le email outbound, invece di monitorare soltanto il piccolo processo API, in modo che un alert identifichi il componente sotto pressione.

La prova generale dell'upgrade deve coprire il fatto che le migrazioni del database e la compatibilità tra frontend e API devono essere testate prima di modificare le versioni di Vikunja. Esegui il restore, la migrazione e la transazione prima della sostituzione in produzione. Se l'URL pubblico dell'API è errato oppure i file caricati non si trovano su un volume, non cancellare i dati per ottenere un avvio corretto; confronta, in quest'ordine, versione, variabili, mount e raggiungibilità delle dipendenze.

Esegui il deploy di Vikunja su Dockup senza perdere i suoi confini

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

Il lavoro di acceptance per Vikunja resta esplicito. Dopo il deployment one-click, imposta VIKUNJA_SERVICE_PUBLICURL sull'origine HTTPS esatta, collega e testa Postgres o MySQL e SMTP per i team in produzione, quindi esegui questo scenario: crea un progetto, un'attività, un allegato e un promemoria, sposta l'attività su una board e verifica l'evento del calendario e la notifica. Questa separazione è intenzionale: Dockup elimina la configurazione ripetitiva dell'infrastruttura senza fingere che i ruoli applicativi, le credenziali dei provider o la policy di restore si scelgano da soli.

Domande frequenti

Di cosa ha bisogno Vikunja per un deployment in produzione?

Instrada il container Vikunja sulla porta 3456 attraverso un'unica origine HTTPS. Il requisito di rete per i servizi di supporto è Postgres o MySQL e SMTP per i team in produzione. Non considerare Vikunja pronto finché non puoi creare un progetto, un'attività, un allegato e un promemoria, spostare l'attività su una board e verificare l'evento del calendario e la notifica.

Quali dati di Vikunja devono rientrare in un backup?

Rendi persistente /app/vikunja/files e includi database, file caricati e configurazione nello stesso manifest di recovery. Un restore pulito di Vikunja ha esito positivo solo quando progetti, cronologia delle attività, allegati, promemoria e utenti vengono ripristinati e una notifica pianificata viene ancora inviata.

Vikunja richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Vikunja e mantieni la porta 3456 sulla route interna. Applica correttamente l'impostazione di Vikunja: imposta VIKUNJA_SERVICE_PUBLICURL sull'origine HTTPS esatta. Per Vikunja, 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 Vikunja?

Ripristina lo stato corrente di Vikunja in un deployment isolato, applica la versione candidata e ripeti la transazione di acceptance. Presta particolare attenzione, perché le migrazioni del database e la compatibilità tra frontend e API devono essere testate prima di modificare le versioni di Vikunja. Conserva l'immagine precedente di Vikunja finché non avrai compreso i confini della migrazione dei dati e del rollback.