Exploitation¶

Exploitation courante d'un Arca installé. Pour l'installer ou le mettre à jour, voir Installation.

Configuration¶

Variable	Défaut	Effet
`ARCA_SECRET_KEY`	—	Obligatoire sauf si `ARCA_DEBUG` est actif. À générer avec `python3 -c "import secrets; print(secrets.token_urlsafe(50))"`.
`ARCA_ALLOWED_HOSTS`	—	Noms ou IP utilisés pour joindre Arca, séparés par des virgules (`arca.lan,192.168.1.20`).
`ARCA_TIME_ZONE`	`UTC`	Fuseau horaire IANA (`Europe/Paris`) : il détermine ce qu'est aujourd'hui.
`ARCA_MAX_UPLOAD_MB`	`25`	Taille maximale d'un document, en Mo. Arca cesse de recevoir un document au-delà, même si le proxy inverse n'impose aucune limite (Traefik et Pangolin n'en imposent pas par défaut). Un proxy qui a sa propre limite doit accepter au moins autant (nginx : `client_max_body_size`).
`ARCA_DATA_DIR`	`./data`	Base de données et documents. Docker utilise toujours `/data`.
`ARCA_BACKUP_DIR`	`./backups`	Archives de sauvegarde chiffrées. Docker utilise toujours `/backups`.
`ARCA_HTTPS`	inactif	Derrière un proxy HTTPS : cookies sécurisés, redirection vers HTTPS, HSTS.
`ARCA_TRUSTED_PROXIES`	—	Derrière un proxy : l'adresse (ou le réseau, `10.0.0.0/8`) depuis laquelle le proxy se connecte, séparées par des virgules. Arca lit alors l'adresse du client dans `X-Forwarded-For` pour limiter les tentatives de connexion ; voir Sécurité de la connexion.
`ARCA_CSRF_TRUSTED_ORIGINS`	—	Derrière un proxy : l'origine publique (`https://arca.example.org`).
`ARCA_VERSION`	`latest`	Docker seulement : la version de l'image à lancer (`0.1.0`).
`ARCA_DEBUG`	inactif	Développement uniquement.

Sauvegardes automatiques¶

Ouvrez Sauvegardes et choisissez Activer les sauvegardes automatiques. Arca affiche une clé de secours une seule fois — XXXX-XXXX-XXXX-XXXX-XXXX-XXXX — et propose un kit de secours à télécharger. Gardez-la loin du serveur (gestionnaire de mots de passe, copie imprimée) : c'est le seul moyen d'ouvrir les archives, et Arca ne peut pas la réafficher.

Arca fait ensuite une archive chiffrée chaque jour (le service backup vérifie toutes les heures) et garde la plus récente archive de chacun des 7 derniers jours, des 4 dernières semaines et des 12 derniers mois, plus les 2 plus récentes (une sauvegarde manuelle faite juste avant une modification survit ainsi à la suivante).
Les archives vont dans ARCA_BACKUP_DIR : avec Docker, le volume arca-backups. Pour les ranger sur un NAS, remplacez le volume par un dossier monté dans compose.yaml (- /mnt/nas/arca:/backups dans les deux services).
Copiez-les hors du serveur (sauvegarde Proxmox, rsync, NAS) : Arca ne fait aucun appel réseau.
Exporter télécharge une archive fraîche du même type, lisible avec la même clé.
Le serveur ne garde que la moitié publique de la clé : il peut faire des archives, pas les lire. Une clé de secours perdue ne se récupère pas.

Les sauvegardes incluent les documents. Un document supprimé reste dans les sauvegardes faites avant, jusqu'à ce que leur rotation les efface.

Copies hors du serveur¶

Des sauvegardes sur la même machine que les données ne survivent ni à une panne de disque, ni à un incendie, ni à un vol. Gardez en tête la règle 3-2-1 : 3 copies de vos données, sur 2 supports différents, dont 1 ailleurs. Les archives sont chiffrées par votre clé de secours : n'importe quel stockage convient, y compris un service cloud grand public. Conservez la clé de secours ailleurs que les archives (gestionnaire de mots de passe, kit de secours imprimé).

Arca ne fait aucun appel réseau : la copie est faite par vous ou par l'outil de votre choix. Trois niveaux, du plus simple au plus automatique :

1. Télécharger une archive (tout le monde). Dans la page Sauvegardes, téléchargez la dernière archive (ou un export) vers un autre appareil : clé USB, ordinateur portable. Arca affiche la date de la dernière fois, et le contrôle d'intégrité vous le rappelle après 30 jours sans copie téléchargée.

2. Un dossier synchronisé. Rangez les archives dans un dossier qu'un client de synchronisation recopie déjà ailleurs (Syncthing, Nextcloud, Dropbox, OneDrive, Google Drive…). Avec Docker, remplacez le volume arca-backups par ce dossier dans compose.yaml, pour les services arca et backup :

    volumes:
      - arca-data:/data
      - /home/moi/Sync/arca-backups:/backups

Le dossier doit être accessible en écriture à l'uid 1000 (l'utilisateur arca de l'image).

3. Une copie automatique. Sur l'hôte Docker, une tâche planifiée copie les archives vers une autre machine ou un stockage distant. Vers un NAS ou une autre machine en SSH, avec rsync (crontab de l'hôte, chaque nuit à 3 h 30) :

