# Stockages

> AWS S3, Cloudflare R2, MinIO, Scaleway, Wasabi : le point d’accès est la seule différence. Les réglages de chacun pour la page de livraison, la CLI et la bibliothèque.

Canonical: https://colis-docs.vercel.app/docs/stockages · Markdown: https://colis-docs.vercel.app/docs/stockages.md

colis parle S3. Tout stockage compatible convient ; le point d’accès (`endpoint`) est la seule
différence. Quand il est défini, deux valeurs par défaut suivent :

- `region` devient `"auto"`, la convention des fournisseurs qui ignorent la région mais dont le SDK en
  exige une ;
- `forcePathStyle` devient `true` : `https://endpoint/bucket/key` plutôt que
  `https://bucket.endpoint/key`. Les passerelles auto-hébergées l’exigent, les fournisseurs gérés
  l’acceptent.

Les deux restent modifiables. Dans chaque cas, donnez aux clés la lecture et l’écriture sur ce seul
bucket, rien d’autre : des clés capables de lister le bucket permettraient d’énumérer les codes.

## Cloudflare R2

Pas de frais de sortie, ce qui compte quand vos clients téléchargent des fichiers lourds. Créez le
bucket (**R2 → Create bucket**) et un jeton d’API **Object Read & Write** limité à ce bucket. L’identifiant
de compte est le début du point d’accès S3 que R2 affiche.

Pour la [page de livraison](https://colis-docs.vercel.app/docs/page-de-livraison) :

```sh
COLIS_BUCKET=livraisons
COLIS_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
COLIS_REGION=auto
AWS_ACCESS_KEY_ID=…
AWS_SECRET_ACCESS_KEY=…
```

Pour la CLI en mode bucket, `colis init --provider r2 --bucket livraisons` écrit le même réglage, avec
les secrets lus depuis `.env` (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`).

Dans votre code :

```ts
import { createBucket } from '@colis/core'

const store = createBucket({
  bucket: 'livraisons',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  },
})
```

Les règles de cycle de vie et CORS se règlent dans **R2 → votre bucket → Settings**. R2 abandonne de
lui-même les envois multipart incomplets après sept jours.

## AWS S3

Laissez `COLIS_ENDPOINT` vide et donnez une vraie région (`COLIS_REGION=eu-west-3`). Sans clés
explicites, la chaîne d’identifiants d’AWS s’applique : variables `AWS_*`, profil partagé, rôle
d’instance. Sur un hébergement qui fournit un rôle, préférez-le : rien à faire tourner, rien à fuiter.

La politique minimale pour le préfixe des colis :

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::livraisons/*"
    }
  ]
}
```

Les deux dernières actions ne servent qu’aux [gros fichiers](https://colis-docs.vercel.app/docs/gros-fichiers). Signer une URL ne
demande aucune permission de plus : c’est un calcul local sur les clés que vous détenez déjà.

`colis verifier` en mode bucket appelle aussi `HeadBucket`, qu’AWS autorise avec `s3:ListBucket` sur
le bucket lui-même, et lit les règles de cycle de vie et CORS. Avec la politique ci-dessus, ces
contrôles échouent ou avertissent alors que la page de livraison fonctionne : vérifiez plutôt le
déploiement avec `colis verifier --remote`.

## MinIO

Le moyen le plus rapide d’essayer le vrai chemin de code, sans compte :

```sh
docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin \
  quay.io/minio/minio server /data --console-address ":9001"
```

Créez le bucket depuis la console sur [localhost:9001](http://localhost:9001), puis
`COLIS_ENDPOINT=http://localhost:9000` avec `minioadmin` / `minioadmin` comme clés.
`colis init --provider minio` écrit le même réglage pour la CLI.

## Scaleway Object Storage

Scaleway utilise vraiment la région : donnez-la plutôt que de laisser `"auto"`.

```sh
COLIS_ENDPOINT=https://s3.fr-par.scw.cloud
COLIS_REGION=fr-par
```

`colis init --provider scaleway` lit les clés dans `SCW_ACCESS_KEY` et `SCW_SECRET_KEY`.

## Wasabi

```sh
COLIS_ENDPOINT=https://s3.eu-central-1.wasabisys.com
COLIS_REGION=eu-central-1
```

`colis init --provider wasabi` lit les clés dans `WASABI_ACCESS_KEY` et `WASABI_SECRET_KEY`.

## À propos des ACL

`upload()` accepte une option `acl`, mais la plupart des buckets récents ont les ACL désactivées, et
R2 ne les prend pas en charge : l’option fait alors échouer la requête. colis n’a pas besoin d’objets
publics ; laissez `acl` de côté.

## Vérifier

Quel que soit le fournisseur, `colis verifier` en mode bucket effectue les opérations dont colis a
besoin et signale la règle de cycle de vie ou la règle CORS manquante. Voir [CLI](https://colis-docs.vercel.app/docs/cli#verifier).