Opslag & verzending Beschikbaar
S3-opslag
Waar de bytes van je bestanden staan, kies je één keer bij het uitrollen. Er is geen scherm voor en geen instelling per organisatie: api en worker krijgen dezelfde variabelen mee en dat is het hele verhaal.
Wat je nodig hebt
- Toegang tot de omgevingsvariabelen van je stack (Docker Compose, Portainer of Swarm) en de mogelijkheid om api en worker opnieuw uit te rollen.
- Een S3-compatibele bucket met endpoint, region, bucketnaam en een sleutelpaar. Hetzner Object Storage, MinIO, Scaleway en AWS voldoen.
- Een back-up die de database en het opslagvolume samen pakt; ook na de overstap blijft het volume nodig zolang er nog bestanden op staan.
Zo koppel je het
- 1 Standaard hoef je niets te doen:
SCHAKL_STORAGE_BACKEND=localschrijft naar het named volumestorage-data, aangekoppeld in api en worker opSCHAKL_STORAGE_PATH(standaard/data/storage). - 2 Wil je objectopslag, zet dan op allebei die services
SCHAKL_STORAGE_BACKEND=s3, plusSCHAKL_STORAGE_S3_ENDPOINT,_REGION,_BUCKET,_ACCESS_KEY_IDen_SECRET_ACCESS_KEY. Zet je het maar bij één van de twee, dan blijft de ander naar het volume schrijven. - 3 Optioneel:
SCHAKL_STORAGE_S3_KEY_PREFIXom alles onder één pad te zetten, enSCHAKL_STORAGE_S3_FORCE_PATH_STYLE, dat al optruestaat en daarmee MinIO-vriendelijk is. - 4 Houd de sleutels uit je stackdefinitie met
SCHAKL_STORAGE_S3_ACCESS_KEY_ID_FILEenSCHAKL_STORAGE_S3_SECRET_ACCESS_KEY_FILE, wijzend naar een Docker-secret. Een leeg of onleesbaar bestand weigert de start, met het pad in de melding. - 5 Rol api en worker opnieuw uit en upload één bestand, bijvoorbeeld met Bestand uploaden op een taak. Vanaf dat moment landen nieuwe bestanden in de bucket.
- 6 Laat het volume staan en houd het in je back-up zolang er bestanden zijn die er nog vandaan komen. Welke dat zijn, is te zien aan de
backendenstorage_keydie elke bestandsrij in de API meedraagt.
Dezelfde bytes, één object
Een bestand wordt geadresseerd op de sha256 van zijn eigen inhoud, per organisatie. Een doorgestuurde prijslijst, een opnieuw bijgesneden logo en de handtekeningafbeelding onder elke binnengekomen mail kosten daardoor samen één object in plaats van steeds een nieuwe. De-duplicatie gaat nooit over organisaties heen: de sleutel is organisatie plus backend plus hash, en elk object staat onder de prefix van die ene organisatie. Dat is een bewuste keuze; het opruimen van een organisatie wist die hele prefix, en met gedeelde bytes zou dat de bestanden van een ander meenemen.
Verwijderen geeft niet meteen ruimte terug
Een verwijderd bestand haalt zijn rij weg; de bytes blijven nog even staan. Een onderhoudstaak in de worker draait elke nacht om 03:15 UTC, per organisatie, en doet twee dingen.
- Vouwen: rijen van vóór de de-duplicatie, standaard 500 per organisatie per nacht (SCHAKL_STORAGE_FOLD_BATCH). Een grote installatie is na een paar nachten bij, niet tijdens de upgrade.
- Opruimen: bytes waar geen enkele bestandsrij meer naar wijst, en pas nadat ze SCHAKL_STORAGE_BLOB_GRACE_HOURS (standaard 24 uur) ongebruikt zijn gezien.
- Bijeffect: binnen dat venster is een per ongeluk verwijderd bestand nog te redden zonder een back-up terug te zetten, al is dat handwerk in de database.
Overstappen is geen verhuizing
De backend wordt per bestandsrij vastgelegd, dus s3 aanzetten geldt alleen voor nieuwe uploads. Terugdraaien is even simpel: haal de variabelen weg en nieuwe uploads gaan weer naar het volume. Een bestand waarvan de backend niet bereikbaar is, geeft een expliciete melding over de objectopslag-configuratie in plaats van een leeg bestand.
- Bestaande bestanden blijven van het volume komen, dus het volume blijft nodig.
- Later van bucket of prefix wisselen laat de objecten die er al staan onbereikbaar achter.
- Database en volume horen in dezelfde back-up: een teruggezette database zonder volume levert bestandsrijen zonder inhoud.
Wie erbij kan
Uploaden en verwijderen vraagt het recht files.file.write, standaard bij beheerder en medewerker en niet bij een klantaccount. Een bestand ophalen vraagt geen apart recht: elke ingelogde collega mag de bestanden van de eigen organisatie lezen, maar de rijen zijn tenant-gescoped, het klantbereik van de lezer telt mee, en een klantlogo of een HR-dossierdocument antwoordt 404 in plaats van een 403 die het bestaan zou verraden. Alleen huisstijlbestanden (logo, favicon, app-icoon) zijn zonder inloggen op te halen, want die staan op het inlogscherm; de organisatie wordt daarbij strikt uit de hostnaam bepaald.
Rechten
Geef deze rechten aan de rol die deze koppeling beheert (Instellingen → Rollen). Standaard alleen voor beheerders, en nooit voor de rol client.
-
files.file.writeBestanden uploaden en verwijderen, overal waar de app bestanden accepteert. Standaard bij beheerder en medewerker, niet bij een klantaccount.
Wat het bewust niet doet
- Geen opslagscherm: nergens in de app staat hoeveel ruimte je gebruikt, er is geen quotum per organisatie en geen koppeling met facturatie.
- Geen instelling per organisatie of per klant: de backend geldt voor de hele installatie en wordt in de omgeving van api en worker gekozen.
- Aanzetten verhuist niets. Er is geen migratieknop: bestaande bestanden blijven staan waar ze staan.
- De-duplicatie gaat nooit over organisaties heen. Dat scheelt minder ruimte, maar houdt de scheiding tussen organisaties heel.
- Verwijderen geeft niet meteen ruimte terug: de bytes verdwijnen pas bij de nachtelijke opruiming, minstens een etmaal later.
- Rol je een release terug, verwijder dan geen bestanden tot je weer vooruit hebt gerold. De vorige versie wist het object onvoorwaardelijk en neemt gedeelde kopieën mee.
- Per bestand geldt een harde grens van 10 MB (<code>SCHAKL_UPLOAD_MAX_BYTES</code>) en een vaste lijst met toegestane bestandstypen (<code>SCHAKL_UPLOAD_ALLOWED_TYPES</code>). Allebei horen bij de installatie en niet bij de organisatie: S3 aanzetten verhoogt ze niet.
Waar je het vindt Nergens in de app: dit is een keuze van de beheerder, in de omgevingsvariabelen van api en worker. De bestanden zelf kom je tegen bij Documenten op een project, bijlagen op een taak, het logo van een klant en Instellingen → Huisstijl.
Lees de handleiding