S3 storage
Uploaded files (attachments, voice messages and avatars) are kept in the server's data directory by default. With an S3 bucket configured, the server stores them there instead. It still serves them to the apps itself, so the bucket does not need to be reachable from the internet, and access works as before: a file can be downloaded by anyone with its link. The database keeps file names and sizes; only the contents move to the bucket.
The server's tolktak-server listening log line shows files=s3 or files=disk.
Garage in the Compose setup
The Compose setup runs Garage, a lightweight S3 server, with a bucket named tolktak. There is nothing to configure: the keys come from .env. The files are kept in the garage-data volume and Garage's metadata in garage-meta. Garage is reachable only by the other services of the setup.
A provider's S3
Create a bucket and an access key that can read and write objects in it, then set:
| Variable | Example | Description |
|---|---|---|
TOLKTAK_S3_BUCKET |
tolktak |
Bucket name. Setting it turns S3 storage on. |
TOLKTAK_S3_ENDPOINT |
https://<account id>.r2.cloudflarestorage.com |
The provider's S3 address. Leave it empty for AWS S3. http:// is accepted for a server on a private network. |
TOLKTAK_S3_REGION |
auto |
The bucket's region. us-east-1 if empty. |
TOLKTAK_S3_ACCESS_KEY, TOLKTAK_S3_SECRET_KEY |
The access key. Both are required with a bucket. |
| Provider | TOLKTAK_S3_ENDPOINT |
TOLKTAK_S3_REGION |
|---|---|---|
| AWS S3 | empty | the bucket's region, for example eu-central-1 |
| Cloudflare R2 | https://<account id>.r2.cloudflarestorage.com |
auto |
| Backblaze B2 | https://s3.<region>.backblazeb2.com |
the region from the endpoint, for example eu-central-003 |
| Other S3-compatible servers | the server's address | as the server expects |
The server addresses objects by path, <endpoint>/<bucket>/<file id>, which all of these support.
- Compose: set the variables in
.envand removegaragefromCOMPOSE_PROFILES, then rundocker compose up -danddocker compose rm -sf garage. docker run: add the variables with-e.
Keep the bucket private. Files are named by random identifiers and never change after upload.
Keeping files on disk
In the Compose setup, set an empty TOLKTAK_S3_BUCKET= in .env and remove garage from COMPOSE_PROFILES. The files are then kept in the data volume, next to the server's other data.
Moving existing files
tolktak-server copy-files uploads the files from the data directory (TOLKTAK_DATA_DIR/files) to the configured bucket. Files that are already in the bucket are skipped, so the command can be run again after an interruption. It leaves the local files in place; delete them once the server works with the bucket.
From a docker run server to the Compose setup, see Moving from docker run. For a Compose setup that kept its files on disk:
docker compose run --rm tolktak copy-files # after setting the TOLKTAK_S3_* variables
docker compose up -d
The command reads the bucket settings from the same variables as the server.
Backups
With Garage, back up the garage-data and garage-meta volumes as described in Maintenance. With a provider, use its versioning or replication, or copy the bucket with a tool such as rclone.