kindred/silo
1
1
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update configuration and deployment docs for filesystem storage backend #131

New Issue
Open
opened 2026-02-17 16:11:52 +00:00 by forbes · 0 comments
forbes commented 2026-02-17 16:11:52 +00:00
Owner
Copy Link

Summary

Update all documentation to cover the new filesystem storage backend option, making MinIO optional for new deployments.

Context

Three documentation files need updates:

  • docs/CONFIGURATION.md — currently documents only MinIO/S3 storage config
  • docs/INSTALL.md — installation guide references MinIO setup
  • docs/DEPLOYMENT.md — production deployment operations guide

Additionally, Docker Compose files and config examples need updating.

Current storage documentation

docs/CONFIGURATION.md — Storage section

Currently documents:

storage:
  endpoint: "localhost:9000"
  access_key: "minioadmin"
  secret_key: "minioadmin"
  bucket: "silo-files"
  use_ssl: false
  region: "us-east-1"

Environment variable overrides: SILO_MINIO_ENDPOINT, SILO_MINIO_ACCESS_KEY, SILO_MINIO_SECRET_KEY.

Config files

  • config.example.yaml — template with comments
  • deployments/config.dev.yaml — Docker Compose dev config
  • deployments/config.prod.yaml — production daemon config

Docker Compose files

  • deployments/docker-compose.yaml — dev (includes MinIO service)
  • deployments/docker-compose.allinone.yaml — all-in-one with LDAP (includes MinIO)
  • deployments/docker-compose.prod.yaml — production (external MinIO reference)

Requirements

docs/CONFIGURATION.md

Add filesystem backend documentation alongside existing MinIO docs:

storage:
  backend: "filesystem"  # "minio" (default) | "filesystem"
  # Filesystem backend settings (used when backend: "filesystem")
  filesystem:
    root: "/var/lib/silo/objects"
  # MinIO/S3 settings (used when backend: "minio")
  endpoint: "localhost:9000"
  access_key: "minioadmin"
  # ... existing fields ...

Document:

  • storage.backend field and valid values
  • storage.filesystem.root — must be writable by the silod process
  • Filesystem backend requires no external services
  • When backend is unset, defaults to "minio" for backward compatibility

docs/INSTALL.md

  • Add filesystem backend as the recommended option for simple/single-server deployments
  • Keep MinIO as an option for S3-compatible / distributed setups
  • Remove MinIO as a hard requirement
  • Add filesystem prerequisites: writable directory, disk space considerations

docs/DEPLOYMENT.md

  • Add backup strategy for filesystem backend: rsync, ZFS snapshots, or similar
  • Document that filesystem files + pg_dump constitute a complete backup
  • Note: no automatic garbage collection (unlike MinIO lifecycle policies) — monitor disk space
  • Add permissions note: silod process needs read/write to storage.filesystem.root

config.example.yaml

Add commented filesystem config block showing both options.

Docker Compose files

  • deployments/docker-compose.yaml: Add a profile or make MinIO service optional (e.g. Docker Compose profiles). Add volume mount for filesystem storage.
  • deployments/docker-compose.allinone.yaml: Same — make MinIO optional.
  • Update deployments/config.dev.yaml to show filesystem option.
  • deployments/docker-compose.prod.yaml: Already has no MinIO service — add filesystem volume mount.

Acceptance criteria

  • CONFIGURATION.md documents both backends with examples
  • INSTALL.md covers filesystem setup without MinIO
  • DEPLOYMENT.md includes filesystem backup strategy
  • config.example.yaml updated with filesystem option
  • Docker Compose files make MinIO optional
  • New deployments can follow docs without touching MinIO
  • Existing MinIO deployments are not broken by doc changes

Priority

P1

Depends on

  • #126 (FileStore interface — for config structure)
  • #127 (filesystem backend — for behavior to document)

Part of

Storage Migration: MinIO → PostgreSQL + Filesystem

## Summary Update all documentation to cover the new filesystem storage backend option, making MinIO optional for new deployments. ## Context Three documentation files need updates: - `docs/CONFIGURATION.md` — currently documents only MinIO/S3 storage config - `docs/INSTALL.md` — installation guide references MinIO setup - `docs/DEPLOYMENT.md` — production deployment operations guide Additionally, Docker Compose files and config examples need updating. ## Current storage documentation ### `docs/CONFIGURATION.md` — Storage section Currently documents: ```yaml storage: endpoint: "localhost:9000" access_key: "minioadmin" secret_key: "minioadmin" bucket: "silo-files" use_ssl: false region: "us-east-1" ``` Environment variable overrides: `SILO_MINIO_ENDPOINT`, `SILO_MINIO_ACCESS_KEY`, `SILO_MINIO_SECRET_KEY`. ### Config files - `config.example.yaml` — template with comments - `deployments/config.dev.yaml` — Docker Compose dev config - `deployments/config.prod.yaml` — production daemon config ### Docker Compose files - `deployments/docker-compose.yaml` — dev (includes MinIO service) - `deployments/docker-compose.allinone.yaml` — all-in-one with LDAP (includes MinIO) - `deployments/docker-compose.prod.yaml` — production (external MinIO reference) ## Requirements ### `docs/CONFIGURATION.md` Add filesystem backend documentation alongside existing MinIO docs: ```yaml storage: backend: "filesystem" # "minio" (default) | "filesystem" # Filesystem backend settings (used when backend: "filesystem") filesystem: root: "/var/lib/silo/objects" # MinIO/S3 settings (used when backend: "minio") endpoint: "localhost:9000" access_key: "minioadmin" # ... existing fields ... ``` Document: - `storage.backend` field and valid values - `storage.filesystem.root` — must be writable by the silod process - Filesystem backend requires no external services - When `backend` is unset, defaults to `"minio"` for backward compatibility ### `docs/INSTALL.md` - Add filesystem backend as the recommended option for simple/single-server deployments - Keep MinIO as an option for S3-compatible / distributed setups - Remove MinIO as a hard requirement - Add filesystem prerequisites: writable directory, disk space considerations ### `docs/DEPLOYMENT.md` - Add backup strategy for filesystem backend: `rsync`, ZFS snapshots, or similar - Document that filesystem files + `pg_dump` constitute a complete backup - Note: no automatic garbage collection (unlike MinIO lifecycle policies) — monitor disk space - Add permissions note: silod process needs read/write to `storage.filesystem.root` ### `config.example.yaml` Add commented filesystem config block showing both options. ### Docker Compose files - `deployments/docker-compose.yaml`: Add a profile or make MinIO service optional (e.g. Docker Compose profiles). Add volume mount for filesystem storage. - `deployments/docker-compose.allinone.yaml`: Same — make MinIO optional. - Update `deployments/config.dev.yaml` to show filesystem option. - `deployments/docker-compose.prod.yaml`: Already has no MinIO service — add filesystem volume mount. ## Acceptance criteria - [ ] `CONFIGURATION.md` documents both backends with examples - [ ] `INSTALL.md` covers filesystem setup without MinIO - [ ] `DEPLOYMENT.md` includes filesystem backup strategy - [ ] `config.example.yaml` updated with filesystem option - [ ] Docker Compose files make MinIO optional - [ ] New deployments can follow docs without touching MinIO - [ ] Existing MinIO deployments are not broken by doc changes ## Priority P1 ## Depends on - #126 (FileStore interface — for config structure) - #127 (filesystem backend — for behavior to document) ## Part of Storage Migration: MinIO → PostgreSQL + Filesystem
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
forbes
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: kindred/silo#131
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?