# Backends de stockage

Un [bucket](/fr/docs/buckets-overview) dit comment les fichiers sont organisés. Le backend dit où leurs octets aboutissent. C'est une décision d'opérateur, prise entièrement par variables d'environnement, et elle n'apparaît jamais dans le schéma — le même fichier de configuration tourne sur disque local en développement et sur S3 en production.

Les trois backends prennent en charge toute la surface : téléversement, téléchargement, suppression, [URL signées](/fr/docs/signed-urls) et [transformations d'image](/fr/docs/image-transforms).

| Backend                   | `STORAGE_PROVIDER`                        | Idéal pour                                          | Échelle              |
| ------------------------- | ----------------------------------------- | --------------------------------------------------- | -------------------- |
| Système de fichiers local | `local`                                   | Développement, mononœud, auto-hébergé               | Limité par le disque |
| S3 / compatible S3        | `s3`                                      | Production, multinœud                               | Illimité             |
| MinIO, R2, Scaleway       | `s3` + `STORAGE_S3_FORCE_PATH_STYLE=true` | Stockages objet auto-hébergés ou non-AWS            | Illimité             |
| PostgreSQL `bytea`        | `bytea`                                   | Petits fichiers, déploiement mono-base, sans disque | Limité par la base   |

## Choisir un backend

`STORAGE_PROVIDER` n'est pas obligatoire. Laissée vide, la variable fait suivre au backend le dialecte de base de données :

| `STORAGE_PROVIDER` | `DATABASE_URL`      | Backend obtenu                                                                    |
| ------------------ | ------------------- | --------------------------------------------------------------------------------- |
| `s3`               | indifférent         | S3. Les cinq identifiants `STORAGE_S3_*` sont requis.                             |
| `local`            | indifférent         | Système de fichiers local. `STORAGE_LOCAL_DIRECTORY` est **requis** — sans repli. |
| non défini         | défini (Postgres)   | `bytea` — les octets vont dans la base que vous exploitez déjà.                   |
| non défini         | non défini (SQLite) | Système de fichiers local sous `<répertoire de données>/storage`.                 |

Les deux dernières lignes constituent le chemin zéro-configuration, et elles reflètent la posture « SQLite par défaut » : rien d'externe à provisionner, aucun identifiant à gérer. Notez l'asymétrie — un `STORAGE_PROVIDER=local` _explicite_ échoue au démarrage sans `STORAGE_LOCAL_DIRECTORY`, alors qu'un local _implicite_ choisit le répertoire par défaut pour vous. La forme explicite est traitée comme une affirmation délibérée sur l'emplacement : un répertoire manquant y devient une erreur qui mérite d'être signalée.

```bash
# Zéro configuration : rien de défini, base SQLite → fichiers locaux sous le répertoire de données
# Local explicite
STORAGE_PROVIDER=local
STORAGE_LOCAL_DIRECTORY=/var/lib/sovrium/uploads
```

```bash
# Compatible S3 (MinIO ici — retirez l'option path-style pour AWS)
STORAGE_PROVIDER=s3
STORAGE_S3_ENDPOINT=https://minio.example.com
STORAGE_S3_BUCKET=my-app-files
STORAGE_S3_REGION=eu-west-1
STORAGE_S3_ACCESS_KEY_ID=...
STORAGE_S3_SECRET_ACCESS_KEY=...
STORAGE_S3_FORCE_PATH_STYLE=true
```

:::callout
**Vos buckets sont des préfixes dans un unique bucket hôte.** Chaque bucket déclaré dans `buckets[]` devient un préfixe de chemin (`avatars/`, `documents/`) à l'intérieur de l'unique bucket de stockage objet nommé par `STORAGE_S3_BUCKET`. Vous ne créez pas un bucket S3 par bucket Sovrium, et vous n'avez même pas besoin du droit d'en créer.
:::

:::callout
**Les noms `S3_*` nus sont dépréciés.** `S3_ENDPOINT`, `S3_BUCKET` et les autres sont encore lus comme alias et émettent un avertissement unique au démarrage. Renommez-les en `STORAGE_S3_*` ; l'ancienne graphie disparaîtra à la prochaine version majeure.
:::

## La signature selon le backend

S3 expose une présignature native : les URL signées sur ce backend sont donc déléguées au fournisseur. Local et `bytea` n'offrent pas cette primitive, aussi Sovrium signe et vérifie lui-même des jetons HMAC sur sa propre route `/signed`. La différence est invisible pour les appelants : la même requête produit la même forme d'URL sur les trois backends, et une URL émise sur l'un n'est jamais transposable à un autre.

## Pages associées

- [Présentation des buckets](/fr/docs/buckets-overview) — les buckets posés sur un backend.
- [Permissions de bucket](/fr/docs/buckets-permissions) — qui peut lire et écrire.
- [Opérations sur les fichiers](/fr/docs/file-operations) — les points de terminaison servis par tous les backends.
- [URL signées](/fr/docs/signed-urls) — présignées sur S3, signées en HMAC ailleurs.
- [Variables d'environnement : services](/fr/docs/env-vars-services) — la référence complète `STORAGE_*`.
- [Écoconception](/fr/docs/ecoconception) — pourquoi le défaut sans dépendance est le défaut.