Ospitare Vikunja su un VPS gestito significa custodire le attività e i progetti del vostro team su una macchina tutta vostra, che i nostri team tengono aggiornata e supervisionano giorno e notte. Vikunja è un software libero con licenza AGPL-3.0. Questa guida segue la sua documentazione ufficiale: la scelta del database, l'installazione con Docker Compose, l'URL pubblico e il segreto, gli account, HTTPS, le impostazioni proprie di Vikunja, l'e-mail, i backup e gli aggiornamenti.
Di Simon Vasconcelos Lee
Pubblicato il 19 novembre 2026Lettura: 13 minuti
vikunja/vikunja:2.8.0 e PostgreSQL, con la porta 3456 pubblicata su 127.0.0.1 dietro un reverse proxy in HTTPS.service.publicurl, l'indirizzo HTTPS della vostra istanza, e service.secret, che firma le sessioni.files, prima di ogni aggiornamento; le migrazioni del database si eseguono da sole all'avvio.Vikunja è un gestore di attività e progetti open source e self-hosted, che il suo repository descrive come «the task manager you actually own», il gestore di attività che possedete davvero. L'API, scritta in Go, e l'interfaccia web sono fornite in un unico binario, o in un'unica immagine Docker: c'è una sola cosa da installare.
Vikunja è pubblicato con la GNU AGPL versione 3 o successiva, tranne la cartella desktop/ del suo repository, l'app desktop, che è con licenza GPL versione 3 o successiva. Potete usarlo, anche in azienda, per il vostro team come per i vostri clienti, senza alcuna licenza da acquistare. Resta il costo del server che lo fa girare.
La sezione 13 aggiunge una condizione propria dell'AGPL: se modificate il programma, la vostra versione deve offrire in modo ben visibile, a chiunque interagisca con essa a distanza tramite una rete, la possibilità di ottenerne il codice sorgente, gratuitamente. Se distribuite delle copie, si applicano anche gli obblighi di condivisione del sorgente previsti dalla licenza. Far girare Vikunja senza modificarlo non attiva questa sezione.
Questa guida installa l'edizione open source, che la documentazione descrive come pienamente funzionale da sola. Vikunja Pro, una licenza facoltativa, aggiunge per le organizzazioni un pannello di amministrazione, il monitoraggio del tempo e i log di audit.
Vikunja funziona con SQLite, PostgreSQL, MySQL o MariaDB. La documentazione non indica alcun valore di memoria o di CPU; orienta la scelta del database in base al numero di utenti:
| Database | Che cosa dice la documentazione | Versione provata nella CI |
|---|---|---|
| SQLite | Incluso nel binario e nell'immagine Docker, niente da installare. Oltre una manciata di utenti, la documentazione raccomanda MySQL o PostgreSQL. | Quella inclusa |
| PostgreSQL | Il database degli esempi Docker della documentazione. Dalla 2.8.0, la ricerca ignora gli accenti con l'estensione unaccent. | 18 |
| MySQL, MariaDB | Almeno MySQL 8.0, perché la 5.7 non è supportata. Per i caratteri non latini, il database deve usare utf8mb4. | MySQL 8, MariaDB 12 |
La documentazione raccomanda una versione del database ancora mantenuta. Redis può fare da cache, ma osserva che probabilmente non vi servirà finché l'istanza conta solo una manciata di utenti: questa guida ne fa a meno.
L'occupazione del disco dipende soprattutto dai vostri allegati e dagli sfondi dei progetti, conservati nella cartella files, con un massimo di 20 MB per file per impostazione predefinita. Su un VPS gestito, parlateci del vostro team, del numero dei suoi utenti e di quanto usa gli allegati, e vi raccomandiamo la taglia adatta.
La documentazione installa Vikunja e PostgreSQL con Docker Compose. Su un server in cui Docker è installato, create una cartella e generate prima il segreto dell'istanza, un valore casuale che incollerete nel file:
openssl rand -hex 32
Collocate poi nella cartella questo docker-compose.yml, tratto dall'esempio PostgreSQL della documentazione. Sostituite tasks.example.com con il vostro nome di dominio, paste-your-secret-here con il valore generato e changeme con una password robusta, la stessa nei due punti:
services:
vikunja:
image: vikunja/vikunja:2.8.0
environment:
VIKUNJA_SERVICE_PUBLICURL: https://tasks.example.com/
VIKUNJA_SERVICE_SECRET: paste-your-secret-here
VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff
VIKUNJA_DATABASE_TYPE: postgres
VIKUNJA_DATABASE_HOST: db
VIKUNJA_DATABASE_USER: vikunja
VIKUNJA_DATABASE_PASSWORD: changeme
VIKUNJA_DATABASE_DATABASE: vikunja
ports:
- "127.0.0.1:3456:3456"
volumes:
- ./files:/app/vikunja/files
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:18
environment:
POSTGRES_USER: vikunja
POSTGRES_PASSWORD: changeme
volumes:
- ./db:/var/lib/postgresql
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
interval: 30s
start_period: 15s
start_interval: 5s
Vikunja gira con l'utente 1000: create la cartella files e affidategliela prima del primo avvio, come chiede la documentazione, poi avviate i servizi:
mkdir files
sudo chown 1000 files
docker compose up -d
docker compose logs vikunja
Al primo avvio, Vikunja crea il proprio database ed esegue tutte le sue migrazioni. La riga http server started on [::]:3456 nei log indica che è pronto, e curl http://127.0.0.1:3456/api/v1/info, lanciato sul server, restituisce la sua versione e le sue impostazioni pubbliche.
127.0.0.1: è qui che ci discostiamo dagli esempi della documentazione, che pubblicano la porta su tutti gli indirizzi. La sua lista di controllo per il rafforzamento della sicurezza chiede che solo il reverse proxy possa raggiungere Vikunja: l'interfaccia si apre allora tramite il proxy, in HTTPS.VIKUNJA_SERVICE_PUBLICURL: l'indirizzo HTTPS che aprono i vostri utenti, con la barra finale. Vikunja lo usa per costruire i suoi link, nelle e-mail per esempio, e come origine CORS autorizzata, attiva per impostazione predefinita: questa impostazione è quindi obbligatoria. Un indirizzo errato, con una porta mancante per esempio, si manifesta con un errore «unauthorized» alla creazione del primo account.VIKUNJA_SERVICE_SECRET firma i token di sessione. Se resta vuoto, viene generato a caso a ogni avvio, e ogni riavvio disconnette allora tutti gli utenti.2.8.0 fissa la versione, come raccomanda la documentazione, così gli aggiornamenti avvengono quando lo decidete voi. latest segue l'ultima versione stabile, e unstable le build di sviluppo.files e db conservano sul server gli allegati e i dati di PostgreSQL: sono ciò che salvate.scratch. Un docker exec verso una shell non funziona, e le variabili PUID e PGID di altre immagini non hanno alcun effetto su di essa. Gli errori si leggono con docker compose logs vikunja.Per una manciata di utenti, la documentazione propone SQLite: rimuovete il servizio db, il blocco depends_on e le variabili VIKUNJA_DATABASE_*, e montate una cartella su /db, dove l'immagine conserva già vikunja.db. Createla e affidatela all'utente 1000, come files:
volumes:
- ./files:/app/vikunja/files
- ./db:/db
Dalla versione 2.4.0, Vikunja pubblica un repository di pacchetti per Debian e Ubuntu, per amd64, arm64 e armhf, firmato con la sua chiave GPG:
curl -fsSL https://dl.vikunja.io/repos/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/vikunja.gpg
echo "deb [signed-by=/usr/share/keyrings/vikunja.gpg] https://dl.vikunja.io/repos/apt stable main" | sudo tee /etc/apt/sources.list.d/vikunja.list
sudo apt update && sudo apt install vikunja
Il pacchetto installa Vikunja in /opt/vikunja, con SQLite per impostazione predefinita, e un servizio systemd abilitato ma non ancora avviato. Scrive anche un segreto casuale in una sezione service di /etc/vikunja/config.yml: completate quella stessa sezione, poi avviate il servizio.
service:
secret: "the value written by the package"
publicurl: "https://tasks.example.com/"
interface: "127.0.0.1:3456"
ipextractionmethod: "xff"
sudo systemctl start vikunja
Vikunja non crea alcun account per impostazione predefinita. Una volta attivo HTTPS, aprite https://tasks.example.com/ e registratevi: è il vostro primo account. Le registrazioni sono aperte per impostazione predefinita, a chiunque raggiunga l'indirizzo; una volta creati gli account del vostro team, la documentazione suggerisce di chiuderle. Aggiungete questa riga alle variabili del servizio vikunja, poi rilanciate docker compose up -d:
VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
Gli account successivi si gestiscono dalla riga di comando. Poiché l'immagine non ha una shell, si richiama direttamente il suo binario:
docker compose exec vikunja /app/vikunja/vikunja user create -u marie -e marie@example.com
docker compose exec vikunja /app/vikunja/vikunja user list
docker compose exec vikunja /app/vikunja/vikunja user reset-password 2 --direct
user create chiede la password quando l'opzione -p non la fornisce, il che la tiene fuori dalla cronologia del vostro terminale.user reset-password invia per e-mail un link di reimpostazione, oppure sostituisce direttamente la password con --direct, usando l'identificativo che mostra user list.user change-status disattiva o riattiva un account, con --disable o --enable.doctor verifica la configurazione, l'URL pubblico, il segreto, il database, l'accesso in scrittura a files e, se attivo, il server SMTP.VIKUNJA_SERVICE_TIMEZONE vale GMT per impostazione predefinita e si aspetta un nome del database tz, Europe/Paris per esempio, mai uno scostamento UTC. Serve da fuso orario predefinito degli utenti, e fissa quindi l'ora dei loro promemoria.Vikunja serve HTTP in chiaro. La documentazione termina HTTPS su un reverse proxy, perché password e token non viaggino mai senza cifratura: il proxy ascolta sulle porte 80 e 443, ottiene il certificato e inoltra a Vikunja su 127.0.0.1:3456.
Dietro un proxy, Vikunja vede per impostazione predefinita l'indirizzo del proxy su ogni richiesta: log e limiti di frequenza colpiscono allora tutti insieme. L'impostazione VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff, già presente nel file Compose, gli fa leggere l'intestazione X-Forwarded-For. Si fida di questa intestazione solo sulle richieste provenienti dagli indirizzi di loopback e di rete privata, compresa la rete di Docker: con la porta pubblicata su 127.0.0.1, ci arriva solo il vostro proxy.
Ecco il Caddyfile della documentazione. Caddy ottiene da solo un certificato Let's Encrypt per il nome indicato, trasmette l'intestazione X-Forwarded-For e lascia passare le connessioni WebSocket:
tasks.example.com {
reverse_proxy 127.0.0.1:3456
}
Il blocco della documentazione si riduce a una riga proxy_pass e a una dimensione di upload. Questo blocco lo riprende con due aggiunte: l'intestazione X-Forwarded-For, che Vikunja legge, e le intestazioni WebSocket. L'interfaccia della versione 2.8.0 apre una connessione WebSocket su /api/v2/ws per i suoi aggiornamenti in tempo reale; quando fallisce, le sue notifiche ripiegano su un'interrogazione ogni 10 secondi. Aggiungete prima questo blocco map alla sezione http di /etc/nginx/nginx.conf:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Poi questo blocco server, sulla porta 80 per lasciare a Certbot l'attivazione di HTTPS:
server {
listen 80;
listen [::]:80;
server_name tasks.example.com;
location / {
proxy_pass http://127.0.0.1:3456;
client_max_body_size 20M;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
sudo nginx -t
sudo certbot --nginx
client_max_body_size 20M corrisponde alla dimensione massima dei file in Vikunja, 20 MB per impostazione predefinita. Se la aumentate con VIKUNJA_FILES_MAXSIZE, la documentazione chiede di aumentare anche questa riga.
Quasi ogni chiave del file config.yml ha la sua variabile d'ambiente: service.enablecaldav diventa VIKUNJA_SERVICE_ENABLECALDAV. Quando un'opzione è definita in entrambi i punti, prevale la variabile. La lista di controllo per il rafforzamento della sicurezza della documentazione passa in rassegna le funzioni da disattivare se non vi servono:
| Chiave | Valore predefinito | Disattivatela per |
|---|---|---|
service.enablelinksharing | true | Impedire la condivisione dei progetti tramite link pubblici |
service.enablecaldav | true | Rimuovere l'endpoint CalDAV, che accetta l'autenticazione HTTP di base |
webhooks.enabled | true | Evitare che Vikunja invii richieste a indirizzi scelti dagli utenti |
service.enabletaskattachments | true | Impedire l'upload di file nelle attività |
service.enableuserdeletion | true | Impedire agli utenti di eliminare il proprio account |
plugins.enabled | false | Già disattivata: tenere il codice di terzi fuori da Vikunja |
Dalla 2.8.0, la ricerca ignora gli accenti su PostgreSQL quando l'estensione unaccent è attiva: «cafe» trova anche «café». L'immagine ufficiale di PostgreSQL la include; attivatela nel database di Vikunja, poi riavviate Vikunja. Il log mostra allora unaccent extension detected, search is accent-insensitive.
docker compose exec db psql -U vikunja -d vikunja -c 'CREATE EXTENSION IF NOT EXISTS unaccent;'
docker compose restart vikunja
Ogni utente importa le proprie attività dalla scheda «Import» delle sue impostazioni, e può anche esportarvi tutti i propri dati in un archivio zip. Le importazioni da file, archivio Vikunja, CSV, TickTick e WeKan, insieme all'importazione da un'istanza Planka, sono sempre disponibili. Todoist, Trello e Microsoft To Do passano da OAuth: sono disattivati per impostazione predefinita e si attivano nella sezione migration della configurazione, con le credenziali dell'app creata presso ciascun servizio. Il reindirizzamento OAuth avviene nel browser: l'istanza non deve essere raggiungibile da questi servizi, ma service.publicurl deve essere corretto.
CalDAV sincronizza le attività con le vostre app, con i parametri di connessione della scheda CalDAV delle impostazioni. La documentazione presenta questa integrazione come una versione alfa che funziona bene con alcuni client: provate il vostro prima di farne lo strumento di tutto il team. Su iPhone e iPad, ogni progetto diventa un elenco nell'app Promemoria. Un account con l'autenticazione a due fattori si connette con un token CalDAV dedicato.
Vikunja invia e-mail per i promemoria delle attività, la conferma dei nuovi account e la reimpostazione delle password. L'invio è disattivato per impostazione predefinita: gli account sono allora attivi appena creati, e la reimpostazione della password per e-mail non è possibile. Una volta attivato l'invio, ogni nuovo account locale conferma il proprio indirizzo prima dell'uso.
Da un VPS Simafri, configurate un server SMTP autenticato, sulla porta 587 o 465: quello del vostro servizio di invio o del vostro fornitore di posta. Aggiungete queste variabili al servizio vikunja:
VIKUNJA_MAILER_ENABLED: "true"
VIKUNJA_MAILER_HOST: smtp.example.com
VIKUNJA_MAILER_PORT: 587
VIKUNJA_MAILER_USERNAME: tasks@example.com
VIKUNJA_MAILER_PASSWORD: your-smtp-password
VIKUNJA_MAILER_FROMEMAIL: tasks@example.com
VIKUNJA_MAILER_FORCESSL: "true", che impone TLS fin dall'inizio della connessione e rifiuta le connessioni non cifrate.plain per impostazione predefinita, login o cram-md5 con VIKUNJA_MAILER_AUTHTYPE, a seconda del vostro server.Rilanciate docker compose up -d, poi inviate un messaggio di prova. Il comando verifica la connessione con un comando SMTP NOOP, che alcuni relay minimali non supportano: preferite un server SMTP completo.
docker compose exec vikunja /app/vikunja/vikunja testmail you@example.com
La documentazione conta due parti da salvare, insieme: il database e la cartella degli allegati. Dalla 2.8.0, le attività e i progetti eliminati passano prima 30 giorni nel cestino; trascorso questo tempo o svuotato il cestino, solo un backup li riporta indietro.
| Elemento | Che cosa conserva | Come copiarlo |
|---|---|---|
| Il database PostgreSQL | Account, progetti, attività, commenti e impostazioni | pg_dump, senza fermare Vikunja |
files | Allegati, avatar e sfondi dei progetti | Una copia della cartella |
Con SQLite, db/vikunja.db | L'intero database | Una copia del file, a Vikunja fermo |
docker-compose.yml | Il segreto, l'URL pubblico e le password | Conservato a parte, come un segreto |
docker compose exec -T db pg_dump -U vikunja vikunja > vikunja-$(date +%F).sql
tar -czf vikunja-files-$(date +%F).tar.gz files
La documentazione chiede backup cifrati conservati fuori dal server, e ripristini provati regolarmente: su un'istanza separata, accedete e aprite un'attività con un allegato. Collocati sul disco del server, questi archivi rientrano anche nei suoi backup notturni.
Il comando vikunja dump raccoglie la configurazione, il database e tutti i file in un archivio zip, e vikunja restore lo ricarica. L'archivio contiene in chiaro il file di configurazione e ogni variabile VIKUNJA_*: cifratelo e proteggetelo come il database stesso.
Su una nuova installazione, con lo stesso docker-compose.yml, caricate l'esportazione nel database ancora vuoto prima del primo avvio di Vikunja, poi rimettete al suo posto la cartella files:
docker compose up -d db
docker compose exec -T db psql -U vikunja vikunja < vikunja-2026-11-19.sql
tar -xzf vikunja-files-2026-11-19.tar.gz
docker compose up -d
Vikunja esegue da solo le migrazioni del database all'avvio di una nuova versione. La documentazione chiede quindi un backup prima di ogni aggiornamento, per poter tornare allo stato precedente, e la lettura delle note di rilascio, che segnalano eventuali passaggi manuali.
files.docker-compose.yml, per esempio da 2.8.0 alla versione successiva.docker compose pull
docker compose up -d
Con il pacchetto Debian, sudo apt update && sudo apt upgrade sostituisce il binario e riavvia il servizio. Passare da una versione stabile alle build unstable funziona, ma la documentazione sconsiglia di tornare indietro: attendete piuttosto la versione stabile successiva.
Le correzioni di sicurezza sono pubblicate come avvisi di sicurezza GitHub e annunciate nelle note di rilascio. La versione 2.8.0 del 5 novembre 2026 ne corregge diciannove, e il suo annuncio chiede di aggiornare appena possibile. Per essere avvisati, seguite i rilasci del repository GitHub o il feed RSS del changelog.
Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; Vikunja resta il vostro software, con le sue impostazioni, i vostri progetti e le vostre attività.
| Argomento | I nostri team | Voi |
|---|---|---|
| Il server | Aggiornamenti del sistema e della sicurezza, interventi sul server compresi | Il momento più adatto alla vostra attività |
| La supervisione | Server seguito 24 ore su 24, 7 giorni su 7, con intervento senza attendere la vostra chiamata | La lettura dei log della vostra istanza |
| Vikunja | Monitoraggio proattivo: errori, rallentamenti e spazio su disco individuati, correzione raccomandata | La sua installazione, i suoi aggiornamenti e le sue impostazioni, che applicate voi o il vostro assistente IA |
| Gli account e i progetti | Il server che li ospita, sorvegliato e salvato | Gli account del vostro team, le registrazioni, le condivisioni e i permessi |
| L'e-mail | Un server che raggiunge il vostro server SMTP sulla porta 587 o 465 | Il vostro servizio di invio e le sue credenziali |
| I backup | Ogni notte, cifrati e conservati fuori dalla macchina; ripristino compreso | Le vostre esportazioni del database e della cartella files, e la richiesta di ripristino, quando ne avete bisogno |
| La migrazione | Il vostro server attuale migrato, in omaggio | Il momento del passaggio |
Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.
Con un VPS gestito Simafri, i nostri team tengono aggiornato il server della vostra istanza Vikunja, lo sorvegliano giorno e notte e intervengono senza attendere la vostra chiamata; seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi o il vostro assistente IA. I backup sono cifrati ogni notte e conservati fuori dalla macchina, il loro ripristino è compreso e la migrazione del vostro server attuale è in omaggio.
Sì. Vikunja ha licenza AGPL-3.0: potete usarlo in azienda senza alcuna licenza da acquistare. Se lo modificate, i vostri utenti remoti devono poter ottenere il codice sorgente della vostra versione. Resta il costo del server che lo fa girare.
SQLite, incluso nell'immagine, basta per una manciata di utenti. Oltre, la documentazione raccomanda PostgreSQL o MySQL. PostgreSQL è il database dei suoi esempi Docker, e dalla 2.8.0 la sua ricerca ignora gli accenti con l'estensione unaccent.
Create un docker-compose.yml con le immagini vikunja/vikunja:2.8.0 e postgres:18, la porta 3456 pubblicata su 127.0.0.1, una cartella files affidata all'utente 1000, l'URL pubblico e il segreto, poi lanciate docker compose up -d. Collocate quindi un reverse proxy in HTTPS davanti alla porta 3456.
service.publicurl è l'indirizzo HTTPS della vostra istanza: Vikunja ne ricava i suoi link e la sua origine CORS, da cui un errore unauthorized quando è errato. service.secret firma le sessioni; se resta vuoto, cambia a ogni avvio e disconnette tutti gli utenti.
Vikunja non ha un account predefinito: registratevi sulla vostra istanza. Chiudete poi le registrazioni impostando VIKUNJA_SERVICE_ENABLEREGISTRATION su false, e create gli account successivi con il comando vikunja user create, lanciato nel container.
Attivate l'invio con VIKUNJA_MAILER_ENABLED, poi indicate l'host, la porta 587 o 465, il nome utente, la password e l'indirizzo del mittente del vostro server SMTP. Senza e-mail, gli account sono attivi appena creati e le password si reimpostano dalla riga di comando.
Salvate insieme il database, con pg_dump per PostgreSQL, e la cartella files degli allegati. Conservate le copie cifrate e fuori dal server, fatene una prima di ogni aggiornamento e provate regolarmente a ripristinarle.
Un VPS gestito copre il server: sistema, sicurezza, supervisione e backup. I nostri team seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi. Un intervento nell'applicazione si fattura a ore o a forfait.
Simafri
Parliamo del vostro progetto
Diteci in due parole ciò che vi serve: vi rispondiamo rapidamente.
Grazie! La tua richiesta è stata inviata. Ti risponderemo a breve.
Preferite l'email? Scriveteci a support@simafri.com.