docs: add garage setup guide and update config example filename

Signed-off-by: Noooste <83548733+Noooste@users.noreply.github.com>
2026-08-27 15:37:03 +00:00 · 2026-04-24 12:09:04 +02:00
parent f1eeca60bf
commit 42055930ed
3 changed files with 61 additions and 2 deletions
@@ -0,0 +1,113 @@
+# Garage UI Backend Configuration
+
+# Server configuration
+server:
+  host: "0.0.0.0"
+  port: 8080
+  environment: "development" # development, production
+  domain: "localhost" # Domain name for the application
+  protocol: "http" # Protocol for internal communication (http/https)
+  root_url: "http://localhost:8080" # Full external URL for OAuth2 redirects (adjust for production)
+
+  # Request size limits (in bytes)
+  max_body_size: 314572800 # 300MB - Maximum request body size (increase for large file uploads)
+  max_header_size: 1048576 # 1MB - Maximum request header size
+  read_buffer_size: 4096 # 4KB - Read buffer size
+  write_buffer_size: 4096 # 4KB - Write buffer size
+
+# Garage S3 Configuration
+garage:
+  endpoint: "http://localhost:3900" # Garage S3 API endpoint
+  region: "eu-west-1" # S3 region (ensure it matches Garage S3 configuration)
+
+  # Garage Admin API configuration
+  admin_endpoint: "http://localhost:3903" # Garage Admin API endpoint
+  admin_token: "changeme" # Admin API bearer token
+
+# Authentication Configuration
+# You can enable one or both authentication methods
+auth:
+  # JWT Configuration
+  # Ed25519 private key in PEM format for JWT token signing
+  # If not specified, a new key will be generated on each startup (tokens won't persist across restarts)
+  # Generate with: openssl genpkey -algorithm ED25519 -out jwt-key.pem
+  # The key is a 64-byte Ed25519 private key
+  jwt_private_key: "" # Leave empty to auto-generate, or provide PEM-encoded Ed25519 private key
+
+  # Admin Authentication (username/password)
+  admin:
+    enabled: false # Set to true to enable admin login
+    username: "admin"
+    password: "changeme"
+
+  # Admin Token Authentication
+  # When enabled, users can log in using the Garage admin token
+  # Auto-enabled when no other auth method is configured (zero-config fallback)
+  token:
+    enabled: false # Set to true to explicitly enable, or leave all auth disabled for auto-enable
+
+  # OIDC Configuration
+  # NOTE: When OIDC is enabled, server.root_url is required for OAuth2 redirects
+  # The redirect URL will be automatically constructed as: {root_url}/auth/oidc/callback
+  oidc:
+    enabled: false # Set to true to enable OIDC login
+    provider_name: "Keycloak"
+    client_id: "garage-ui"
+    client_secret: "your-client-secret"
+
+    # OIDC scopes to request
+    scopes:
+      - openid
+      - email
+      - profile
+
+    # OIDC Provider URLs
+    issuer_url: "https://keycloak.example.com/realms/master"
+
+    # Token validation
+    skip_issuer_check: false
+    skip_expiry_check: false
+
+    # Attribute mappings
+    email_attribute: "email"
+    username_attribute: "preferred_username"
+    name_attribute: "name"
+
+    # Role-based access (optional)
+    role_attribute_path: "resource_access.garage-ui.roles"
+    admin_role: "admin"
+
+    # TLS configuration
+    tls_skip_verify: false # Only set to true for testing, not recommended for production
+
+    # Session configuration
+    session_max_age: 86400 # 24 hours in seconds
+    cookie_name: "garage_session"
+    cookie_secure: false # Set to true in production with HTTPS
+    cookie_http_only: true
+    cookie_same_site: "lax" # lax, strict, none
+
+# CORS Configuration (for frontend)
+cors:
+  enabled: true
+  allowed_origins:
+    - "*" # Vite default
+  allowed_methods:
+    - GET
+    - POST
+    - PUT
+    - DELETE
+    - OPTIONS
+  allowed_headers:
+    - Origin
+    - Content-Type
+    - Accept
+    - Authorization
+  allow_credentials: false
+  max_age: 3600
+
+# Logging Configuration
+# The application uses zerolog for structured logging
+logging:
+  level: "info" # Options: debug, info, warn, error
+  format: "text" or "json"