mirror of https://github.com/block/buzz.git synced 2026-08-18 06:50:31 +02:00

Files

T

7012d86d52 feat: configure S3 URL addressing style (#3400 )

## Summary

- add one strict `BUZZ_S3_ADDRESSING_STYLE=path|virtual` setting shared
by media and Git/CAS storage
- preserve path-style defaults for bundled Compose/Helm MinIO while
supporting Railway's virtual-hosted bucket contract
- fail startup on invalid or non-Unicode values before dependency
connection, and validate the Helm value with the same two choices
- document operator mappings and why endpoint and bucket remain separate
for routing and SigV4 signing

## Best-practice rationale

AWS documents both URL forms and favors virtual-hosted addressing for
S3, while compatibility endpoints such as the bundled MinIO deployment
can require path style. `rust-s3` defaults to virtual/subdomain
addressing and provides `with_path_style()` for the explicit
compatibility case.

Some providers buckets only support as virtual-hosted bucket styles.
This PR therefore uses one explicit, provider-neutral switch rather than
endpoint heuristics or fallback behavior, while retaining `path` as
Buzz's backward-compatible default.

Sources:
-
https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html
- https://docs.rs/rust-s3/0.37.0/s3/bucket/struct.Bucket.html
- https://docs.railway.com/storage-buckets#url-style
-
https://github.com/minio/minio/blob/master/docs/config/README.md#domain

## Validation

- `cargo fmt --all`
- `cargo check --workspace --all-targets`
- targeted `buzz-media` and `buzz-relay` parsing/client-construction
tests for defaults, strict errors, and both URL styles
- Helm unittest: 45/45 passed
- Compose config/render validation passed
- local MinIO path-mode relay startup passed the Git A3 conformance
probe and became ready
- unreachable object storage failed startup and readiness never opened
- push hooks completed the broader Rust and desktop suites successfully

---------

Signed-off-by: npub122y0pqkertljmedu303rl0aqrj3w8pvu43t6jxm6875lzg6f2pwqegc3xc <5288f082d91aff2de5bc8be23fbfa01ca2e3859cac57a91b7a3fa9f12349505c@buzz.block.builderlab.xyz>
Signed-off-by: Kalvin Chau <kalvin@block.xyz>
Co-authored-by: npub122y0pqkertljmedu303rl0aqrj3w8pvu43t6jxm6875lzg6f2pwqegc3xc <5288f082d91aff2de5bc8be23fbfa01ca2e3859cac57a91b7a3fa9f12349505c@buzz.block.builderlab.xyz>

2026-07-29 17:00:41 -07:00

2.3 KiB

Raw Blame History

Buzz Docker Compose deployment

This is the single-node/VPS deployment bundle. It is intentionally separate from the root docker-compose.yml, which remains local development infrastructure.

Quick start

cd deploy/compose
cp .env.example .env
$EDITOR .env       # replace every CHANGE_ME value
./run.sh start

For a public VPS with automatic Let's Encrypt certificates:

cd deploy/compose
BUZZ_COMPOSE_TLS=true ./run.sh start

The bootstrap script should eventually replace manual .env editing for normal users. It is responsible for generating stable secrets and, optionally, an owner keypair.

Production notes

Requires Docker Compose v2.24.4 or newer; the TLS override uses Compose's !reset tag to remove the direct relay port when Caddy terminates HTTPS.
Default BUZZ_IMAGE tracks ghcr.io/block/buzz:main for early testing. Pin it to ghcr.io/block/buzz:sha-<7> or a semver release tag for production once available.
Keep BUZZ_RELAY_PRIVATE_KEY, BUZZ_GIT_HOOK_HMAC_SECRET, database/Redis, and S3 secrets stable across restarts.
RELAY_OWNER_PUBKEY is intentionally not prefixed with BUZZ_; it must be a 64-character hex Nostr pubkey when closed relay mode is enabled.
BUZZ_AUTO_MIGRATE is opt-in. Set BUZZ_AUTO_MIGRATE=true or run buzz-admin migrate before starting the relay when bootstrapping a fresh database. Auto-migration requires an image that includes embedded SQLx migrations.
The stack uses Postgres, Redis, MinIO, and a git data volume because those are real Buzz dependencies today. Minimal mode can simplify this later.
The bundled Compose stack fixes the relay endpoint to http://minio:9000 and BUZZ_S3_ADDRESSING_STYLE=path: Docker DNS resolves minio, not <bucket>.minio. It is not configurable for an external S3 provider through .env; use the Helm chart or a custom Compose configuration for providers such as new Railway Storage Buckets that require virtual addressing.

Run ./run.sh backup-hint for the backup checklist.

Validation

Before sharing an install link publicly, verify a fresh install with:

cd deploy/compose
cp .env.example .env
$EDITOR .env
./run.sh config
./run.sh start
curl -fsS "http://127.0.0.1:$(grep -E '^BUZZ_HTTP_PORT=' .env | cut -d= -f2-)/_liveness"
./run.sh status

2.3 KiB Raw Blame History

Buzz Docker Compose deployment

Quick start

Production notes

Validation

2.3 KiB

Raw Blame History