# Présentation des buckets Les buckets sont des conteneurs nommés pour les fichiers téléversés. Chaque bucket porte sa propre limite de taille, ses types MIME autorisés, sa visibilité publique/privée et ses permissions d'accès. Les tables référencent les buckets via des [champs de pièce jointe](/fr/docs/attachment-fields), les [formulaires](/fr/docs/form-file-uploads) y écrivent des fichiers, et l'API REST expose des points de terminaison de téléversement, de téléchargement, d'URL signée et de transformation d'image. Deux préoccupations sont délibérément séparées : - **Où les fichiers sont stockés** — le _backend_ de stockage — est contrôlé par l'opérateur via des variables d'environnement (`STORAGE_PROVIDER` et consorts). Il n'apparaît jamais dans le schéma de l'application. - **Comment les fichiers sont organisés** — les _buckets_ — est une configuration d'application déclarée dans le tableau de premier niveau `buckets[]` de votre configuration. ```yaml buckets: - name: avatars public: true maxFileSize: 2097152 allowedMimeTypes: [image/jpeg, image/png, image/webp] permissions: upload: authenticated download: all delete: [admin] ``` Lorsque `buckets` est entièrement omis, Sovrium provisionne un bucket `default` implicite (`public: false`, permissions par défaut standard). ## Backends de stockage Le backend est choisi au moment du déploiement avec `STORAGE_PROVIDER`. Les trois backends prennent en charge l'intégralité de la surface des opérations de fichiers, des URL signées et des transformations d'image. | Backend | `STORAGE_PROVIDER` | Idéal pour | Évolutivité | URL présignées natives | | ------------------------- | -------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------ | | Système de fichiers local | `local` (par défaut) | Développement, mononœud, auto-hébergé | Limité par le disque | Non (Sovrium signe en interne) | | S3 / compatible S3 | `s3` | Production, scale-out | Illimité | Oui (délégué au fournisseur) | | MinIO | `s3` + `STORAGE_FORCE_PATH_STYLE=true` | Magasin d'objets compatible S3 auto-hébergé | Illimité | Oui | | PostgreSQL `bytea` | `bytea` | Petits fichiers, déploiements mono-base simples | Limité par la base | Non (Sovrium signe en interne) | :::callout **Frugal par défaut.** Le backend par défaut est `local` — zéro dépendance externe, reflétant la posture de base de données SQLite par défaut de Sovrium. N'optez _pour_ S3 que lorsque vous avez besoin de scale-out ou de déploiements multinœuds. Voir [Écoconception](/fr/docs/ecoconception). ::: ### Variables d'environnement du backend | Variable | Requis | Par défaut | Objectif | | -------------------------- | ------- | ----------- | ------------------------------------------------------------------------------- | | `STORAGE_PROVIDER` | Non | `local` | Backend de stockage : `s3`, `local` ou `bytea`. | | `STORAGE_ENDPOINT` | S3 seul | — | URL du point de terminaison compatible S3. | | `STORAGE_BUCKET` | S3 seul | — | Nom du bucket S3 sous-jacent (le magasin d'objets hôte, pas un bucket Sovrium). | | `STORAGE_REGION` | S3 seul | `us-east-1` | Région AWS. | | `STORAGE_ACCESS_KEY` | S3 seul | — | ID de clé d'accès S3. | | `STORAGE_SECRET_KEY` | S3 seul | — | Clé d'accès secrète S3. | | `STORAGE_FORCE_PATH_STYLE` | Non | `false` | Utiliser des URL de style chemin (requis pour MinIO). | :::callout **Les buckets Sovrium sont des préfixes de chemin, pas des buckets S3.** Chaque bucket que vous déclarez dans `buckets[]` correspond à un préfixe de chemin à l'intérieur du bucket hôte unique configuré par `STORAGE_BUCKET` (par ex. `avatars/`, `documents/`). Un seul bucket S3 contient tous vos buckets Sovrium. ::: Voir [Variables d'environnement](/fr/docs/env-vars) pour la référence complète des variables côté opérateur. ## Propriétés du bucket Chaque entrée du tableau `buckets[]` accepte les propriétés suivantes. | Propriété | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | Nom de bucket unique. Minuscules, alphanumérique, traits d'union ; doit commencer par une lettre ; 63 caractères max (compatibilité de préfixe S3). Utilisé comme préfixe de chemin de stockage. | | `public` | Booléen. Lorsque `true`, les fichiers sont servis sans URL signées. Vaut `false` par défaut (privé). | | `maxFileSize` | Taille maximale de fichier en octets pour les téléversements vers ce bucket. Surcharge le `STORAGE_MAX_FILE_SIZE` global. Doit être ≥ 1. | | `allowedMimeTypes` | Tableau des types MIME autorisés pour les téléversements. Prend en charge les caractères génériques (par ex. `image/*`). Lorsqu'il est omis, tous les types sont acceptés. Minimum une entrée. | | `permissions` | Contrôle d'accès par opération. Voir [Permissions](#permissions) ci-dessous. | :::callout **La validation du nom est stricte.** `Avatars` (majuscule) et `123-bucket` (chiffre en tête) sont rejetés par `sovrium validate`. Exemples valides : `avatars`, `documents`, `public-assets`, `user-uploads`. Les noms en double dans le tableau sont également rejetés au moment de la validation. ::: ## Permissions Les permissions de bucket utilisent le même format partagé `PermissionValueSchema` que les [permissions de table](/fr/docs/table-permissions) : chaque opération accepte `all`, `authenticated`, ou une liste de noms de rôles. | Opération | Description | Par défaut | | ------------ | --------------------------------------------------- | ----------------------------------------- | | `upload` | Qui peut téléverser des fichiers vers ce bucket. | `authenticated` | | `download` | Qui peut télécharger des fichiers depuis ce bucket. | `all` si public, `authenticated` si privé | | `sign` | Qui peut générer des URL de téléchargement signées. | `authenticated` | | `signUpload` | Qui peut générer des URL de téléversement signées. | `[admin]` | | `delete` | Qui peut supprimer des fichiers de ce bucket. | `[admin]` | Valeurs de permission : - `all` — tout le monde, y compris les requêtes non authentifiées. - `authenticated` — tout utilisateur connecté. - `['admin', 'editor']` — uniquement les rôles listés. ```yaml buckets: - name: documents maxFileSize: 52428800 allowedMimeTypes: [application/pdf, text/csv] permissions: upload: [admin, editor] download: authenticated sign: authenticated signUpload: [admin, editor] delete: [admin] ``` Lorsqu'un bucket omet entièrement `permissions`, les valeurs par défaut par opération ci-dessus s'appliquent — notamment, seul le rôle `admin` peut générer des URL signées. ## Public vs privé | Visibilité | Comportement | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `public: true` | Fichiers servis directement sans authentification ni URL signées. Convient aux avatars, logos, ressources marketing. | | `public: false` (par défaut) | Les fichiers requièrent soit une authentification (correspondant à la permission `download`) soit une [URL signée](/fr/docs/signed-urls) valide. | Les opérateurs peuvent en outre exposer des préfixes de chemin globalement via `STORAGE_PUBLIC_PATHS` (voir [URL signées](/fr/docs/signed-urls)). ## Exemple : buckets multiples Un bucket d'images public aux côtés d'un bucket de documents privé, restreint par rôle. ```yaml buckets: - name: avatars public: true maxFileSize: 2097152 allowedMimeTypes: [image/*] permissions: upload: authenticated download: all delete: [admin] - name: documents maxFileSize: 52428800 allowedMimeTypes: [application/pdf] permissions: upload: [admin, editor] download: authenticated sign: authenticated signUpload: [admin, editor] delete: [admin] ``` ## Pages associées - [Opérations sur les fichiers](/fr/docs/file-operations) — points de terminaison de téléversement, téléchargement, liste et suppression. - [URL signées](/fr/docs/signed-urls) — accès limité dans le temps aux fichiers privés. - [Transformations d'image](/fr/docs/image-transforms) — redimensionnement, recadrage et conversion de format à la volée. - [Champs de pièce jointe](/fr/docs/attachment-fields) — stocker des fichiers sur des enregistrements de table. - [Téléversements de fichiers de formulaire](/fr/docs/form-file-uploads) — accepter des fichiers via des formulaires. - [Variables d'environnement](/fr/docs/env-vars) — configuration du backend côté opérateur.