teyfix/rustfs repository overview

⁠teyfix/rustfs

Single-node RustFS with native MC provisioning and synchronization, under the shared CUE/gomplate bootstrap and Process Compose. Versions live in docker-bake.hcl; CI tests amd64 and arm64.

Mount /config/rustfs.yaml and supply RUSTFS_ACCESS_KEY and RUSTFS_SECRET_KEY, or their _FILE equivalents. Generated client configuration stays private under /run/teyfix-rustfs. The server keeps its native /data directory. See Compose⁠.

⁠Mounted buckets

Keep project assets under s3/ and mount ${PWD}/s3:/buckets:ro. Each immediate child directory names a bucket:

s3/
  artwork/
    bucket.yaml
    poster.webp
  uploads/
    bucket.yaml

Use bucket.yaml instead of .gitkeep:

public: true

public defaults to false and selects native anonymous download access or private access. The descriptor is mirrored as an ordinary object, by design. Directories without descriptors also become buckets, initially private; a descriptor supplies explicit policy. Missing or removed descriptors do not delete buckets or reset their existing policies. Bucket names must satisfy the lowercase S3 naming constraint in the schema.

bucket_root: /buckets
reconcile_interval: 5s
console: false
paths:
  log: /var/log/rustfs

After initial provisioning, native mc mirror --md5 --overwrite --watch forwards object changes and observed local deletions. Process Compose also schedules a bounded native reconciliation, every five seconds by default, to discover new buckets, apply descriptors and copy files missed during recursive watch registration. New folders and metadata changes require no container/server restart or new process graph. Runs do not overlap. The tradeoff is a full mirror scan per interval; increase reconcile_interval for large trees. Native watching continues between scans.

Neither pass uses --remove: objects already remote-only survive scans and restarts. Observed local deletions remove their uploaded objects, as expected. Removing a local bucket directory does not remove the bucket itself; file-deletion events still apply. The scan⁠ and watch⁠ behaviors are separate in the pinned MC release.

Every descriptor is validated before applying a reconciliation. Invalid metadata fails initial startup. During operation, it marks readiness unhealthy while the existing server and object watcher continue; a valid subsequent pass restores readiness. Descriptors are ordinary public/private configuration, not a place for credentials. Keep the mounted root available for the container's lifetime.

⁠Explicit resources

The top-level buckets list remains available for buckets without mounted assets and explicit sources:

buckets:
  - name: private-uploads
  - name: fixture
    anonymous: download
    sync:
      source: /seed/fixture
      watch: false

Explicit policies reconcile on startup. sync sources must exist beneath /seed; watch defaults true and false means startup-only synchronization. Do not declare the same bucket in both this list and a descriptor. Changing the top-level configuration requires a restart; live descriptor changes do not. Absent declarations preserve stored buckets and objects.

⁠Runtime

S3 listens on 9000. Console access on 9001 is opt-in. Mount /var/log/rustfs (or paths.log) for native RustFS log files read by external Vector; no collector runs here. Other native observability environment settings remain available. Readiness requires server health, initial policies/synchronization and successful metadata reconciliation. Initial provisioning or object-watcher failures exit through Process Compose.

Build with docker buildx bake rustfs --load; test with docker buildx bake rustfs-smoke. The suite covers live bucket discovery, metadata mirroring/policy/recovery, immediate nested-tree creation, local deletion, preservation of remote-only objects, retained state, startup-only synchronization, missing sources, logs and clean shutdown.

Invoke Compose from the project root. .state/rustfs bind mounts survive docker compose down -v; remove only that scoped disposable state after stopping for a reset. Preserve .cache/ separately.

⁠IAM, versioning and object lock

Explicit buckets support object_lock: true (native mc mb --with-lock) and versioning: enabled | suspended | unchanged (default unchanged; lock requires enabled). Object lock is a creation property here: enabling it in YAML does not retrofit an existing unlocked bucket; the native lock check fails startup in that case. It enables versioning without imposing a retention period. Live bucket.yaml discovery continues to own public/private policy; declare lock-enabled buckets in the main configuration before writing objects.

Declare native IAM policy documents in policies, and users with secret references and policy attachments:

buckets:
  - name: artifacts
    object_lock: true
policies:
  artifacts_read:
    Statement:
      - Effect: Allow
        Action: [s3:GetObject, s3:GetObjectVersion]
        Resource: ["arn:aws:s3:::artifacts/*"]
      - Effect: Allow
        Action: [s3:ListBucket, s3:GetBucketLocation]
        Resource: ["arn:aws:s3:::artifacts"]
users:
  - name: artifact_reader
    secret: { from_env: ARTIFACT_READER_PASSWORD }
    policies: [artifacts_read]

Native mc admin creates/updates policies and user passwords, then attaches declared policies on each start. Attachments are additive; this interface does not delete users, policies or independently attached grants. Policy Version defaults to 2012-10-17; native action/resource validation remains with RustFS. Read-only access to versioned objects needs s3:GetObjectVersion as well as s3:GetObject when the client requests a version explicitly. Smoke checks actual read access, write denial and password rotation against retained storage.

⁠Metrics

RustFS 1.0.1 exports native OTLP/HTTP metrics. It is not a drop-in implementation of MinIO's authenticated Prometheus scrape/config generator. Configure its native environment:

environment:
  RUSTFS_OBS_METRICS_EXPORT_ENABLED: "true"
  RUSTFS_OBS_METRIC_ENDPOINT: http://otel-collector:4318/v1/metrics
  RUSTFS_OBS_METER_INTERVAL: "30"
  RUSTFS_OBS_ENDPOINT_METRICS_HEADERS_FILE: /run/secrets/metrics-headers

The headers file uses native comma-separated name=value syntax, such as an Authorization bearer value; the shared base resolves the file before launch. Point this at an external collector that accepts OTLP and exposes the desired Prometheus endpoint. No log/metrics collector runs inside the RustFS container. Native delivery with an Authorization header and a nonempty metrics payload is exercised by smoke tests. File logs remain available separately for Vector.

Maintained from the source documentation⁠. See published tags⁠ and the service integration guide⁠.