30 3 * * * rsync -a --delete /var/lib/docker/volumes/arca_arca-backups/_data/ nas:/backups/arca/

Vers presque n'importe quel stockage (S3, Backblaze B2, SFTP, WebDAV, Google Drive, OneDrive…), avec rclone après rclone config :

30 3 * * * rclone sync /var/lib/docker/volumes/arca_arca-backups/_data remote:arca-backups

Le chemin du volume dépend du nom du projet compose (docker volume inspect arca_arca-backups l'indique). Aux niveaux 2 et 3, cochez Une copie automatique hors du serveur est en place dans la page Sauvegardes : Arca ne voit pas ces copies, et cesse de vous le rappeler.

Restaurer¶

Depuis le navigateur : Sauvegardes › Restaurer…, choisissez une archive dans la liste ou envoyez-en une, tapez la clé de secours. Arca vérifie tout d'abord (clé, intégrité de l'archive, base de données, version) et ne change rien si un contrôle échoue. Après confirmation, il redémarre et remplace les données avant de servir de nouveau les pages ; les données précédentes sont gardées dans un dossier before-restore-<date> du volume de données. Connectez-vous avec le compte tel qu'il était à la date de l'archive.

Sur un nouveau serveur : installez Arca, démarrez-le une fois (docker compose up -d), créez un compte, puis utilisez Sauvegardes › Restaurer une archive venant d'une autre installation… avec le fichier envoyé.

Si Arca ne démarre plus, restaurez en ligne de commande, service web arrêté :

docker compose stop arca
docker compose run --rm arca python manage.py restore /backups/arca-AAAAMMJJ-HHMMSS.arca-backup
docker compose start arca

Depuis les sources, Arca ne redémarre pas tout seul : après avoir confirmé une restauration dans le navigateur, arrêtez Arca, lancez uv run manage.py restore --apply-staged, puis redémarrez-le. Ou restaurez en ligne de commande, Arca arrêté : uv run manage.py restore <archive>.

Copie manuelle du volume¶

En secours, ou avant une opération risquée sur le serveur, copiez tout le volume pendant qu'Arca est arrêté (la base est alors cohérente) :

docker compose stop arca
docker run --rm -v arca_arca-data:/data:ro -v "$PWD":/backup alpine \
  tar czf "/backup/arca-$(date +%F).tar.gz" -C /data .
docker compose start arca

