Comment auto-héberger Vikunja en 2026 : URL publique, base de données et stockage des fichiers

Si vous avez déjà essayé d’auto-héberger Vikunja, vous connaissez probablement cette situation frustrante : l’interface s’affiche, mais l’URL publique de l’API est incorrecte ou les fichiers importés ne se trouvent pas sur un volume. Recréer le conteneur suffit rarement à résoudre un désaccord entre les URL, l’état et les dépendances.

Ce guide utilise un critère de validation concret : créer un projet, une tâche, une pièce jointe et un rappel, déplacer la tâche sur un tableau, puis vérifier son événement de calendrier et sa notification. Chaque choix de configuration est évalué selon ce critère, et non selon l’état « conteneur actif ».

Les dépendances de Vikunja

Délimitez trois zones autour de Vikunja : l’ingress vers le port 3456, l’état durable et les exigences connexes. Le conteneur peut être remplacé, mais les deux autres éléments doivent avoir des responsables clairement définis. Le contrat réseau de Vikunja repose sur Postgres ou MySQL et sur SMTP pour les équipes en production. Conservez les endpoints privés dans le DNS interne, n’autorisez que les appels sortants nécessaires et attribuez à Vikunja un identifiant de service avec des droits limités.

Le schéma est complet lorsqu’un client vierge peut créer un projet, une tâche, une pièce jointe et un rappel, déplacer la tâche sur un tableau, puis vérifier son événement de calendrier et sa notification. Collectez les données de durée et de ressources pour le trafic des pièces jointes, les requêtes de base de données, les tâches en arrière-plan et les e-mails sortants, plutôt que pour le seul petit processus d’API. Si la transaction échoue, la première limite qui ne se comporte pas comme indiqué permet de déterminer s’il faut examiner le routage, la capacité locale ou un service associé.

Les volumes ne sont que la première couche de reprise

Répertoriez l’état avant de créer le premier enregistrement réel : base de données, fichiers importés et configuration. Montez /app/vikunja/files avant le bootstrap, écrivez des données d’exemple inoffensives, puis remplacez le conteneur pour vérifier que ce chemin est réellement persistant. Confirmez le montage en écrivant des données inoffensives, en remplaçant Vikunja, puis en les relisant.

Les snapshots sont utiles pour effectuer rapidement un rollback, mais une sauvegarde indépendante est nécessaire si l’hôte ou le volume disparaît. Effectuez une restauration dans un environnement vide avec l’image épinglée et vérifiez que les projets, l’historique des tâches, les pièces jointes, les rappels et les utilisateurs sont restaurés et qu’une notification planifiée est toujours envoyée. Utilisez les volumes persistants et les snapshots pour bien distinguer ces deux mécanismes de reprise.

Protéger les éléments importants de Vikunja

Après la première connexion, vérifiez ce qu’un visiteur anonyme, un utilisateur standard et un administrateur peuvent chacun faire. Le problème Vikunja à éviter est l’utilisation d’un secret JWT inchangé ou le maintien accidentel des inscriptions ouvertes. La politique visée consiste à utiliser un secret JWT stable, à fermer les inscriptions une fois l’enrôlement terminé et à séparer les membres standard des administrateurs de projets.

Générez VIKUNJA_SERVICE_JWTSECRET sous la forme d’une longue valeur aléatoire ; sa rotation invalide généralement les sessions ou les tokens. Préparez donc l’impact pour les utilisateurs au lieu de la considérer comme une migration de chiffrement. Séparez les comptes de dépendances des comptes humains, refusez les flux sortants inutilisés lorsque c’est possible et limitez le travail influencé par le trafic des pièces jointes, les requêtes de base de données, les tâches en arrière-plan et les e-mails sortants, plutôt que le seul petit processus d’API.

Transformer le smoke test de Vikunja en vérification de release

Une release candidate de Vikunja mérite de recevoir du trafic lorsqu’elle termine un scénario fixe : créer un projet, une tâche, une pièce jointe et un rappel, déplacer la tâche sur un tableau, puis vérifier son événement de calendrier et sa notification. Capturez le digest de l’image, la configuration effective hors secrets, l’origine publique et les timestamps de ce scénario. Les données de test doivent être supprimables, tout en restant suffisamment réalistes pour exercer le même parcours que celui des utilisateurs.

Exécutez ce scénario après avoir remplacé le runtime, puis reconstruisez le service à partir de la base de données, des fichiers importés et de la configuration. La reprise est validée lorsque les projets, l’historique des tâches, les pièces jointes, les rappels et les utilisateurs sont restaurés et qu’une notification planifiée est toujours envoyée. Comparez avec la release précédente les mesures de ressources liées au trafic des pièces jointes, aux requêtes de base de données, aux tâches en arrière-plan et aux e-mails sortants, plutôt que celles du seul petit processus d’API, et examinez tout écart significatif avant la promotion.

Enfin, testez cet incident contrôlé : refusez temporairement à l’identité de test l’accès à Postgres ou MySQL et à SMTP pour les équipes en production. Vérifiez que Vikunja explique l’échec, n’endommage pas l’état existant et reprend son fonctionnement lorsque la condition valide est rétablie. Enregistrez un extrait de log anonymisé ainsi que le temps de reprise. Ensemble, ces vérifications couvrent le comportement, la durabilité et l’exploitabilité, et pas seulement la disponibilité du processus.

