docs: add configuration reference documenting all config.yaml options #4

New Issue

forbes · 2026-02-06T18:20:37Z

forbes commented

2026-02-06 18:20:37 +00:00

Problem

There is no reference documentation for config.yaml. The only guidance is config.example.yaml which has inline comments but does not explain the full scope of options, environment variable overrides, or the interaction between configuration sections.

The auth system alone has significant configuration surface area (local, LDAP, OIDC, CORS, session settings) that users need to understand to deploy Silo in different environments.

What Needs Documenting

Server Section

host, port, base_url
How base_url affects OIDC callbacks and session cookie settings

Database Section

host, port, name, user, password
sslmode options and when to use each
max_connections tuning guidance
Environment variable override: SILO_DB_PASSWORD

Storage Section (MinIO)

endpoint, access_key, secret_key, bucket
use_ssl and region
Environment variable overrides: SILO_MINIO_ACCESS_KEY, SILO_MINIO_SECRET_KEY

Schemas Section

directory — path to YAML schema files
default — default schema name for part number generation
How schemas are loaded and cached

FreeCAD Section

uri_scheme and executable path

Auth Section (most complex)

auth.enabled — master toggle, dev mode behavior when false
auth.local — local auth with bcrypt, default admin account setup
- default_admin_username, default_admin_password (env var recommended)
auth.ldap — LDAP/FreeIPA configuration
- url, base_dn, bind_dn, bind_password
- user_filter, group_filter
- tls_skip_verify (testing only)
- role_mapping — group DN to role mapping
auth.oidc — OpenID Connect configuration
- issuer_url, client_id, client_secret
- redirect_url and how it's derived from base_url
- admin_role, editor_role, default_role
auth.cors — CORS configuration
- allowed_origins — list of allowed origins
- Behavior difference when auth is enabled vs disabled

Environment Variable Overrides

Document all supported env vars and which config keys they override
SILO_DB_PASSWORD, SILO_MINIO_ACCESS_KEY, SILO_MINIO_SECRET_KEY
SILO_ADMIN_USERNAME, SILO_ADMIN_PASSWORD
How the override mechanism works (env takes precedence over YAML)

Tasks

Create docs/CONFIGURATION.md with full reference for all config sections
Document every config key with type, default value, and description
Document all environment variable overrides
Add deployment scenario examples (dev mode, local auth only, LDAP, OIDC)
Cross-reference from DEPLOYMENT.md and AUTH.md

## Problem There is no reference documentation for `config.yaml`. The only guidance is `config.example.yaml` which has inline comments but does not explain the full scope of options, environment variable overrides, or the interaction between configuration sections. The auth system alone has significant configuration surface area (local, LDAP, OIDC, CORS, session settings) that users need to understand to deploy Silo in different environments. ## What Needs Documenting ### Server Section - `host`, `port`, `base_url` - How `base_url` affects OIDC callbacks and session cookie settings ### Database Section - `host`, `port`, `name`, `user`, `password` - `sslmode` options and when to use each - `max_connections` tuning guidance - Environment variable override: `SILO_DB_PASSWORD` ### Storage Section (MinIO) - `endpoint`, `access_key`, `secret_key`, `bucket` - `use_ssl` and `region` - Environment variable overrides: `SILO_MINIO_ACCESS_KEY`, `SILO_MINIO_SECRET_KEY` ### Schemas Section - `directory` — path to YAML schema files - `default` — default schema name for part number generation - How schemas are loaded and cached ### FreeCAD Section - `uri_scheme` and `executable` path ### Auth Section (most complex) - `auth.enabled` — master toggle, dev mode behavior when false - `auth.local` — local auth with bcrypt, default admin account setup - `default_admin_username`, `default_admin_password` (env var recommended) - `auth.ldap` — LDAP/FreeIPA configuration - `url`, `base_dn`, `bind_dn`, `bind_password` - `user_filter`, `group_filter` - `tls_skip_verify` (testing only) - `role_mapping` — group DN to role mapping - `auth.oidc` — OpenID Connect configuration - `issuer_url`, `client_id`, `client_secret` - `redirect_url` and how it's derived from `base_url` - `admin_role`, `editor_role`, `default_role` - `auth.cors` — CORS configuration - `allowed_origins` — list of allowed origins - Behavior difference when auth is enabled vs disabled ### Environment Variable Overrides - Document all supported env vars and which config keys they override - `SILO_DB_PASSWORD`, `SILO_MINIO_ACCESS_KEY`, `SILO_MINIO_SECRET_KEY` - `SILO_ADMIN_USERNAME`, `SILO_ADMIN_PASSWORD` - How the override mechanism works (env takes precedence over YAML) ## Tasks - [ ] Create `docs/CONFIGURATION.md` with full reference for all config sections - [ ] Document every config key with type, default value, and description - [ ] Document all environment variable overrides - [ ] Add deployment scenario examples (dev mode, local auth only, LDAP, OIDC) - [ ] Cross-reference from DEPLOYMENT.md and AUTH.md

forbes closed this issue

2026-02-06 20:33:19 +00:00

forbes referenced this issue from a commit

2026-02-06 22:20:03 +00:00

docs: add comprehensive configuration reference

forbes referenced this issue from a commit

2026-02-07 19:40:25 +00:00

docs: add comprehensive configuration reference

forbes referenced this issue

2026-03-03 20:30:49 +00:00

feat(storage): explode .kc/.fcstd archives for XML-level revision diffing #176

Sign in to join this conversation.