Le volume s'appelle <répertoire du projet>_arca-data (docker volume ls). Gardez une copie hors du serveur, idéalement chiffrée : une sauvegarde sur la même machine ne survit pas à sa panne.

Pour restaurer :

docker compose stop arca
docker run --rm -v arca_arca-data:/data -v "$PWD":/backup alpine \
  sh -c 'test -f /backup/arca-AAAA-MM-JJ.tar.gz && rm -rf /data/* && tar xzf /backup/arca-AAAA-MM-JJ.tar.gz -C /data'
docker compose start arca

test -f s'arrête avant de vider le volume si le nom de l'archive est faux. Sur un nouveau serveur, lancez une fois docker compose up -d pour que le conteneur et son volume existent, puis restaurez comme ci-dessus.

Depuis les sources : arrêtez le service, puis copiez le répertoire ARCA_DATA_DIR ; restaurez-le en le recopiant, service arrêté.

Intégrité¶

Arca se vérifie lui-même : le fichier de la base (corruption, références cassées), la cohérence des données dérivées (dates d'action, jours d'ancrage, codes de devise) et l'installation (migrations, contrôles Django, répertoire de données, espace libre, versions des paquets).

Les documents sont vérifiés aussi : fichier absent (erreur), fichier modifié depuis son ajout (erreur, contrôle complet seulement) et fichier qui n'appartient à aucun document (avertissement ; il n'est jamais supprimé, examinez-le avant de l'effacer à la main).

Un contrôle rapide tourne à chaque démarrage du conteneur ; son résultat apparaît dans la page Intégrité et sur le tableau de bord.
La page Intégrité peut lancer un contrôle rapide à la demande.
Le contrôle complet et les réparations se lancent depuis un terminal :

docker compose exec arca python manage.py doctor --mode full
docker compose exec arca python manage.py doctor --mode full --fix

Depuis les sources : uv run manage.py doctor --mode full (ajoutez --fix pour réparer).

--fix ne recalcule que des champs dérivés (date d'action, jour d'ancrage) ; il ne supprime jamais rien. Le code de sortie vaut 0 si tout va bien, 1 en cas d'avertissements, 2 en cas d'erreurs — utilisable par un outil de supervision.

Flux agenda¶

Arca peut publier vos échéances à venir sous forme de flux agenda privé : un événement sur la journée entière à la date d'action de chaque échéance, avec des alarmes à 9 h avant (90, 30 et 7 jours par défaut, réglables dans la page Agenda). Les échéances traitées ou ignorées quittent le flux. Le flux ne contient jamais de numéro de référence, de montant, d'organisme ni de notes.

Activez-le depuis la page Agenda, puis abonnez-vous à son adresse. Les textes du flux sont dans la langue de l'interface au moment de l'activation ; pour en changer, désactivez puis réactivez le flux dans l'autre langue (ce qui donne une nouvelle adresse : réabonnez-vous).

