Skip to content

Modern Docker Management, Designed for Everyone

refactor: add dynamic env config schema generation (#2237)

Kyle Mendell8e65564fd1a3
diff --git a/Justfile b/Justfile
index 4c87ea15c..a47e3a3c1 100644
--- a/Justfile
+++ b/Justfile
@@ -210,6 +210,24 @@ deploy scope kind *args:
proto-backend:
cd {{ edge_proto_dir }} && go run github.com/bufbuild/buf/cmd/[email protected] generate
+# Generate the docs config schema JSON.
+[group('docs')]
+_docs-config output="" source_root=".":
+ #!/usr/bin/env bash
+ set -euo pipefail
+
+ cmd=(go run -tags exclude_frontend ./backend/cmd config-schema --source-root "{{ source_root }}")
+ if [ -n "{{ output }}" ]; then
+ cmd+=(--output "{{ output }}")
+ fi
+
+ "${cmd[@]}"
+
+# Docs targets. Example: just docs config
+[group('docs')]
+docs target *args:
+ @just "_docs-{{ target }}" {{ args }}
+
# Benchmark edge tunnel transport performance (gRPC vs WebSocket) with allocations.
# Usage: just bench-edge-tunnel [count] [benchtime]
diff --git a/backend/cli/config_schema.go b/backend/cli/config_schema.go
new file mode 100644
index 000000000..24cdaf951
--- /dev/null
+++ b/backend/cli/config_schema.go
@@ -0,0 +1,57 @@
+package cli
+
+import (
+ "fmt"
+ "os"
+
+ "github.com/getarcaneapp/arcane/backend/internal/configschema"
+ "github.com/spf13/cobra"
+)
+
+var configSchemaCmd = &cobra.Command{
+ Use: "config-schema",
+ Short: "Export the config/settings schema for docs",
+ Long: "Export the canonical JSON schema for runtime config and settings environment overrides",
+ Run: func(cmd *cobra.Command, args []string) {
+ outputFile, err := cmd.Flags().GetString("output")
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "Error reading --output flag: %v\n", err)
+ os.Exit(1)
+ }
+
+ sourceRoot, err := cmd.Flags().GetString("source-root")
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "Error reading --source-root flag: %v\n", err)
+ os.Exit(1)
+ }
+
+ doc, err := configschema.GenerateWithSourceRoot(sourceRoot)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "Error generating config schema: %v\n", err)
+ os.Exit(1)
+ }
+
+ output, err := configschema.MarshalJSON(doc)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "Error encoding config schema: %v\n", err)
+ os.Exit(1)
+ }
+
+ if outputFile != "" {
+ if err := os.WriteFile(outputFile, output, 0o600); err != nil {
+ fmt.Fprintf(os.Stderr, "Error writing file: %v\n", err)
+ os.Exit(1)
+ }
+ fmt.Fprintf(os.Stderr, "Config schema written to %s\n", outputFile)
+ return
+ }
+
+ fmt.Print(string(output))
+ },
+}
+
+func init() {
+ configSchemaCmd.Flags().StringP("output", "o", "", "Output file (default: stdout)")
+ configSchemaCmd.Flags().String("source-root", "", "Repository root or backend source root (default: auto-detect from working directory)")
+ rootCmd.AddCommand(configSchemaCmd)
+}
diff --git a/backend/internal/configschema/schema.go b/backend/internal/configschema/schema.go
new file mode 100644
index 000000000..aca671638
--- /dev/null
+++ b/backend/internal/configschema/schema.go
@@ -0,0 +1,479 @@
+package configschema
+
+import (
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "go/ast"
+ "go/format"
+ "go/parser"
+ "go/token"
+ "os"
+ "path/filepath"
+ "reflect"
+ "slices"
+ "sort"
+ "strconv"
+ "strings"
+
+ "github.com/getarcaneapp/arcane/backend/internal/models"
+ "github.com/getarcaneapp/arcane/backend/internal/services"
+ "github.com/getarcaneapp/arcane/backend/pkg/utils"
+)
+
+const (
+ schemaVersion = 1
+ sourceFileConfig = "backend/internal/config/config.go"
+ sourceFileBuildablesConfig = "backend/internal/config/buildables_config.go"
+ sourceFileSettings = "backend/internal/models/settings.go"
+ sourceSymbolConfig = "config.Config"
+ sourceSymbolBuildablesConfig = "config.BuildablesConfig"
+)
+
+var documentNotes = []string{
+ "When AGENT_MODE=true or UI_CONFIGURATION_DISABLED=true, Arcane manages non-internal settings through environment variables more broadly than the always-on envOverride path.",
+ "The settingEnvOverrides section includes stable envOverride settings plus non-internal settings that are env-managed in env-only modes.",
+}
+
+// SchemaDocument is the canonical JSON artifact consumed by the docs site.
+type SchemaDocument struct {
+ SchemaVersion int `json:"schemaVersion"`
+ Notes []string `json:"notes,omitempty"`
+ EnvConfig []ConfigEntry `json:"envConfig"`
+ SettingEnvOverrides []SettingOverrideEntry `json:"settingEnvOverrides"`
+}
+
+// ConfigEntry describes an environment-backed runtime config value.
+type ConfigEntry struct {
+ Env string `json:"env"`
+ Field string `json:"field"`
+ Type string `json:"type"`
+ DefaultValue string `json:"defaultValue,omitempty"`
+ Description string `json:"description,omitempty"`
+ Options []string `json:"options,omitempty"`
+ SupportsFile bool `json:"supportsFile,omitempty"`
+ Conditional bool `json:"conditional,omitempty"`
+ BuildTags []string `json:"buildTags,omitempty"`
+ Source string `json:"source"`
+ SourceFile string `json:"sourceFile"`
+ SourceSymbol string `json:"sourceSymbol"`
+}
+
+// SettingOverrideEntry describes a database-backed setting that can be controlled by env vars.
+type SettingOverrideEntry struct {
+ Env string `json:"env"`
+ SettingKey string `json:"settingKey"`
+ Description string `json:"description,omitempty"`
+ DefaultValue string `json:"defaultValue,omitempty"`
+ Type string `json:"type"`
+ Sensitive bool `json:"sensitive"`
+ Deprecated bool `json:"deprecated"`
+ Category string `json:"category,omitempty"`
+ Public bool `json:"public"`
+ Requires string `json:"requires,omitempty"`
+ Note string `json:"note,omitempty"`
+ Source string `json:"source"`
+ SourceFile string `json:"sourceFile"`
+ SourceSymbol string `json:"sourceSymbol"`
+}
+
+type envFieldOptions struct {
+ conditional bool
+ buildTags []string
+ sourceFile string
+ sourceType string
+}
+
+type overrideDocRule struct {
+ requires string
+ note string
+ deprecated bool
+}
+
+var overrideDocRules = map[string]overrideDocRule{
+ "authOidcConfig": {
+ deprecated: true,
+ note: "Deprecated legacy JSON OIDC configuration. Prefer the discrete OIDC_* environment variables.",
+ },
+ "autoUpdateInterval": {
+ requires: "AUTO_UPDATE=true to have effect at runtime.",
+ },
+ "scheduledPruneInterval": {
+ requires: "SCHEDULED_PRUNE_ENABLED=true to have effect at runtime.",
+ },
+ "scheduledPruneContainers": {
+ requires: "SCHEDULED_PRUNE_ENABLED=true to have effect at runtime.",
+ },
+ "scheduledPruneImages": {
+ requires: "SCHEDULED_PRUNE_ENABLED=true to have effect at runtime.",
+ },
+ "scheduledPruneVolumes": {
+ requires: "SCHEDULED_PRUNE_ENABLED=true to have effect at runtime.",
+ },
+ "scheduledPruneNetworks": {
+ requires: "SCHEDULED_PRUNE_ENABLED=true to have effect at runtime.",
+ },
+ "scheduledPruneBuildCache": {
+ requires: "SCHEDULED_PRUNE_ENABLED=true to have effect at runtime.",
+ },
+ "vulnerabilityScanInterval": {
+ requires: "VULNERABILITY_SCAN_ENABLED=true to have effect at runtime.",
+ },
+ "autoHealInterval": {
+ requires: "AUTO_HEAL_ENABLED=true to have effect at runtime.",
+ },
+ "autoHealExcludedContainers": {
+ requires: "AUTO_HEAL_ENABLED=true to have effect at runtime.",
+ },
+ "autoHealMaxRestarts": {
+ requires: "AUTO_HEAL_ENABLED=true to have effect at runtime.",
+ },
+ "autoHealRestartWindow": {
+ requires: "AUTO_HEAL_ENABLED=true to have effect at runtime.",
+ },
+}
+
+// GenerateWithSourceRoot builds the canonical schema document for config and settings docs.
+func GenerateWithSourceRoot(sourceRoot string) (*SchemaDocument, error) {
+ envConfig, err := collectEnvConfigInternal(sourceRoot)
+ if err != nil {
+ return nil, fmt.Errorf("collect env config: %w", err)
+ }
+
+ settingOverrides, err := collectSettingEnvOverridesInternal()
+ if err != nil {
+ return nil, fmt.Errorf("collect setting env overrides: %w", err)
+ }
+
+ doc := &SchemaDocument{
+ SchemaVersion: schemaVersion,
+ Notes: slices.Clone(documentNotes),
+ EnvConfig: envConfig,
+ SettingEnvOverrides: settingOverrides,
+ }
+
+ return doc, nil
+}
+
+// MarshalJSON returns a stable, indented JSON encoding of the schema document.
+func MarshalJSON(doc *SchemaDocument) ([]byte, error) {
+ output, err := json.MarshalIndent(doc, "", " ")
+ if err != nil {
+ return nil, fmt.Errorf("marshal schema document: %w", err)
+ }
+
+ output = append(output, '\n')
+ return output, nil
+}
+
+func collectEnvConfigInternal(sourceRoot string) ([]ConfigEntry, error) {
+ root, err := resolveSourceRootInternal(sourceRoot)
+ if err != nil {
+ return nil, err
+ }
+
+ configEntries, err := parseStructEnvFieldsInternal(
+ filepath.Join(root, "internal/config/config.go"),
+ "Config",
+ envFieldOptions{
+ sourceFile: sourceFileConfig,
+ sourceType: sourceSymbolConfig,
+ },
+ )
+ if err != nil {
+ return nil, err
+ }
+
+ buildablesEntries, err := parseStructEnvFieldsInternal(
+ filepath.Join(root, "internal/config/buildables_config.go"),
+ "BuildablesConfig",
+ envFieldOptions{
+ conditional: true,
+ buildTags: []string{"buildables"},
+ sourceFile: sourceFileBuildablesConfig,
+ sourceType: sourceSymbolBuildablesConfig,
+ },
+ )
+ if err != nil {
+ return nil, err
+ }
+
+ configEntries = append(configEntries, buildablesEntries...)
+ sort.Slice(configEntries, func(i, j int) bool {
+ return configEntries[i].Env < configEntries[j].Env
+ })
+
+ return configEntries, nil
+}
+
+func parseStructEnvFieldsInternal(filename, structName string, opts envFieldOptions) ([]ConfigEntry, error) {
+ fset := token.NewFileSet()
+ file, err := parser.ParseFile(fset, filename, nil, parser.ParseComments)
+ if err != nil {
+ return nil, fmt.Errorf("parse %s: %w", filename, err)
+ }
+
+ structType, err := findStructTypeInternal(file, structName)
+ if err != nil {
+ return nil, err
+ }
+
+ entries := make([]ConfigEntry, 0, len(structType.Fields.List))
+ for _, field := range structType.Fields.List {
+ if len(field.Names) == 0 || field.Tag == nil {
+ continue
+ }
+
+ tagValue, err := strconv.Unquote(field.Tag.Value)
+ if err != nil {
+ return nil, fmt.Errorf("unquote struct tag for %s: %w", structName, err)
+ }
+
+ structTag := reflect.StructTag(tagValue)
+ envName := structTag.Get("env")
+ if envName == "" {
+ continue
+ }
+
+ options := splitTagListInternal(structTag.Get("options"))
+ typeName, err := exprStringInternal(field.Type)
+ if err != nil {
+ return nil, fmt.Errorf("render type for %s.%s: %w", structName, field.Names[0].Name, err)
+ }
+
+ description := normalizeCommentInternal(field.Doc.Text())
+ if description == "" {
+ description = normalizeCommentInternal(field.Comment.Text())
+ }
+
+ for _, name := range field.Names {
+ entries = append(entries, ConfigEntry{
+ Env: envName,
+ Field: name.Name,
+ Type: typeName,
+ DefaultValue: structTag.Get("default"),
+ Description: description,
+ Options: options,
+ SupportsFile: slices.Contains(options, "file"),
+ Conditional: opts.conditional,
+ BuildTags: slices.Clone(opts.buildTags),
+ Source: opts.sourceType,
+ SourceFile: opts.sourceFile,
+ SourceSymbol: opts.sourceType + "." + name.Name,
+ })
+ }
+ }
+
+ return entries, nil
+}
+
+func collectSettingEnvOverridesInternal() ([]SettingOverrideEntry, error) {
+ defaults := services.DefaultSettingsConfig()
+ settingsType := reflect.TypeFor[models.Settings]()
+ entries := make([]SettingOverrideEntry, 0, settingsType.NumField())
+
+ for field := range settingsType.Fields() {
+ keyTag := field.Tag.Get("key")
+ if keyTag == "" {
+ continue
+ }
+
+ tagParts := splitTagListInternal(keyTag)
+ if len(tagParts) == 0 {
+ continue
+ }
+
+ key := tagParts[0]
+ attrs := tagParts[1:]
+ hasEnvOverride := slices.Contains(attrs, "envOverride")
+ isInternal := slices.Contains(attrs, "internal")
+ if !hasEnvOverride && isInternal {
+ continue
+ }
+
+ defaultValue, isPublic, isSensitive, err := defaults.FieldByKey(key)
+ if err != nil {
+ return nil, fmt.Errorf("lookup default value for %q: %w", key, err)
+ }
+ if isSensitive {
+ defaultValue = ""
+ }
+
+ meta := utils.ParseMetaTag(field.Tag.Get("meta"))
+ rule := overrideDocRules[key]
+ requires := rule.requires
+ if !hasEnvOverride {
+ requires = joinRequirementsInternal(
+ "AGENT_MODE=true or UI_CONFIGURATION_DISABLED=true to manage this setting via env.",
+ requires,
+ )
+ }
+
+ entries = append(entries, SettingOverrideEntry{
+ Env: utils.CamelCaseToScreamingSnakeCase(key),
+ SettingKey: key,
+ Description: meta["description"],
+ DefaultValue: defaultValue,
+ Type: defaultStringInternal(meta["type"], "text"),
+ Sensitive: isSensitive,
+ Deprecated: rule.deprecated || slices.Contains(attrs, "deprecated"),
+ Category: meta["category"],
+ Public: isPublic,
+ Requires: requires,
+ Note: rule.note,
+ Source: "models.Settings + services.DefaultSettingsConfig",
+ SourceFile: sourceFileSettings,
+ SourceSymbol: "models.Settings." + field.Name,
+ })
+ }
+
+ sort.Slice(entries, func(i, j int) bool {
+ if entries[i].Category == entries[j].Category {
+ return entries[i].Env < entries[j].Env
+ }
+ return entries[i].Category < entries[j].Category
+ })
+
+ return entries, nil
+}
+
+func findStructTypeInternal(file *ast.File, structName string) (*ast.StructType, error) {
+ for _, decl := range file.Decls {
+ genDecl, ok := decl.(*ast.GenDecl)
+ if !ok || genDecl.Tok != token.TYPE {
+ continue
+ }
+
+ for _, spec := range genDecl.Specs {
+ typeSpec, ok := spec.(*ast.TypeSpec)
+ if !ok || typeSpec.Name.Name != structName {
+ continue
+ }
+
+ structType, ok := typeSpec.Type.(*ast.StructType)
+ if !ok {
+ return nil, fmt.Errorf("%s is not a struct", structName)
+ }
+
+ return structType, nil
+ }
+ }
+
+ return nil, fmt.Errorf("struct %s not found", structName)
+}
+
+func exprStringInternal(expr ast.Expr) (string, error) {
+ var buf bytes.Buffer
+ if err := format.Node(&buf, token.NewFileSet(), expr); err != nil {
+ return "", err
+ }
+ return buf.String(), nil
+}
+
+func splitTagListInternal(value string) []string {
+ if value == "" {
+ return nil
+ }
+
+ parts := strings.Split(value, ",")
+ result := make([]string, 0, len(parts))
+ for _, part := range parts {
+ trimmed := strings.TrimSpace(part)
+ if trimmed == "" {
+ continue
+ }
+ result = append(result, trimmed)
+ }
+
+ return result
+}
+
+func normalizeCommentInternal(comment string) string {
+ return strings.TrimSpace(strings.Join(strings.Fields(comment), " "))
+}
+
+func joinRequirementsInternal(parts ...string) string {
+ filtered := make([]string, 0, len(parts))
+ for _, part := range parts {
+ part = strings.TrimSpace(part)
+ if part == "" {
+ continue
+ }
+ filtered = append(filtered, part)
+ }
+
+ return strings.Join(filtered, " ")
+}
+
+func defaultStringInternal(value, fallback string) string {
+ if strings.TrimSpace(value) == "" {
+ return fallback
+ }
+ return value
+}
+
+func resolveSourceRootInternal(sourceRoot string) (string, error) {
+ candidates := make([]string, 0, 2)
+ if strings.TrimSpace(sourceRoot) != "" {
+ candidates = append(candidates, sourceRoot)
+ } else {
+ wd, err := os.Getwd()
+ if err != nil {
+ return "", fmt.Errorf("get working directory: %w", err)
+ }
+ candidates = append(candidates, wd)
+ }
+
+ for _, candidate := range candidates {
+ resolved, err := resolveSourceRootCandidateInternal(candidate)
+ if err == nil {
+ return resolved, nil
+ }
+ }
+
+ if strings.TrimSpace(sourceRoot) != "" {
+ return "", fmt.Errorf("resolve source root from %q: expected backend/internal/config/config.go", sourceRoot)
+ }
+
+ return "", fmt.Errorf("resolve source root: run from the repository root/backend directory or pass --source-root")
+}
+
+func resolveSourceRootCandidateInternal(candidate string) (string, error) {
+ candidate, err := filepath.Abs(candidate)
+ if err != nil {
+ return "", fmt.Errorf("abs path for %q: %w", candidate, err)
+ }
+
+ for current := candidate; ; current = filepath.Dir(current) {
+ if hasSchemaSourceFilesInternal(current) {
+ return current, nil
+ }
+
+ backendRoot := filepath.Join(current, "backend")
+ if hasSchemaSourceFilesInternal(backendRoot) {
+ return backendRoot, nil
+ }
+
+ parent := filepath.Dir(current)
+ if parent == current {
+ break
+ }
+ }
+
+ return "", fmt.Errorf("schema sources not found from %q", candidate)
+}
+
+func hasSchemaSourceFilesInternal(root string) bool {
+ required := []string{
+ filepath.Join(root, "internal/config/config.go"),
+ filepath.Join(root, "internal/config/buildables_config.go"),
+ }
+
+ for _, filename := range required {
+ if _, err := os.Stat(filename); err != nil {
+ return false
+ }
+ }
+
+ return true
+}
diff --git a/backend/internal/configschema/schema_test.go b/backend/internal/configschema/schema_test.go
new file mode 100644
index 000000000..58657c04c
--- /dev/null
+++ b/backend/internal/configschema/schema_test.go
@@ -0,0 +1,333 @@
+package configschema
+
+import (
+ "reflect"
+ "slices"
+ "sort"
+ "strings"
+ "testing"
+
+ "github.com/getarcaneapp/arcane/backend/internal/models"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestGenerate_EnvConfigIncludesTaggedFields(t *testing.T) {
+ doc, err := GenerateWithSourceRoot("")
+ require.NoError(t, err)
+
+ assert.Equal(t, expectedEnvConfigVars, envNames(doc.EnvConfig))
+
+ entries := mapEnvEntries(doc.EnvConfig)
+
+ appURL, ok := entries["APP_URL"]
+ require.True(t, ok)
+ assert.Equal(t, "AppUrl", appURL.Field)
+ assert.Equal(t, "string", appURL.Type)
+ assert.Equal(t, "http://localhost:3552", appURL.DefaultValue)
+ assert.Equal(t, "config.Config", appURL.Source)
+ assert.Equal(t, sourceFileConfig, appURL.SourceFile)
+
+ encryptionKey, ok := entries["ENCRYPTION_KEY"]
+ require.True(t, ok)
+ assert.True(t, encryptionKey.SupportsFile)
+ assert.Contains(t, encryptionKey.Options, "file")
+
+ buildableUsername, ok := entries["AUTO_LOGIN_USERNAME"]
+ require.True(t, ok)
+ assert.True(t, buildableUsername.Conditional)
+ assert.Equal(t, []string{"buildables"}, buildableUsername.BuildTags)
+ assert.Equal(t, sourceFileBuildablesConfig, buildableUsername.SourceFile)
+ assert.Equal(t, "config.BuildablesConfig", buildableUsername.Source)
+}
+
+func TestGenerate_SettingEnvOverridesMatchModelMetadata(t *testing.T) {
+ doc, err := GenerateWithSourceRoot("")
+ require.NoError(t, err)
+
+ expectedCount := countDocumentedSettingOverrides()
+ assert.Len(t, doc.SettingEnvOverrides, expectedCount)
+ assert.Equal(t, expectedSettingOverrideKeys, sortedSettingKeys(doc.SettingEnvOverrides))
+
+ entries := mapSettingOverrideEntries(doc.SettingEnvOverrides)
+
+ dockerTimeout, ok := entries["dockerApiTimeout"]
+ require.True(t, ok)
+ assert.Equal(t, "DOCKER_API_TIMEOUT", dockerTimeout.Env)
+ assert.Equal(t, "30", dockerTimeout.DefaultValue)
+ assert.Equal(t, "number", dockerTimeout.Type)
+ assert.Equal(t, "timeouts", dockerTimeout.Category)
+ assert.Equal(t, "models.Settings + services.DefaultSettingsConfig", dockerTimeout.Source)
+
+ oidcSecret, ok := entries["oidcClientSecret"]
+ require.True(t, ok)
+ assert.True(t, oidcSecret.Sensitive)
+ assert.Equal(t, "OIDC_CLIENT_SECRET", oidcSecret.Env)
+
+ legacyOIDC, ok := entries["authOidcConfig"]
+ require.True(t, ok)
+ assert.True(t, legacyOIDC.Deprecated)
+ assert.NotEmpty(t, legacyOIDC.Note)
+ assert.Contains(t, legacyOIDC.Requires, "AGENT_MODE=true")
+ assert.Empty(t, legacyOIDC.DefaultValue)
+
+ trivyImage, ok := entries["trivyImage"]
+ require.True(t, ok)
+ assert.Contains(t, trivyImage.Requires, "UI_CONFIGURATION_DISABLED=true")
+
+ assert.Empty(t, oidcSecret.DefaultValue)
+
+ _, hasRuntimeDerived := entries["uiConfigDisabled"]
+ assert.False(t, hasRuntimeDerived)
+}
+
+func TestGenerate_DocumentIncludesEnvOnlyModeNote(t *testing.T) {
+ doc, err := GenerateWithSourceRoot("")
+ require.NoError(t, err)
+
+ notes := strings.Join(doc.Notes, " ")
+ assert.Contains(t, notes, "AGENT_MODE=true")
+ assert.Contains(t, notes, "UI_CONFIGURATION_DISABLED=true")
+}
+
+func TestGenerate_OutputOrderingIsStable(t *testing.T) {
+ doc, err := GenerateWithSourceRoot("")
+ require.NoError(t, err)
+
+ assert.Equal(t, envNames(doc.EnvConfig), sortedStrings(envNames(doc.EnvConfig)))
+ assert.Equal(t, categoriesThenEnv(doc.SettingEnvOverrides), sortedCategoryEnvPairs(doc.SettingEnvOverrides))
+}
+
+func mapEnvEntries(entries []ConfigEntry) map[string]ConfigEntry {
+ result := make(map[string]ConfigEntry, len(entries))
+ for _, entry := range entries {
+ result[entry.Env] = entry
+ }
+ return result
+}
+
+func mapSettingOverrideEntries(entries []SettingOverrideEntry) map[string]SettingOverrideEntry {
+ result := make(map[string]SettingOverrideEntry, len(entries))
+ for _, entry := range entries {
+ result[entry.SettingKey] = entry
+ }
+ return result
+}
+
+func envNames(entries []ConfigEntry) []string {
+ result := make([]string, 0, len(entries))
+ for _, entry := range entries {
+ result = append(result, entry.Env)
+ }
+ return result
+}
+
+func sortedSettingKeys(entries []SettingOverrideEntry) []string {
+ result := make([]string, 0, len(entries))
+ for _, entry := range entries {
+ result = append(result, entry.SettingKey)
+ }
+ sort.Strings(result)
+ return result
+}
+
+func sortedStrings(values []string) []string {
+ result := append([]string(nil), values...)
+ sort.Strings(result)
+ return result
+}
+
+func categoriesThenEnv(entries []SettingOverrideEntry) []string {
+ result := make([]string, 0, len(entries))
+ for _, entry := range entries {
+ result = append(result, entry.Category+"|"+entry.Env)
+ }
+ return result
+}
+
+func sortedCategoryEnvPairs(entries []SettingOverrideEntry) []string {
+ copied := append([]SettingOverrideEntry(nil), entries...)
+ sort.Slice(copied, func(i, j int) bool {
+ if copied[i].Category == copied[j].Category {
+ return copied[i].Env < copied[j].Env
+ }
+ return copied[i].Category < copied[j].Category
+ })
+
+ result := make([]string, 0, len(copied))
+ for _, entry := range copied {
+ result = append(result, entry.Category+"|"+entry.Env)
+ }
+ return result
+}
+
+func countDocumentedSettingOverrides() int {
+ settingsType := reflect.TypeFor[models.Settings]()
+ count := 0
+
+ for field := range settingsType.Fields() {
+ keyTag := field.Tag.Get("key")
+ if keyTag == "" {
+ continue
+ }
+
+ tagParts := splitTagListInternal(keyTag)
+ if len(tagParts) == 0 {
+ continue
+ }
+
+ attrs := tagParts[1:]
+ if slices.Contains(attrs, "envOverride") || !slices.Contains(attrs, "internal") {
+ count++
+ }
+ }
+
+ return count
+}
+
+var expectedEnvConfigVars = []string{
+ "ADMIN_STATIC_API_KEY",
+ "AGENT_MODE",
+ "AGENT_TOKEN",
+ "ALLOW_DOWNGRADE",
+ "ANALYTICS_DISABLED",
+ "APP_URL",
+ "ARCANE_BACKUP_VOLUME_NAME",
+ "AUTO_LOGIN_PASSWORD",
+ "AUTO_LOGIN_USERNAME",
+ "DATABASE_URL",
+ "DIR_PERM",
+ "DOCKER_API_TIMEOUT",
+ "DOCKER_HOST",
+ "DOCKER_IMAGE_PULL_TIMEOUT",
+ "EDGE_AGENT",
+ "EDGE_RECONNECT_INTERVAL",
+ "EDGE_TRANSPORT",
+ "ENCRYPTION_KEY",
+ "ENVIRONMENT",
+ "FILE_PERM",
+ "GIT_OPERATION_TIMEOUT",
+ "GIT_WORK_DIR",
+ "GPU_MONITORING_ENABLED",
+ "GPU_TYPE",
+ "HTTP_CLIENT_TIMEOUT",
+ "JWT_REFRESH_EXPIRY",
+ "JWT_SECRET",
+ "LISTEN",
+ "LOG_JSON",
+ "LOG_LEVEL",
+ "MANAGER_API_URL",
+ "OIDC_ADMIN_CLAIM",
+ "OIDC_ADMIN_VALUE",
+ "OIDC_AUTO_REDIRECT_TO_PROVIDER",
+ "OIDC_CLIENT_ID",
+ "OIDC_CLIENT_SECRET",
+ "OIDC_ENABLED",
+ "OIDC_ISSUER_URL",
+ "OIDC_PROVIDER_LOGO_URL",
+ "OIDC_PROVIDER_NAME",
+ "OIDC_SCOPES",
+ "OIDC_SKIP_TLS_VERIFY",
+ "PORT",
+ "PROJECTS_DIRECTORY",
+ "PROXY_REQUEST_TIMEOUT",
+ "REGISTRY_TIMEOUT",
+ "TLS_CERT_FILE",
+ "TLS_ENABLED",
+ "TLS_KEY_FILE",
+ "TRIVY_SCAN_TIMEOUT",
+ "TZ",
+ "UI_CONFIGURATION_DISABLED",
+ "UPDATE_CHECK_DISABLED",
+}
+
+var expectedSettingOverrideKeys = []string{
+ "accentColor",
+ "applicationTheme",
+ "authLocalEnabled",
+ "authOidcConfig",
+ "authPasswordPolicy",
+ "authSessionTimeout",
+ "autoHealEnabled",
+ "autoHealExcludedContainers",
+ "autoHealInterval",
+ "autoHealMaxRestarts",
+ "autoHealRestartWindow",
+ "autoInjectEnv",
+ "autoUpdate",
+ "autoUpdateExcludedContainers",
+ "autoUpdateInterval",
+ "baseServerUrl",
+ "buildProvider",
+ "buildTimeout",
+ "buildsDirectory",
+ "defaultDeployPullPolicy",
+ "defaultShell",
+ "depotProjectId",
+ "depotToken",
+ "diskUsagePath",
+ "dockerApiTimeout",
+ "dockerHost",
+ "dockerImagePullTimeout",
+ "dockerPruneMode",
+ "enableGravatar",
+ "environmentHealthInterval",
+ "eventCleanupInterval",
+ "followProjectSymlinks",
+ "gitOperationTimeout",
+ "gitSyncMaxBinarySizeMb",
+ "gitSyncMaxFiles",
+ "gitSyncMaxTotalSizeMb",
+ "gitopsSyncInterval",
+ "httpClientTimeout",
+ "keyboardShortcutsEnabled",
+ "maxImageUploadSize",
+ "mobileNavigationMode",
+ "mobileNavigationShowLabels",
+ "oidcAdminClaim",
+ "oidcAdminValue",
+ "oidcAuthorizationEndpoint",
+ "oidcAutoRedirectToProvider",
+ "oidcClientId",
+ "oidcClientSecret",
+ "oidcDeviceAuthorizationEndpoint",
+ "oidcEnabled",
+ "oidcIssuerUrl",
+ "oidcJwksEndpoint",
+ "oidcMergeAccounts",
+ "oidcProviderLogoUrl",
+ "oidcProviderName",
+ "oidcScopes",
+ "oidcSkipTlsVerify",
+ "oidcTokenEndpoint",
+ "oidcUserinfoEndpoint",
+ "oledMode",
+ "pollingEnabled",
+ "pollingInterval",
+ "projectsDirectory",
+ "proxyRequestTimeout",
+ "registryTimeout",
+ "scheduledPruneBuildCache",
+ "scheduledPruneContainers",
+ "scheduledPruneEnabled",
+ "scheduledPruneImages",
+ "scheduledPruneInterval",
+ "scheduledPruneNetworks",
+ "scheduledPruneVolumes",
+ "sidebarHoverExpansion",
+ "swarmStackSourcesDirectory",
+ "trivyConcurrentScanContainers",
+ "trivyConfig",
+ "trivyCpuLimit",
+ "trivyIgnore",
+ "trivyImage",
+ "trivyMemoryLimitMb",
+ "trivyNetwork",
+ "trivyPreserveCacheOnVolumePrune",
+ "trivyPrivileged",
+ "trivyResourceLimitsEnabled",
+ "trivyScanTimeout",
+ "trivySecurityOpts",
+ "vulnerabilityScanEnabled",
+ "vulnerabilityScanInterval",
+}
diff --git a/backend/internal/services/settings_service.go b/backend/internal/services/settings_service.go
index de874bd05..49b01ef6f 100644
--- a/backend/internal/services/settings_service.go
+++ b/backend/internal/services/settings_service.go
@@ -89,6 +89,11 @@ func (s *SettingsService) refreshSettingsCacheInternal(ctx context.Context) erro
}
func (s *SettingsService) getDefaultSettings() *models.Settings {
+ return DefaultSettingsConfig()
+}
+
+// DefaultSettingsConfig returns the canonical default settings model used by Arcane.
+func DefaultSettingsConfig() *models.Settings {
return &models.Settings{
ProjectsDirectory: models.SettingVariable{Value: "/app/data/projects"},
FollowProjectSymlinks: models.SettingVariable{Value: "false"},