Skip to content

buckethead.config.settings

Env-driven configuration via pydantic-settings. All env vars use the BUCKETHEAD_ prefix with __ as the nesting delimiter.

Call BucketHeadSettings() to load from env and .to_bucket_config() to produce the BucketConfig that BucketSQLite accepts.

buckethead.config.settings

Unified env-driven settings for BucketHead.

One pydantic-settings tree, one convention. Every env var starts with BUCKETHEAD_ and uses __ as the nesting delimiter, so BUCKETHEAD_ONEPASSWORD__VAULT lands in settings.onepassword.vault.

Sub-models split along the grain of the codebase:

  • bucket / snapshot — provider-neutral runtime config. An S3-compatible bucket name + creds + endpoint, plus the key/branch the snapshot lives under.
  • cloudflare / onepassword — per-backend config, keyed to the names registered in provisioning/factories.py. Adding a new cloud or secret store means one new sub-model here + one new branch in the factory; no new env-name convention to invent.

Runtime code reaches BucketConfig via to_bucket_config(), which enforces that the fields SQLite-over-S3 actually needs are present.

BucketEnv

Bases: BaseModel

S3-compatible bucket addressing + credentials.

SnapshotEnv

Bases: BaseModel

Where the snapshot lives inside the bucket.

CloudflareEnv

Bases: BaseModel

Cloudflare-specific knobs.

account_id is dual-purpose: provisioning uses it for API calls, and runtime uses it to derive the S3 endpoint when bucket.endpoint_url is unset and cloud == 'cloudflare-r2'.

OnePasswordEnv

Bases: BaseModel

1Password-specific knobs used by provisioning.

BucketHeadSettings

Bases: BaseSettings

to_bucket_config 

to_bucket_config() -> BucketConfig

Resolve runtime config into a BucketConfig.

Raises ValueError when required fields aren't set. Derives the R2 endpoint from cloudflare.account_id when bucket.endpoint_url is unset and cloud == 'cloudflare-r2'.

Source code in src/buckethead/config/settings.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def to_bucket_config(self) -> BucketConfig:
    """Resolve runtime config into a BucketConfig.

    Raises ``ValueError`` when required fields aren't set. Derives the
    R2 endpoint from ``cloudflare.account_id`` when ``bucket.endpoint_url``
    is unset and ``cloud == 'cloudflare-r2'``.
    """
    missing: list[str] = []
    if not self.bucket.name:
        missing.append("BUCKETHEAD_BUCKET__NAME")
    if not self.bucket.access_key_id:
        missing.append("BUCKETHEAD_BUCKET__ACCESS_KEY_ID")
    if not self.bucket.secret_access_key:
        missing.append("BUCKETHEAD_BUCKET__SECRET_ACCESS_KEY")
    if missing:
        raise ValueError(f"missing required env vars: {', '.join(missing)}")

    endpoint = self.bucket.endpoint_url
    if (
        endpoint is None
        and self.cloud == "cloudflare-r2"
        and self.cloudflare.account_id
    ):
        endpoint = f"https://{self.cloudflare.account_id}.r2.cloudflarestorage.com"

    return BucketConfig(
        bucket=self.bucket.name,
        key=self.snapshot.key,
        endpoint_url=endpoint,
        region=self.bucket.region,
        access_key_id=self.bucket.access_key_id,
        secret_access_key=self.bucket.secret_access_key,
        initial_branch=self.snapshot.branch,
    )