immich-archiver: je fotobibliotheek spiegelen naar je eigen schijf
PixelUnion bewaart je foto’s op Europese servers, met redundantie en monitoring. Dat is ons werk, en we nemen het serieus.
Het standaardadvies voor data die je belangrijk vindt is de 3-2-1-regel: drie kopieën, op twee verschillende soorten opslag, met één kopie op een andere locatie. Onze kant daarvan is geregeld. We beschermen tegen rampen, niet alleen tegen een schijf die het begeeft, en daar kun je op rekenen. Wat we niet kunnen zijn, is een kopie die bij jou thuis staat, op hardware die van jou is, leesbaar zonder account en zonder ons. Genoeg mensen willen dat er ook bij hebben, en dat is een redelijke wens.
Daarom hebben we immich-archiver gebouwd, een open-source tool die een Immich-bibliotheek spiegelt naar een map op een schijf die van jou is.
Wat het doet
Je geeft het een server-URL en een gebruikers-API-sleutel (een application programming interface-sleutel, die je aanmaakt in je accountinstellingen), plus een doelmap. Het downloadt elke foto en video in je tijdlijn naar mappen per jaar en maand.
| |
Het resultaat op schijf:
/path/to/archive/2005/2005-06/IMG_0001.jpg
/path/to/archive/2005/2005-06/IMG_0001.jpg.json
Elk bestand krijgt er een sidecar-bestand naast in JSON (JavaScript Object Notation, een tekstformaat dat elke tool kan lezen) met het volledige metadatarecord dat de server voor dat bestand heeft: opnamedatum, cameramerk en -model, GPS-coördinaten, albumlidmaatschap, gezichten, waarderingen. We slaan de ruwe API-respons letterlijk op in plaats van een geselecteerde subset, want op het moment dat je bepaalt welke velden ertoe doen, gok je naar een toekomst die je niet kunt zien. De aanpak is geleend van immich-go, dat dit al jaren goed doet.
Draai het later opnieuw en het downloadt alleen wat ontbreekt. Er is geen state-database. Het controleert het bestandssysteem, en het gebruikt de sidecar om te bevestigen dat een bestand met een overeenkomende naam ook echt hetzelfde item is, en niet een ongerelateerde foto die toevallig dezelfde bestandsnaam heeft.
Dat ontwerp heeft een reële prijs, en die is het benoemen waard. Omdat er geen index is, doet elke run een stat-aanroep op elk doelbestand, wat bij zeer grote bibliotheken over een netwerkbestandssysteem trager is dan het lezen van een lokale database. Hernoem een gedownload bestand en de tool haalt het opnieuw op, omdat hij het niet meer herkent. Wat je ervoor terugkrijgt is dat de map de bron van waarheid is. Er is geen aparte index die corrupt kan raken, uit de pas kan gaan lopen, of aan je uitgelegd moet worden wanneer hij het oneens is met de werkelijkheid.
Nog een paar details die het weten waard zijn. Downloads worden geschreven naar een tijdelijk .part-bestand en pas na een voltooide overdracht op hun plek hernoemd, zodat een onderbroken run nooit een afgekapt bestand achterlaat dat een latere run voor voltooid aanziet. Live Photos komen binnen als beide componenten, de foto en de bewegende clip, met dezelfde basisbestandsnaam. Albums die met jou gedeeld zijn worden standaard overgeslagen en belanden in een aparte map als je --include-shared meegeeft. Concurrency en het aantal retries zijn instelbaar, met standaard vier parallelle downloads en drie retries bij netwerk- of serverfouten.
Waarom het bestaat, en wat het niet is
De vraag achter deze tool krijgen we regelmatig: als PixelUnion zou verdwijnen, wat gebeurt er dan met mijn foto’s? Het eerlijke antwoord was altijd “exporteer ze”, en dat is geen antwoord wanneer de exportroute betekent dat je tienduizend bestanden via een browser downloadt, album voor album. Een back-up die afhangt van of jij eraan denkt om een vervelende handmatige taak uit te voeren, is geen back-up. Het is een taak die je gaat overslaan.
Dit is een command-line interface-tool, meestal afgekort tot CLI. Je hebt een terminal nodig, een API-sleutel, en genoeg vertrouwdheid met allebei om het in een cronjob of geplande taak te zetten. Dat sluit een hoop mensen uit, en we gaan niet doen alsof dat niet zo is.
Waar we willen uitkomen is een downloadknop in PixelUnion zelf. Je klikt erop, wij maken een archief klaar, je krijgt een link, alles komt binnen in één bestand. Dichter bij wat Google Takeout doet, zonder het deel waarin het een week duurt en incompleet aankomt. Dat is een aanzienlijk groter stuk werk, het staat op de roadmap, en het komt deze maand niet uit.
Dus hebben we een afweging gemaakt, en het is de voor de hand liggende: lever nu de tool die werkt voor de mensen die hem kunnen gebruiken, in plaats van niemand te dekken terwijl de vriendelijkere versie gebouwd wordt. immich-archiver is de tussenstap. Ben je thuis in een terminal, dan hoef je niet te wachten.
Waar je het vindt
De repository staat op github.com/pixelunioneu/immich-archiver, onder de AGPL-3.0 (de GNU Affero General Public License, versie 3). Elke release levert kant-en-klare binaries voor Linux, Windows en macOS, op zowel x86-64 als ARM64, zodat Apple Silicon-Macs een native build krijgen in plaats van een vertaalde.
De macOS-binaries zijn ondertekend met een Developer ID-certificaat en genotariseerd bij Apple, waardoor Gatekeeper ze laat draaien zonder de waarschuwing over een onbekende ontwikkelaar. Dat is belangrijker dan het klinkt: de gebruikelijke workaround voor niet-ondertekende tools is gebruikers vertellen de quarantainevlag van een gedownloade binary te halen, en dat leert mensen precies de controle te omzeilen die hen beschermt. De nieuwste release is altijd degene die je wilt hebben.
Dit is een eerste release. De kern is degelijk en getest, maar heeft nog niet de verscheidenheid aan bibliotheken gezien die echte gebruikers hebben, en dat is waar dit soort tools meestal breekt. Issues en pull requests zijn welkom, vooral die die beginnen met “dit deed iets vreemds met mijn…”.
Nog één afsluitende gedachte, want die geldt ver buiten deze tool. Een back-up waarvan je nooit hebt teruggezet is geen back-up, het is een hypothese. Draai hem één keer, open de map, controleer of een foto daadwerkelijk opent. Zet hem daarna in de planning en denk er niet meer aan.