iPhone, iPad : Réglages › Apps › Calendrier › Comptes de calendrier › Ajouter un compte › Autre › Ajouter un calendrier avec abonnement (avant iOS 18 : Réglages › Calendrier › Comptes › …), collez l'adresse. Ouvrez ensuite l'abonnement et désactivez Supprimer les alertes, sinon les alarmes sont ignorées. Le bouton S'abonner de la page Agenda fait la même chose depuis le navigateur du téléphone ; si Arca est servi en HTTP simple (réseau local), iOS tente d'abord une connexion sécurisée puis demande s'il faut continuer sans : acceptez.
Mac : Calendrier › Fichier › Nouvel abonnement à un calendrier, ou le bouton S'abonner ; décochez Supprimer les alertes.
Android : installez ICSx⁵ (gratuit sur F-Droid) et ajoutez l'adresse ; toute application d'agenda affiche ensuite les événements et les alarmes. Dans Google Agenda, les agendas d'ICSx⁵ restent masqués tant que leur compte n'est pas coché : dans l'application Google Agenda (pas dans les paramètres d'Android), Paramètres › Gérer les comptes, puis cochez Abonnements à des calendriers.
Ordinateur : Thunderbird, Evolution et GNOME Agenda s'abonnent à une adresse (Nouvel agenda › Sur le réseau).
Google Agenda (À partir de l'URL) est déconseillé : ce sont les serveurs de Google qui lisent le flux, qui doit donc être joignable depuis Internet ; ils ignorent les alarmes et rafraîchissent lentement.

Les applications d'agenda rafraîchissent à leur rythme (de 15 minutes à un jour) : une modification dans Arca apparaît au rafraîchissement suivant.

Flux par personne. Le flux ci-dessus est le flux complet, pour vous qui gérez le foyer. Pour donner à un membre du foyer ses seules échéances, activez son flux dans Flux par personne, sur la page Agenda. Les échéances de tout le foyer (dossiers sans personne) n'y figurent que si vous cochez Inclure les échéances de tout le foyer pour cette personne. Les délais d'alarme sont communs à tous les flux. Chaque adresse vaut un mot de passe pour son flux ; renouvelez-la ou désactivez-la séparément.

Joindre le flux. Arca sert seulement l'adresse ; votre téléphone doit pouvoir l'atteindre :

réseau local seul : rien à faire, le téléphone se met à jour à la maison ;
VPN (Tailscale, WireGuard…) : le téléphone est « à la maison » partout ;
proxy inverse (Caddy, Traefik, nginx, Cloudflare Tunnel, Pangolin…) : le jeton protège le flux. Si le proxy place une connexion (authentification unique) devant Arca, laissez passer le chemin /ical/ sans elle : une application d'agenda ne sait pas se connecter.

Avec Pangolin et la SSO de la plateforme, ouvrez la ressource Arca, onglet Règles :

Activez Activer les règles.
Ajouter une règle : action Toujours autoriser (outrepasser l'authentification), type de correspondance Chemin, valeur /ical/*, priorité 1.
Cliquez sur Enregistrer les règles.

Si la ressource utilise une politique partagée (« Cette ressource hérite de… »), ses règles viennent de cette politique, et celles saisies sur la ressource ne s'appliquent pas : donnez à la ressource sa propre politique, ou ajoutez la règle à la politique partagée (elle vaut alors pour toutes les ressources qui l'utilisent). Pour vérifier, ouvrez https://<votre domaine>/ical/test.ics sans être connecté : la page « Not Found » d'Arca prouve que la règle fonctionne ; « Unauthorized » de Pangolin, qu'elle ne s'applique pas.

Sécurité. L'adresse vaut un mot de passe : quiconque la possède peut lire le flux. En cas de fuite, créez une nouvelle adresse dans la page Agenda et réabonnez vos appareils. Le jeton fait partie de l'adresse : il apparaît donc dans les journaux d'accès (ceux d'Arca et de votre proxy).

La double authentification (page Sécurité) demande, après le mot de passe, un code d'une application d'authentification sur votre téléphone (Aegis, 2FAS, Google Authenticator, KeePassXC…). Activez-la quand Arca est joignable depuis Internet sans proxy d'authentification. Elle est inutile sur un réseau local, derrière un proxy qui demande déjà un second facteur (Pangolin, Authelia, Authentik…) ou dans l'application de bureau.

Activer la double authentification affiche un QR code : scannez-le, puis saisissez le code affiché par l'application. Rien n'est actif tant que ce code n'est pas accepté.
Arca affiche ensuite 10 codes de secours, une seule fois. Chacun remplace une fois un code du téléphone. Gardez-les loin du téléphone : imprimés, ou dans votre gestionnaire de mots de passe. Régénérer les codes de secours les remplace tous.
Désactiver demande un code.
Téléphone et codes perdus : sur le serveur, lancez docker compose exec arca python manage.py disable_2fa (depuis les sources : uv run manage.py disable_2fa), puis connectez-vous avec le mot de passe seul.
Restaurer une sauvegarde ancienne remet la double authentification dans l'état de l'archive : le téléphone reste valable, les codes de secours sont ceux de l'époque.

