Backups to S3-compatible storage

Lunedo can write its backups to a bucket in Amazon S3, Google Cloud Storage, MinIO, Cloudflare R2 or another S3-compatible service. Set the target under Settings › Instance › Operations › Backups, section Target, with Where backups are written set to S3-compatible storage. The other backup settings are described in Backups.

Settings

Field	Description
Endpoint	Address of the service, starting with https://, without a path, for example https://s3.example.com. Leave it empty for Amazon S3.
Region	The region of the bucket, for example eu-central-1. Cloudflare R2 uses auto.
Bucket	The bucket name: 3 to 63 lowercase letters, digits, dots, hyphens or underscores. The bucket must exist.
Prefix	Optional folder for the backups, ending with a slash, for example lunedo/.
Access key	The key needs permission to write, read, list and delete objects.
Secret key	Stored encrypted with the master key and never shown again.
Address the bucket in the path	Needed by MinIO and some other services.

When a secret key is stored, leave the field empty to keep it, or enter a new one to replace it. Changing the endpoint, the region, the bucket or the access key requires the secret key again, so a stored key is never sent to another service. Switching to a directory target removes the stored secret key.

Test connection writes, reads, lists and deletes a small test object with the entered settings, without saving them. A failure names the step (writing, reading, listing or deleting) and the cause: a host name that cannot be resolved, a refused private address, an endpoint without HTTPS, a connection that fails, an untrusted TLS certificate, keys that are not accepted, a key without the needed permission, a bucket that does not exist or is in another region, or a service that refuses the request. Save target saves the settings.

How backups are written

Backups are streamed to the bucket in parts of 8 MiB and are never held in memory. An upload that fails is aborted. Before each backup, Lunedo aborts the unfinished uploads of its own earlier runs, which its run records list; uploads of any other instance that writes to the same bucket are never touched. The database dump is staged on the local disk of the worker while the backup runs (see Free space before a backup).

Keep the backups on another disk or host than the file store. A storage service on the same disk does not protect against losing it.

Services

Service	Endpoint	Region	Path-style	Keys
Amazon S3	empty	the bucket’s region, for example eu-central-1	off	an IAM access key with s3:PutObject, s3:GetObject, s3:ListBucket, s3:DeleteObject, s3:AbortMultipartUpload and s3:ListBucketMultipartUploads
Google Cloud Storage	https://storage.googleapis.com	auto or the bucket’s location	off	an HMAC key of a service account (Cloud Storage › Settings › Interoperability) with the Storage Object Admin role on the bucket
MinIO	the MinIO address, for example https://minio.example.com	us-east-1 unless MinIO is set to another one	on	a MinIO access key with read and write access to the bucket
Cloudflare R2	https://<account id>.r2.cloudflarestorage.com, for a bucket in a jurisdiction https://<account id>.<jurisdiction>.r2.cloudflarestorage.com with eu, us or fedramp; such a bucket is only reachable through the endpoint of its jurisdiction	auto	off	an R2 API token with Object Read & Write, limited to the bucket (R2 overview, Manage next to API Tokens)

Note

The MinIO repository was archived in April 2026 and is no longer maintained. Its community edition is only published as source code, without new binaries. For a new installation, choose another S3-compatible service.

Endpoints in private networks

The S3 client follows the same outbound rules as chat channels: private, loopback and link-local addresses are refused unless they are listed in LUNEDO_OUTBOUND_ALLOWED_NETWORKS, and public endpoints need HTTPS. Addresses in allowed networks may use http://. Lunedo checks the address a host name resolves to, so a host name that points into a private network is refused as well.

When a private endpoint is refused, Test connection names the address the endpoint resolved to and the entry to add, for example 172.18.0.7/32, and asks you to restart Lunedo after adding it.

A storage service on the same Docker network

A storage service in the same Compose project, such as SeaweedFS, Garage or MinIO, has an address in a private network, which Lunedo refuses until it is allowed. Allow only the address of the storage service, never a whole subnet: LUNEDO_OUTBOUND_ALLOWED_NETWORKS also applies to chat channels, which space administrators set up, to Confluence Cloud imports and to the update check. A subnet that contains PostgreSQL or other containers of the installation would let them probe those services through a chat channel test. Put the storage service on a network of its own with a fixed address, keep Lunedo on the default network as well (PostgreSQL is there), and give the storage service credentials, so that other containers cannot write to it without a key:

yaml

services:
  lunedo:
    environment:
      LUNEDO_OUTBOUND_ALLOWED_NETWORKS: 172.30.1.10/32
    networks: [default, storage]
  storage:
    image: chrislusf/seaweedfs:4.48
    restart: unless-stopped
    environment:
      AWS_ACCESS_KEY_ID: ${STORAGE_ACCESS_KEY:?Set STORAGE_ACCESS_KEY in .env}
      AWS_SECRET_ACCESS_KEY: ${STORAGE_SECRET_KEY:?Set STORAGE_SECRET_KEY in .env}
    volumes:
      - storage:/data
    networks:
      storage:
        ipv4_address: 172.30.1.10

networks:
  storage:
    ipam:
      config:
        - subnet: 172.30.1.0/28

volumes:
  storage:

Add STORAGE_ACCESS_KEY and a long random STORAGE_SECRET_KEY to .env (for example head -c 32 /dev/urandom | base64), and enter the same two values as access key and secret key of the target. Choose a subnet that no other network on the host uses; 172.30.1.0/28 does not overlap the default network of the setup script (172.30.0.0/24). scripts/backup-network-check.sh starts this example together with the Compose file of the setup script and checks that the allowed address is only the storage service and that the storage service refuses requests without a key.

Use http://172.30.1.10:8333 as endpoint, with Address the bucket in the path on. The host name storage works as well, because Lunedo checks the address a name resolves to.

Restoring from a bucket

backup verify and backup restore read local files only. To restore a backup from a bucket on the command line, download it first; see Fetching a backup from S3. A new, empty instance can also restore directly from a bucket in the setup assistant; see Restore during the setup assistant.