Storage

Telesphorepo keeps metadata in SQLite and every file (artifact, metadata and index) as a blob in one storage backend. There are two backends:

• fs stores blobs on a local directory.
• s3 stores blobs in any S3-compatible bucket: Cloudflare R2, SeaweedFS, AWS S3 and similar. The value r2 is an alias for s3.

The backend is the same for all repos. Blob keys look the same on both backends: repos/{repo}/{path}. On S3, the optional s3.prefix goes in front.

You set the backend on the Settings page, group Storage. Changes apply without a restart.

Filesystem

fs is the default. Blobs go in blobs/ inside the data directory (/data/blobs in the container image). Set fs.root to use another directory.

Tip

In the container, mount a volume on /data. The database, the upload spool, the master key and the blobs all live there. See Backups and data.

S3-compatible

Set these keys:

Setting	Meaning
storage	s3 (or r2)
s3.endpoint	Full URL of the S3 API
s3.region	Region name. Default auto
s3.bucket	Bucket name. The bucket must already exist
s3.access_key_id	Access key ID
s3.secret_access_key	Secret key. The server stores it encrypted and never returns it
s3.prefix	Optional prefix for every object key, for example telesphorepo/
s3.path_style	Path-style addressing. Default false
s3.redirect	Redirect downloads to a presigned URL. Default true
presign_ttl	Lifetime of a presigned URL. Default 5m

Cloudflare R2

Setting	Value
s3.endpoint	https://<account>.r2.cloudflarestorage.com
s3.region	auto
s3.bucket	your bucket
s3.path_style	false

Create an R2 API token with read and write access to the bucket. Use its access key ID and secret.

SeaweedFS

Setting	Value
s3.endpoint	http://seaweedfs:8333
s3.region	any name, for example us-east-1
s3.bucket	your bucket
s3.path_style	true

SeaweedFS and MinIO need path-style addressing. R2 and AWS do not.

You can also set any of these keys from the environment. The variable is TR_ plus the key in upper case, with dots as underscores: TR_S3_BUCKET, TR_S3_ACCESS_KEY_ID, TR_S3_SECRET_ACCESS_KEY. A setting that comes from the environment is read-only in the UI. With TR_STORAGE=s3, the server refuses to start unless the bucket, endpoint and keys are set.

The connection test

Before the server saves a change to a backend key, it runs a probe. The probe writes, reads, checks and deletes one object named _telesphorepo/probe-<hex>. If the probe fails, the server saves nothing and shows the error. The credentials need permission for all four actions.

You can also run the probe without saving. POST /api/settings/storage/test takes the same body as the settings change. See the HTTP API.

Download redirects

With s3.redirect on, a GET for a Maven or raw file on S3 answers 302 with a presigned URL. The client downloads the file straight from the bucket. The server still checks the caller’s permission first.

• HEAD is never redirected.
• A presigned URL works for anyone who has it until presign_ttl ends.
• Clients and build tools must reach the bucket endpoint. If the bucket is on a private network, turn s3.redirect off. The server then streams every download.

Change the backend

If your server has files and you point it at another location, the server moves the existing blobs for you. A change of only credentials, region, path style or redirect does not move anything. It saves and swaps at once. See Moving storage.

Caution

A storage key that the environment sets is read-only in the UI. The server answers 409 if a request tries to change it. To start a move from the UI, remove the TR_ variable first and restart.