Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Store blobs in a folder or an S3-compatible bucket

Built images, themes and cached PDFs live in a blob store that the web service and the worker must both reach.

About this task

By default the blob store is a local folder, BLOB_DIR. That only works when the app and the worker share it, as in the Compose file's blobs volume. When they run on different hosts, as on Railway, or with app replicas on several hosts, use a bucket.

Keys look like repos/<repo id>/<commit>/images/architecture.svg for files from the docs tree, and pdf/<release id>/<hash>/<name>.pdf for cached PDFs. Nothing is ever overwritten with different content, so no invalidation is needed.

  1. Create a bucket and an access key with read and write access to it.

    AWS S3, Cloudflare R2, MinIO and Railway Buckets all work.

  2. Set the same four variables on the web service and the worker. 
    S3_BUCKET=opend-blobs
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
  3. Optional: set S3_REGION (default auto), S3_FORCE_PATH_STYLE=1 for MinIO-style endpoints, and S3_PREFIX to share a bucket.
  4. Restart both services.

    The start-up log line shows "blobs":"s3".

  5. Rebuild the live releases, so their images and themes are uploaded to the bucket.

    Trigger a build of each release ref's current commit with the admin API, or push.

Results

Either all four required variables are set or none are; anything in between stops the server at start-up. The bucket can stay private: readers never fetch from it directly.