Skip to content
Install

Add S3 storage

To keep database backups off the server and turn on orchard up, add S3-compatible storage. Orchard works with Amazon S3, Cloudflare R2, Backblaze B2, Hetzner Object Storage, MinIO, and any other S3-compatible service.

S3 storage is optional. Database backups work without it on an instance from the one-command installer.

FeatureWith no S3 storageWith S3 storage
Database backups, restores, checkpoints, and copiesOn. Stored on this server.On. Stored in your bucket.
Avatars, icons, and other uploadsOn. Stored on this server.On. Stored in your bucket.
A daily dump of Orchard’s own databaseOn for a new install. Stored on this server.On. Stored on this server.
Cached faviconsOff.On.
orchard upOff.On, if builds can reach the endpoint.

On a Helm install, these features need the store on the server or S3 storage. Neither is on by default.

  • A bucket. Do not name it orchard-backups, because the store on the server uses that name.
  • A key that can list, read, write, and delete in the bucket.
  • The endpoint, region, and addressing style for your provider. For more information, refer to Provider settings.

Keep the bucket private. Orchard serves uploads through its own API, so nothing in the bucket needs to be public.

ProviderEndpointRegionPath-style
Amazon S3https://s3.<region>.amazonaws.comThe bucket’s region, for example eu-west-1false
Cloudflare R2https://<account-id>.r2.cloudflarestorage.comautotrue
Backblaze B2https://s3.<region>.backblazeb2.comThe bucket’s region, for example us-west-004true
Hetzner Object Storagehttps://<location>.your-objectstorage.comThe location, for example fsn1true
MinIOThe address of your serverus-east-1true
Another serviceThe S3 endpoint from your providerThe region from your providertrue, unless your provider requires otherwise

With path-style on, Orchard sends requests to <endpoint>/<bucket>. With path-style off, Orchard sends requests to <bucket>.<endpoint>.

All of these methods save the same settings. You can change the settings later with any of them.

The installer asks one optional question, after the other questions and before it installs anything.

  1. Answer yes to Add S3-compatible storage for off-server backups and uploads?
  2. Select your provider. The installer fills in the endpoint and the addressing style.
  3. Enter the region, the bucket, the access key, and the secret key.

The installer tests the connection before it continues. If the test fails, you can try again or skip S3 storage. A failed test never stops the install.

Pass the settings as flags or environment variables. To skip the question, pass --no-s3.

export ORCHARD_S3_SECRET_KEY='<secret key>'
sudo --preserve-env=ORCHARD_S3_SECRET_KEY ./install.sh --yes \
--mode public --domain orchard.example.com --email [email protected] \
--s3-endpoint https://s3.eu-west-1.amazonaws.com \
--s3-bucket my-orchard-bucket \
--s3-region eu-west-1 \
--s3-access-key <access key> \
--no-s3-path-style
FlagEnvironment variableDescription
--s3-endpointORCHARD_S3_ENDPOINTThe endpoint.
--s3-bucketORCHARD_S3_BUCKETThe bucket.
--s3-regionORCHARD_S3_REGIONThe region. The default is auto.
--s3-access-keyORCHARD_S3_ACCESS_KEYThe access key.
--s3-secret-key-fileORCHARD_S3_SECRET_KEY_FILEA file that holds the secret key.
NoneORCHARD_S3_SECRET_KEYThe secret key.
--s3-secret-keyNoneThe secret key. This flag stays in your shell history, so use one of the two options above.
--s3-path-styleORCHARD_S3_PATH_STYLE=trueUse path-style requests. This is the default.
--no-s3-path-styleORCHARD_S3_PATH_STYLE=falseSend requests to <bucket>.<endpoint>.
--no-s3ORCHARD_S3=falseSkip S3 storage.

If the test fails, the installer prints the reason and continues without S3 storage.

After you claim a new instance, the setup flow shows a Storage step. Orchard skips this step if storage is already set.

  1. Select your provider, and enter the region, the bucket, the access key, and the secret key.
  2. Select Test connection.
  3. Select Save and continue. To add storage later, select Skip for now.
  1. Go to Instance admin > Configuration > Object storage.
  2. Select your provider to fill in the endpoint, region, and addressing style.
  3. Enter the access key, the secret key, and a backup bucket and uploads bucket. These can be the same bucket.
  4. Select Test connection.
  5. Select Save.