Créer un conteneur Vikunja remplaçable

La commande suivante rend visible la limite du conteneur sans prétendre provisionner chaque service externe.

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

Avant d’ouvrir l’ingress, inspectez l’environnement résolu, les montages et le listener. Ajoutez les paramètres de connexion validés pour Postgres ou MySQL et SMTP pour les équipes en production ; utilisez des noms privés pour les services privés. Un lancement réussi se termine lorsque vous pouvez créer un projet, une tâche, une pièce jointe et un rappel, déplacer la tâche sur un tableau, puis vérifier son événement de calendrier et sa notification, et non lorsque docker ps affiche Up.

Router Vikunja sans mentir sur HTTPS

Évitez les origines publiques temporaires et permanentes pour Vikunja. Définissez plutôt VIKUNJA_SERVICE_PUBLICURL sur l’origine HTTPS exacte, faites pointer le nom DNS choisi vers la route de la plateforme et ne proxyfiez que vers le port 3456.

Exécutez cette action depuis l’extérieur de l’hôte : créez un projet, une tâche, une pièce jointe et un rappel, déplacez la tâche sur un tableau, puis vérifiez son événement de calendrier et sa notification. Si l’ingress échoue, le guide de dépannage des erreurs 502 couvre les erreurs de port et de listener. Si Vikunja reçoit la requête, mais que l’URL publique de l’API est incorrecte ou que les fichiers importés ne se trouvent pas sur un volume, les éléments disponibles indiquent désormais un problème situé au-delà du proxy.

Diagnostiquer un Vikunja qui semble sain

Pour Vikunja, surveillez une transaction plutôt qu’un processus : créer un projet, une tâche, une pièce jointe et un rappel, déplacer la tâche sur un tableau, puis vérifier son événement de calendrier et sa notification. Associez sa latence et son taux d’erreur au trafic des pièces jointes, aux requêtes de base de données, aux tâches en arrière-plan et aux e-mails sortants, plutôt qu’au seul petit processus d’API, afin qu’une alerte identifie le composant limité.

La répétition générale de la mise à niveau doit couvrir le fait que les migrations de base de données et la compatibilité frontend/API doivent être testées avant de changer de version de Vikunja. Effectuez une restauration, une migration et la transaction avant de remplacer l’instance de production. Si l’URL publique de l’API est incorrecte ou que les fichiers importés ne se trouvent pas sur un volume, n’effacez pas les données pour obtenir un démarrage au vert ; comparez dans cet ordre la version, les variables, les montages et l’accessibilité des dépendances.

Déployer Vikunja sur Dockup sans perdre ses limites

Dockup peut prendre en charge les éléments remplaçables de la plateforme : acheminer le trafic vers le port 3456, fournir le domaine et le certificat, injecter les secrets, associer le stockage persistant et connecter Vikunja à des services gérés ou attachés en privé. Cela peut être fait sur l’infrastructure Dockup ou sur un serveur que vous rattachez.

La validation de Vikunja reste explicite. Après le déploiement en un clic, définissez VIKUNJA_SERVICE_PUBLICURL sur l’origine HTTPS exacte, connectez et testez Postgres ou MySQL ainsi que SMTP pour les équipes en production, puis exécutez ce scénario : créer un projet, une tâche, une pièce jointe et un rappel, déplacer la tâche sur un tableau, puis vérifier son événement de calendrier et sa notification. Cette répartition est intentionnelle : Dockup supprime la configuration répétitive de l’infrastructure sans prétendre que les rôles applicatifs, les identifiants du fournisseur ou la politique de restauration se choisissent automatiquement.

Foire aux questions

De quoi Vikunja a-t-il besoin pour un déploiement en production ?

Acheminez le conteneur Vikunja sur le port 3456 via une seule origine HTTPS. L’exigence réseau connexe est Postgres ou MySQL et SMTP pour les équipes en production. Ne considérez pas Vikunja comme prêt tant que vous ne pouvez pas créer un projet, une tâche, une pièce jointe et un rappel, déplacer la tâche sur un tableau, puis vérifier son événement de calendrier et sa notification.

Quelles données de Vikunja doivent figurer dans une sauvegarde ?

Rendez /app/vikunja/files persistant et incluez la base de données, les fichiers importés et la configuration dans le même manifeste de reprise. Une restauration Vikunja vierge n’est validée que lorsque les projets, l’historique des tâches, les pièces jointes, les rappels et les utilisateurs sont restaurés et qu’une notification planifiée est toujours envoyée.

Vikunja nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de Vikunja et conservez le port 3456 sur la route interne. Appliquez correctement le paramètre Vikunja : définissez VIKUNJA_SERVICE_PUBLICURL sur l’origine HTTPS exacte. Pour Vikunja, HTTPS protège les identifiants ou le contenu des utilisateurs pendant leur transit et garantit la cohérence du comportement client dépendant de l’origine.

Comment tester une mise à niveau de Vikunja ?

Restaurez l’état actuel de Vikunja dans un déploiement isolé, appliquez la version candidate et répétez sa transaction de validation. Soyez particulièrement attentif, car les migrations de base de données et la compatibilité frontend/API doivent être testées avant de changer de version de Vikunja. Conservez l’image Vikunja précédente jusqu’à ce que les limites de migration des données et de rollback soient comprises.