Les tentatives de connexion sont limitées par adresse : après 5 échecs, l'adresse est bloquée 1 minute, puis deux fois plus longtemps à chaque nouvel échec, jusqu'à 15 minutes ; le compte repart de zéro après 15 minutes sans échec (comptées depuis la fin du dernier blocage). Un code faux compte comme un mot de passe faux. Derrière un proxy inverse, toutes les requêtes viennent de l'adresse du proxy : indiquez-la dans ARCA_TRUSTED_PROXIES, pour qu'Arca lise l'adresse du client dans X-Forwarded-For, que le proxy ajoute (c'est le cas de Pangolin, Traefik, Caddy, et de nginx avec proxy_add_x_forwarded_for). Sans ce réglage, les échecs comptent pour l'adresse du proxy, partagée par tous : les échecs d'un attaquant vous bloqueraient aussi, et le contrôle d'intégrité le signale quand ARCA_HTTPS est actif. L'en-tête n'est cru que venant de ces adresses : un client qui atteint directement le port d'Arca ne peut pas choisir son adresse. Pour trouver l'adresse du proxy, regardez d'où viennent les requêtes, par exemple avec Docker : la passerelle du réseau d'Arca (docker network inspect arca_default) quand le proxy atteint Arca par le port publié sur la même machine. Chaque échec est journalisé, par exemple :

2026-09-30 12:00:00,000 WARNING arca.auth Login failure from 203.0.113.7 at the password step

Les adresses IPv6 sont comptées par /64, que la ligne ajoute : … from 2001:db8:1:2::1 at the code step (counted for 2001:db8:1:2::/64).

Pour bannir au pare-feu les adresses insistantes, un filtre fail2ban peut reconnaître Login failure from <HOST> at the dans le journal du conteneur (docker compose logs arca).

Dépannage¶

Symptôme	Cause et solution
Bad Request (400)	Le nom ou l'IP de la barre d'adresse n'est pas dans `ARCA_ALLOWED_HOSTS`.
La vérification CSRF a échoué. La requête a été interrompue. derrière un proxy	Réglez `ARCA_CSRF_TRUSTED_ORIGINS` sur l'origine publique, avec `https://`.
L'intégrité signale la clé secrète (W009)	La clé est trop faible ou a été tronquée : Compose interprète `$` dans `.env`. Générez-la avec `secrets.token_urlsafe(50)`.
L'intégrité signale des migrations non appliquées	Redémarrez le conteneur (il migre au démarrage) ou lancez `manage.py migrate`.
Aide indique que la documentation manque	Installation depuis les sources : lancez `uv run --group docs mkdocs build`, puis `uv run manage.py collectstatic --noinput`.

Format des archives¶

Un fichier .arca-backup contient la ligne ARCA-BACKUP 1, une ligne d'en-tête JSON (date de création, version d'Arca, type, paramètres et sel scrypt, empreinte de la clé, clé publique X25519 éphémère, taille des blocs), puis des blocs de 64 Kio. La clé de secours (24 caractères, casse et tirets ignorés) est étirée par scrypt en clé privée X25519 ; la clé de l'archive est le HKDF-SHA256 du secret partagé X25519, salé par les deux clés publiques, avec l'info arca-backup v1 suivie du SHA-256 de la ligne d'en-tête. Les blocs sont scellés par ChaCha20-Poly1305 avec le nonce compteur de 11 octets gros-boutiste + 1 octet (1 pour le dernier bloc). Le contenu est un tar gzip : manifest.json (effectifs, migrations, SHA-256 de chaque fichier), db.sqlite3 et media/.