Orchard never shows a saved key again. To keep a saved key, leave its field empty.

On the host, run:

sudo orchardctl backups s3 set \
--endpoint https://s3.eu-west-1.amazonaws.com \
--bucket my-orchard-bucket \
--region eu-west-1 \
--path-style false \
--access-key <access key>

The command asks for the secret key, tests the connection, and saves the settings only if the test passes. It also reads the secret key from --secret-key-file or ORCHARD_S3_SECRET_KEY. For the other commands, refer to backups s3.

A change applies to new databases.

  • New databases back up to the new bucket.
  • Databases you already have keep backing up to where they are now. Their existing backups stay restorable from there.
  • Other features use the new bucket as soon as the server reads the setting, within 30 seconds.

Keep the old location available. Orchard keeps its connection details so these databases can keep backing up and restoring. If you delete the old bucket or its key, those databases lose their backups.

To move an existing database to the new storage, create a copy of it. For more information, refer to Back up and restore a database. The copy backs up to the new bucket. The original database and its backups stay where they are until you delete them.

Uploads that you already added stay in the old location. Upload them again to move them.

orchard up turns on when you save S3 storage. It needs no other setting. Orchard stores each uploaded directory in your bucket under build-contexts/.

Build pods download the directory, and their network policy only lets them reach public addresses on ports 80 and 443. If your endpoint is inside the cluster, on a private address, or on another port, orchard up stays off.

To turn it off, set LOCAL_DEPLOYS_ENABLED to false. For more information, refer to Deploy from your terminal.

Builds fetch the uploaded files from your storage endpoint. If that endpoint is on the same server behind its own ingress, the installer allows builds to reach Traefik, except in tunnel mode, where builds reach the endpoint through Cloudflare instead. With Helm, add your ingress controller’s pods to builders.registryEgress. For more information, refer to Troubleshooting.

Orchard serves uploads through its API by default. To serve them from your own domain or a CDN instead:

  1. Create a separate public bucket for uploads. Do not make your backup bucket public.
  2. Go to Instance admin > Configuration > Object storage.
  3. Set Uploads bucket to the public bucket.
  4. Set Public base URL to the address of the bucket.
  5. Select Save.

Orchard refuses a public URL if uploads and backups share a bucket.

The Helm chart runs the backup proxy but leaves the store on the server off. Choose one of these options.

To keep backups and uploads on the server, add the following to your chart values:

objectStorage:
local:
enabled: true
storage:
size: 20Gi

To add S3 storage, use the setup flow or Instance admin. You do not need to change the chart values.

To manage storage from your values file, set the R2_* environment variables on the server. The names are historical and work with every provider.

VariableDescription
R2_ENDPOINTThe endpoint.
R2_REGIONThe region. The default is auto.
R2_PATH_STYLEtrue or false.
R2_ACCESS_KEY_IDThe access key.
R2_SECRET_ACCESS_KEYThe secret key.
R2_BACKUP_BUCKETThe bucket for backups.
R2_BUCKET_NAMEThe bucket for uploads.
R2_PUBLIC_URLOptional. A public address for uploads.

These variables take priority over saved settings, and they lock the matching fields in the dashboard. orchard up stays off until you also set LOCAL_DEPLOYS_ENABLED=true and R2_BUILD_CONTEXT_BUCKET.

  • Orchard encrypts saved keys, and it never returns them through the API or writes them to logs.
  • Each database gets a key that only reaches its own backups. A backup proxy holds the real key in its own namespace.
  • The proxy signs requests with the real key only for the buckets you configured. A bucket name an organization saves in its settings never adds to that list. If you set r2Proxy.upstream.endpoint in your chart values, also set r2Proxy.defaultBucket or r2Proxy.allowedBuckets. An empty list never means every bucket: the chart does not render and the proxy does not start.
  • If you turn the proxy off with r2Proxy.enabled=false, keys saved in Orchard do not reach databases, so those databases have no backups. Keys from R2_* variables do reach databases, and anyone who can read a Secret in that namespace can read every database’s backups.
  1. On the host, run sudo orchardctl backups s3 status, or go to Instance admin > Configuration > Object storage.
  2. Create a database.
  3. Take a backup, then run a restore test. For more information, refer to Back up and restore a database.