Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
package settings
import (
"context"
"crypto/mldsa"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"errors"
"fmt"
"log/slog"
"os"
"path/filepath"
"reflect"
"slices"
"strconv"
"strings"
"sync"
"sync/atomic"
"time"
"uuid"
"github.com/getarcaneapp/arcane/types/v2/base"
"github.com/getarcaneapp/arcane/types/v2/category"
"github.com/getarcaneapp/arcane/types/v2/features"
searchtypes "github.com/getarcaneapp/arcane/types/v2/search"
"github.com/getarcaneapp/arcane/types/v2/settings"
"github.com/samber/mo"
"go.getarcane.app/kit/normalization"
"go.getarcane.app/kit/pkg"
"go.getarcane.app/sys/crypto"
"gorm.io/gorm"
"github.com/getarcaneapp/arcane/backend/v2/internal/common"
"github.com/getarcaneapp/arcane/backend/v2/internal/config"
"github.com/getarcaneapp/arcane/backend/v2/internal/database"
"github.com/getarcaneapp/arcane/backend/v2/internal/search"
"github.com/getarcaneapp/arcane/backend/v2/pkg/libarcane"
"github.com/getarcaneapp/arcane/backend/v2/pkg/projects"
"github.com/getarcaneapp/arcane/backend/v2/pkg/scheduler/schedule"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils/concurrency"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils/httpx"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils/imageref"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils/validation"
)
const (
browserSessionSigningKeySize = 64
minCiphertextBytes = 28
sensitiveSettingsEncryptedKey = "sensitiveSettingsEncrypted"
)
type SettingsService struct {
db *database.DB
appConfig *config.Config
config atomic.Pointer[Settings]
// effectiveConfig is the shared, read-only env-override-applied snapshot,
// rebuilt whenever config is stored so reads are a pointer load.
effectiveConfig atomic.Pointer[Settings]
envOverrides []settingsEnvOverride
writes sync.Mutex
effectsMu sync.Mutex
effects []func()
effectsWake chan struct{}
effectsDone chan struct{}
effectsClosed bool
lifecycleCtx context.Context
changes *concurrency.Signal[[]libarcane.SettingUpdate]
}
type settingsEnvOverride struct {
fieldIndex int
key string
value string
}
func NewSettingsService(ctx context.Context, db *database.DB, appConfig *config.Config) (*SettingsService, error) {
if ctx == nil {
return nil, errors.New("settings lifecycle context unavailable")
}
svc := &SettingsService{
db: db,
appConfig: appConfig,
effectsWake: make(chan struct{}, 1),
effectsDone: make(chan struct{}),
lifecycleCtx: ctx,
changes: concurrency.NewSignal[[]libarcane.SettingUpdate](),
}
fields, _ := getSettingsFieldCacheInternal()
for _, field := range fields {
if !slices.Contains(splitSettingAttrsInternal(field.attrs), "envOverride") {
continue
}
if val, ok, _ := utils.LookupEnvOrFile(settingEnvName(field.key)); ok && val != "" {
svc.envOverrides = append(svc.envOverrides, settingsEnvOverride{fieldIndex: field.index, key: field.key, value: kit.TrimQuotes(val)})
}
}
if len(svc.envOverrides) > 0 {
slog.InfoContext(ctx, "Loaded Environment Settings Overrides", "count", len(svc.envOverrides))
}
if _, err := EnsureInstanceID(ctx, db); err != nil {
return nil, fmt.Errorf("failed to setup instance ID: %w", err)
}
if err := svc.LoadDatabaseSettings(ctx); err != nil {
return nil, fmt.Errorf("failed to load settings: %w", err)
}
go func() {
defer close(svc.effectsDone)
for {
svc.effectsMu.Lock()
if len(svc.effects) > 0 {
effect := svc.effects[0]
svc.effects[0] = nil
svc.effects = svc.effects[1:]
svc.effectsMu.Unlock()
func() { defer utils.RecoverToError(nil, "settings effect"); effect() }()
continue
}
closed := svc.effectsClosed
svc.effectsMu.Unlock()
if closed {
return
}
select {
case <-svc.effectsWake:
case <-svc.lifecycleCtx.Done():
svc.effectsMu.Lock()
svc.effectsClosed = true
svc.effectsMu.Unlock()
}
}
}()
return svc, nil
}
// SubscribeSettingsChanges invokes callback once with the matching values when any subscribed key
// is present in a successful update. Callbacks run serially on the effects worker, outside the write mutex.
func (s *SettingsService) SubscribeSettingsChanges(keys []string, callback func([]libarcane.SettingUpdate)) func() {
if callback == nil || len(keys) == 0 {
return func() {}
}
subscribed := make(map[string]struct{}, len(keys))
for _, key := range keys {
subscribed[key] = struct{}{}
}
return s.changes.Subscribe(func(updates []libarcane.SettingUpdate) {
matching := make([]libarcane.SettingUpdate, 0, len(updates))
for _, update := range updates {
if _, ok := subscribed[update.Key]; ok {
matching = append(matching, update)
}
}
if len(matching) > 0 {
if err := s.enqueueEffect(func() { callback(matching) }); err != nil && s.lifecycleCtx.Err() == nil {
slog.ErrorContext(s.lifecycleCtx, "Failed to queue settings change effects", "error", err)
}
}
})
}
// NotifySettingsChanges publishes current values for keys through the settings
// write mutex. It is used when another settings-table workflow performs persistence.
func (s *SettingsService) NotifySettingsChanges(ctx context.Context, keys ...string) error {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
updates := make([]libarcane.SettingUpdate, 0, len(keys))
cfg := s.GetSettingsConfig()
for _, key := range keys {
value, _, _, err := cfg.FieldByKey(key)
if err != nil {
return fmt.Errorf("load changed setting '%s': %w", key, err)
}
updates = append(updates, libarcane.SettingUpdate{Key: key, Value: value})
}
s.publishSettingsChanges(updates)
return nil
}
func (s *SettingsService) GetSettingsConfig() *Settings {
v := s.config.Load()
if v == nil {
panic("GetSettingsConfig called before Settings has been loaded")
}
return v
}
func (s *SettingsService) LoadDatabaseSettings(ctx context.Context) error {
var stored []SettingVariable
queryCtx, queryCancel := context.WithTimeout(ctx, 10*time.Second)
defer queryCancel()
if err := s.db.WithContext(queryCtx).Find(&stored).Error; err != nil {
return fmt.Errorf("failed to load configuration from the database: %w", err)
}
dst := DefaultSettingsConfig()
fields, byKey := getSettingsFieldCacheInternal()
for i := range stored {
if !byKey[stored[i].Key].isEncrypted || stored[i].Value == "" {
continue
}
plain, decryptErr := crypto.Decrypt(stored[i].Value)
switch {
case decryptErr == nil:
stored[i].Value = plain
case looksLikeCiphertext(stored[i].Value, decryptErr):
slog.WarnContext(ctx, "Failed to decrypt stored sensitive setting with the current encryption key", "key", stored[i].Key)
}
}
rv := reflect.ValueOf(dst).Elem()
if s.appConfig.UIConfigurationDisabled || s.appConfig.AgentMode {
slog.DebugContext(ctx, "LoadDatabaseSettings: using env path",
"uiConfigurationDisabled", s.appConfig.UIConfigurationDisabled, "agentMode", s.appConfig.AgentMode, "environment", s.appConfig.Environment)
storedValues := make(map[string]string, len(stored))
for _, setting := range stored {
storedValues[setting.Key] = setting.Value
}
for _, field := range fields {
value := rv.Field(field.index).FieldByName("Value")
if slices.Contains(splitSettingAttrsInternal(field.attrs), "internal") {
if val, ok := storedValues[field.key]; ok {
value.SetString(val)
}
continue
}
envVarName := settingEnvName(field.key)
if val, ok, _ := utils.LookupEnvOrFile(envVarName); ok {
mask := kit.Ternary(val == "", "<empty>", fmt.Sprintf("%d chars", len(val)))
slog.DebugContext(ctx, "LoadDatabaseSettings: env override found", "key", field.key, "env", envVarName, "valueMasked", mask)
value.SetString(kit.TrimQuotes(val))
continue
}
if val, ok := storedValues[field.key]; ok {
slog.DebugContext(ctx, "LoadDatabaseSettings: using database fallback", "key", field.key)
value.SetString(val)
continue
}
slog.DebugContext(ctx, "LoadDatabaseSettings: env not set and no database value", "key", field.key, "env", envVarName)
}
count := 0
for _, field := range fields {
if rv.Field(field.index).FieldByName("Value").String() != "" {
count++
}
}
slog.DebugContext(ctx, "LoadDatabaseSettings: completed env load", "loadedFields", count)
} else {
for _, setting := range stored {
if err := dst.UpdateField(setting.Key, setting.Value, false); err != nil && !errors.Is(err, SettingKeyNotFoundError{}) {
return fmt.Errorf("failed to process settings for key '%s': %w", setting.Key, err)
}
}
s.applyEnvOverrides(dst)
}
s.config.Store(dst)
effective := dst.Clone()
s.applyEnvOverrides(effective)
s.effectiveConfig.Store(effective)
return nil
}
// DefaultSettingsConfig returns the canonical default settings model used by Arcane.
func DefaultSettingsConfig() *Settings {
return &Settings{
ProjectsDirectory: SettingVariable{Value: "/app/data/projects"},
TemplatesDirectory: SettingVariable{Value: "/app/data/templates"},
FollowProjectSymlinks: SettingVariable{Value: "false"},
SwarmStackSourcesDirectory: SettingVariable{Value: "/app/data/swarm/sources"},
DiskUsagePath: SettingVariable{Value: "/app/data/projects"},
AutoUpdate: SettingVariable{Value: "false"},
AutoUpdateInterval: SettingVariable{Value: "0 0 0 * * *"},
AutoUpdateDelay: SettingVariable{Value: "0"},
AutoUpdateExcludedContainers: SettingVariable{Value: ""},
PollingEnabled: SettingVariable{Value: "true"},
PollingInterval: SettingVariable{Value: "0 0 * * * *"},
ImageEventWatcherEnabled: SettingVariable{Value: "false"},
DockerClientRefreshInterval: SettingVariable{Value: "0 */5 * * * *"},
EventCleanupInterval: SettingVariable{Value: "0 0 */6 * * *"},
ExpiredSessionsCleanupInterval: SettingVariable{Value: "0 0 0 * * *"},
ActivityHistoryRetentionDays: SettingVariable{Value: "30"},
UpgradeLogRetentionDays: SettingVariable{Value: "3"},
ActivityHistoryMaxEntries: SettingVariable{Value: "1000"},
MaxConcurrentActivities: SettingVariable{Value: "5"},
AutoInjectEnv: SettingVariable{Value: "false"},
DefaultDeployPullPolicy: SettingVariable{Value: "missing"},
ToolsImageRegistry: SettingVariable{Value: "ghcr.io"},
UpdateCheckRegistry: SettingVariable{Value: "auto"},
ScheduledPruneEnabled: SettingVariable{Value: "false"},
ScheduledPruneInterval: SettingVariable{Value: "0 0 0 * * *"},
PruneContainerMode: SettingVariable{Value: "stopped"},
PruneContainerUntil: SettingVariable{Value: ""},
PruneImageMode: SettingVariable{Value: "dangling"},
PruneImageUntil: SettingVariable{Value: ""},
PruneVolumeMode: SettingVariable{Value: "none"},
PruneNetworkMode: SettingVariable{Value: "unused"},
PruneNetworkUntil: SettingVariable{Value: ""},
PruneBuildCacheMode: SettingVariable{Value: "none"},
PruneBuildCacheUntil: SettingVariable{Value: ""},
AutoHealEnabled: SettingVariable{Value: "false"},
AutoHealInterval: SettingVariable{Value: "0 */5 * * * *"},
AutoHealExcludedContainers: SettingVariable{Value: ""},
AutoHealMaxRestarts: SettingVariable{Value: "5"},
AutoHealRestartWindow: SettingVariable{Value: "30"},
VolumeHelperIdleTimeout: SettingVariable{Value: "10"},
BaseServerURL: SettingVariable{Value: "http://localhost"},
EnableGravatar: SettingVariable{Value: "false"},
ExperimentalFeaturesEnabled: SettingVariable{Value: "false"},
DevelopmentBrandingEnabled: SettingVariable{Value: "true"},
AvatarMaxUploadSizeMb: SettingVariable{Value: "2"},
AllEnvironmentsLimit: SettingVariable{Value: "64"},
DefaultShell: SettingVariable{Value: "/bin/sh"},
DockerHost: SettingVariable{Value: "unix:///var/run/docker.sock"},
BuildsDirectory: SettingVariable{Value: "/builds"},
AuthLocalEnabled: SettingVariable{Value: "true"},
AuthSessionTimeout: SettingVariable{Value: "1440"},
AuthPasswordPolicy: SettingVariable{Value: "strong"},
FeatureVulnerabilityManagementEnabled: SettingVariable{Value: "true"},
FeatureSwarmEnabled: SettingVariable{Value: "false"},
VulnerabilityScanEnabled: SettingVariable{Value: "false"},
VulnerabilityScanInterval: SettingVariable{Value: "0 0 0 * * *"},
VulnerabilityThreatIntelEnabled: SettingVariable{Value: "true"},
TrivyDbRegistry: SettingVariable{Value: "ghcr.io"},
TrivyNetwork: SettingVariable{Value: ""},
TrivySecurityOpts: SettingVariable{Value: ""},
TrivyPrivileged: SettingVariable{Value: "false"},
TrivyResourceLimitsEnabled: SettingVariable{Value: "true"},
TrivyCpuLimit: SettingVariable{Value: "1"},
TrivyMemoryLimitMb: SettingVariable{Value: "0"},
TrivyConcurrentScanContainers: SettingVariable{Value: "1"},
TrivyServerEnabled: SettingVariable{Value: "false"},
TrivyServerUrl: SettingVariable{Value: ""},
TrivyServerToken: SettingVariable{Value: ""},
TrivyIgnoreUnfixed: SettingVariable{Value: "true"},
OidcEnabled: SettingVariable{Value: "false"},
OidcClientId: SettingVariable{Value: ""},
OidcClientSecret: SettingVariable{Value: ""},
OidcIssuerUrl: SettingVariable{Value: ""},
OidcAuthorizationEndpoint: SettingVariable{Value: ""},
OidcTokenEndpoint: SettingVariable{Value: ""},
OidcUserinfoEndpoint: SettingVariable{Value: ""},
OidcJwksEndpoint: SettingVariable{Value: ""},
OidcScopes: SettingVariable{Value: "openid email profile"},
OidcGroupsClaim: SettingVariable{Value: "groups"},
OidcSkipTlsVerify: SettingVariable{Value: "false"},
OidcAutoRedirectToProvider: SettingVariable{Value: "false"},
OidcMergeAccounts: SettingVariable{Value: "false"},
OidcProviderName: SettingVariable{Value: ""},
OidcProviderLogoUrl: SettingVariable{Value: ""},
OidcMobileRedirectUris: SettingVariable{Value: "arcane-mobile://oidc-callback"},
MaxImageUploadSize: SettingVariable{Value: "500"},
GitSyncMaxFiles: SettingVariable{Value: "500"},
GitSyncMaxTotalSizeMb: SettingVariable{Value: "50"},
GitSyncMaxBinarySizeMb: SettingVariable{Value: "10"},
EnvironmentHealthInterval: SettingVariable{Value: "0 */2 * * * *"},
LifecycleEnabled: SettingVariable{Value: "false"},
LifecycleDefaultRunnerImage: SettingVariable{Value: "alpine:latest"},
LifecycleMaxTimeoutSec: SettingVariable{Value: "300"},
DockerAPITimeout: SettingVariable{Value: "30"},
DockerImagePullTimeout: SettingVariable{Value: "600"},
TrivyScanTimeout: SettingVariable{Value: "900"},
ImagePatchSuffix: SettingVariable{Value: "patched"},
ImagePatchTimeoutSec: SettingVariable{Value: "600"},
ImagePatchAllPlatforms: SettingVariable{Value: "false"},
ImageAutoPatchEnabled: SettingVariable{Value: "false"},
ImageAutoPatchInterval: SettingVariable{Value: "0 0 3 * * *"},
GitOperationTimeout: SettingVariable{Value: "300"},
HTTPClientTimeout: SettingVariable{Value: "30"},
RegistryTimeout: SettingVariable{Value: "30"},
RegistryTagTimeout: SettingVariable{Value: "120"},
ProxyRequestTimeout: SettingVariable{Value: "60"},
DeployWaitTimeout: SettingVariable{Value: "600"},
BuildProvider: SettingVariable{Value: "local"},
BuildTimeout: SettingVariable{Value: "1800"},
BuildHistoryRetentionDays: SettingVariable{Value: "30"},
DepotProjectId: SettingVariable{Value: ""},
DepotToken: SettingVariable{Value: ""},
ApnsEnabled: SettingVariable{Value: "false"},
ApnsChannelID: SettingVariable{Value: ""},
ApnsSigningKey: SettingVariable{Value: ""},
InstanceID: SettingVariable{Value: ""},
SystemVolumeBackupConfig: SettingVariable{Value: `{"policies":[]}`},
}
}
func (s *SettingsService) applyEnvOverrides(dest *Settings) {
rv := reflect.ValueOf(dest).Elem()
for _, override := range s.envOverrides {
rv.Field(override.fieldIndex).FieldByName("Value").SetString(override.value)
}
}
// IsEnvOverrideActive reports whether a non-empty environment override controls the setting.
func (s *SettingsService) IsEnvOverrideActive(key string) bool {
return slices.ContainsFunc(s.envOverrides, func(override settingsEnvOverride) bool { return override.key == key })
}
// GetSettings returns the shared, read-only effective (env-override-applied) settings snapshot.
// Mutation flows go through UpdateSettings, which works on an explicit clone.
func (s *SettingsService) GetSettings(_ context.Context) (*Settings, error) {
if effective := s.effectiveConfig.Load(); effective != nil {
return effective, nil
}
// Only reachable before LoadDatabaseSettings has completed in the
// constructor; fall back to building the snapshot per call.
settingsCfg := s.GetSettingsConfig().Clone()
s.applyEnvOverrides(settingsCfg)
return settingsCfg, nil
}
// GetSettingsOrDefaults logs any settings load failure and always returns a non-nil *Settings;
// a zero-valued struct makes SettingVariable helpers fall back to the caller's default.
func (s *SettingsService) GetSettingsOrDefaults(ctx context.Context) *Settings {
cfg, err := s.GetSettings(ctx)
if err != nil {
slog.WarnContext(ctx, "failed to load settings, falling back to defaults", "error", err)
}
return kit.Ternary(cfg == nil, &Settings{}, cfg)
}
func validateSettingValue(key, value string) error {
if key == "upgradeLogRetentionDays" && value != "" {
days, err := strconv.Atoi(value)
if err != nil || days < 0 || days > 3650 {
return common.Classify(common.ErrValidation, errors.New("upgradeLogRetentionDays must be a whole number between 0 and 3650"))
}
}
if key == "autoUpdateDelay" && value != "" {
hours, err := strconv.Atoi(value)
if err != nil || hours < 0 || hours > imageref.MaxUpdateDelayHours {
return common.Classify(common.ErrValidation, fmt.Errorf("autoUpdateDelay must be a whole number between 0 and %d", imageref.MaxUpdateDelayHours))
}
}
if key == "allEnvironmentsLimit" {
limit, err := strconv.Atoi(value)
if err != nil || limit < 2 || limit > 256 {
return common.Classify(common.ErrValidation, errors.New("allEnvironmentsLimit must be a whole number between 2 and 256"))
}
}
for _, definition := range features.All() {
if definition.SettingKey == key && value != "true" && value != "false" {
return common.Classify(common.ErrValidation, fmt.Errorf("%s must be true or false", key))
}
}
return nil
}
func (s *SettingsService) UpdateSetting(ctx context.Context, key, value string) error {
if err := validateSettingValue(key, value); err != nil {
return err
}
if err := libarcane.ValidateCronSetting(key, value); err != nil {
return fmt.Errorf("invalid cron expression for %s: %w", key, err)
}
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
return s.persistSettings(ctx, []SettingVariable{{Key: key, Value: value}})
}
// UpdateSettingValues persists a group of internal setting values atomically
// and publishes the refreshed snapshot before returning.
func (s *SettingsService) UpdateSettingValues(ctx context.Context, updates []libarcane.SettingUpdate) error {
values := make([]SettingVariable, 0, len(updates))
for _, update := range updates {
if err := validateSettingValue(update.Key, update.Value); err != nil {
return err
}
values = append(values, SettingVariable{Key: update.Key, Value: update.Value})
}
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
return s.persistSettings(ctx, values)
}
// UpdateSettings publishes the refreshed snapshot before returning. Each
// subscriber's effects remain ordered and may finish after this method returns.
func (s *SettingsService) UpdateSettings(ctx context.Context, updates settings.Update) ([]SettingVariable, error) {
if err := normalization.Normalize(&updates); err != nil {
return nil, err
}
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return nil, err
}
cfg := s.GetSettingsConfig().Clone()
oidcClientSecretUpdated := updates.OidcClientSecret != nil && *updates.OidcClientSecret != cfg.OidcClientSecret.Value && !s.IsEnvOverrideActive("oidcClientSecret")
trivyServerTokenProvided := updates.TrivyServerToken != nil && *updates.TrivyServerToken != ""
trivyServerTokenUpdated := trivyServerTokenProvided && *updates.TrivyServerToken != cfg.TrivyServerToken.Value && !s.IsEnvOverrideActive("trivyServerToken")
normalizeTargetURL := func(value string) string {
normalized, err := httpx.NormalizeBaseURL(value)
if err != nil {
return strings.TrimSpace(value)
}
return normalized
}
if err := validation.ValidateCredentialTargetChange(
"OIDC issuer URL",
cfg.OidcIssuerUrl.Value,
updates.OidcIssuerUrl,
normalizeTargetURL,
map[string]bool{"oidcClientSecret": cfg.OidcClientSecret.Value != ""},
map[string]bool{"oidcClientSecret": updates.OidcClientSecret != nil},
); err != nil {
return nil, err
}
effectiveValue := func(current SettingVariable, next *string) string {
if next != nil {
return *next
}
return current.Value
}
oidcClientSecret := kit.Ternary(oidcClientSecretUpdated, kit.FromPtr(updates.OidcClientSecret), cfg.OidcClientSecret.Value)
if effectiveValue(cfg.OidcEnabled, updates.OidcEnabled) == "true" {
required := []struct{ key, value string }{
{"oidcClientId", effectiveValue(cfg.OidcClientId, updates.OidcClientId)},
{"oidcClientSecret", oidcClientSecret},
{"oidcIssuerUrl", effectiveValue(cfg.OidcIssuerUrl, updates.OidcIssuerUrl)},
}
for _, field := range required {
if strings.TrimSpace(field.value) == "" {
return nil, common.Classify(common.ErrValidation, &base.FieldError{Field: field.key, Err: fmt.Errorf("enabling OIDC requires %s", field.key)})
}
}
}
if err := validation.ValidateCredentialTargetChange(
"Trivy server URL",
cfg.TrivyServerUrl.Value,
updates.TrivyServerUrl,
normalizeTargetURL,
map[string]bool{"trivyServerToken": cfg.TrivyServerToken.Value != ""},
map[string]bool{"trivyServerToken": trivyServerTokenProvided},
); err != nil {
return nil, err
}
valuesToUpdate, err := s.prepareUpdateValues(updates, cfg, DefaultSettingsConfig())
if err != nil {
return nil, err
}
if oidcClientSecretUpdated {
valuesToUpdate = append(valuesToUpdate, SettingVariable{Key: "oidcClientSecret", Value: *updates.OidcClientSecret})
}
if trivyServerTokenUpdated {
valuesToUpdate = append(valuesToUpdate, SettingVariable{Key: "trivyServerToken", Value: *updates.TrivyServerToken})
}
if persistSettingsErr := s.persistSettings(ctx, valuesToUpdate); persistSettingsErr != nil {
return nil, persistSettingsErr
}
changes := make([]libarcane.SettingUpdate, 0, len(valuesToUpdate))
for _, value := range valuesToUpdate {
changes = append(changes, libarcane.SettingUpdate{Key: value.Key, Value: value.Value})
}
result := s.GetSettingsConfig().ToSettingVariableSlice(SettingVisibilityNonAdmin, false)
s.publishSettingsChanges(changes)
return result, nil
}
func (s *SettingsService) publishSettingsChanges(updates []libarcane.SettingUpdate) {
safe := make([]libarcane.SettingUpdate, 0, len(updates))
cfg := s.GetSettingsConfig()
for _, update := range updates {
_, _, sensitive, err := cfg.FieldByKey(update.Key)
if err != nil {
slog.WarnContext(s.lifecycleCtx, "Skipping settings change notification for unknown key", "key", update.Key, "error", err)
continue
}
if !sensitive {
safe = append(safe, update)
}
}
if len(safe) > 0 {
s.changes.Publish(safe)
}
}
func (s *SettingsService) prepareUpdateValues(updates settings.Update, cfg, defaultCfg *Settings) ([]SettingVariable, error) {
rt := reflect.TypeFor[settings.Update]()
rv := reflect.ValueOf(updates)
valuesToUpdate := make([]SettingVariable, 0)
for i := range rt.NumField() {
fieldValue := rv.Field(i)
if fieldValue.Kind() == reflect.Pointer && fieldValue.IsNil() {
continue
}
key, _, _ := strings.Cut(rt.Field(i).Tag.Get("json"), ",")
if key == "" {
continue
}
var value string
if fieldValue.Kind() == reflect.Pointer {
value = fieldValue.Elem().String()
}
if err := validateSettingValue(key, value); err != nil {
return nil, err
}
if s.IsEnvOverrideActive(key) {
continue
}
current, _, _, _ := cfg.FieldByKey(key)
if key == libarcane.DepotTokenSettingKey {
// Sensitive token: only update when explicitly provided.
// Empty input preserves existing token.
if strings.TrimSpace(value) == "" || value == current {
continue
}
if err := cfg.UpdateField(key, value, false); err != nil {
return nil, fmt.Errorf("failed to update in-memory config for key '%s': %w", key, err)
}
valuesToUpdate = append(valuesToUpdate, SettingVariable{Key: key, Value: value})
continue
}
if err := libarcane.ValidateCronSetting(key, value); err != nil {
return nil, fmt.Errorf("invalid cron expression for %s: %w", key, err)
}
valueToSave := value
if valueToSave == "" {
valueToSave, _, _, _ = defaultCfg.FieldByKey(key)
}
if valueToSave == current {
continue
}
err := cfg.UpdateField(key, valueToSave, true)
if errors.Is(err, SettingSensitiveForbiddenError{}) {
continue
}
if err != nil {
return nil, fmt.Errorf("failed to update in-memory config for key '%s': %w", key, err)
}
valuesToUpdate = append(valuesToUpdate, SettingVariable{Key: key, Value: valueToSave})
}
return valuesToUpdate, nil
}
func (s *SettingsService) persistSettings(ctx context.Context, values []SettingVariable) error {
_, byKey := getSettingsFieldCacheInternal()
if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
for _, setting := range values {
if setting.Key == "oidcProviderName" {
setting.Value = normalization.Text(setting.Value, true, true)
}
if byKey[setting.Key].isEncrypted && setting.Value != "" {
encrypted, encryptErr := crypto.Encrypt(setting.Value)
if encryptErr != nil {
return fmt.Errorf("failed to encrypt setting %s: %w", setting.Key, encryptErr)
}
setting.Value = encrypted
}
if err := tx.Save(&setting).Error; err != nil {
return fmt.Errorf("failed to update setting %s: %w", setting.Key, err)
}
}
return nil
}); err != nil {
return err
}
if err := s.LoadDatabaseSettings(context.WithoutCancel(ctx)); err != nil {
return fmt.Errorf("failed to refresh settings cache: %w", err)
}
return nil
}
// retiredSettingValues lists former defaults that startup replaces
// with the current default when an install still holds them verbatim.
var retiredSettingValues = map[string][]string{
"dockerClientRefreshInterval": {"*/30 * * * * *"},
"autoHealInterval": {"*/30 * * * * *"},
}
func (s *SettingsService) EnsureDefaultSettings(ctx context.Context) error {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
defaultSettingVars := DefaultSettingsConfig().ToSettingVariableSlice(SettingVisibilityAll, false)
return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
for _, defaultSetting := range defaultSettingVars {
var existing SettingVariable
err := tx.Where("key = ?", defaultSetting.Key).First(&existing).Error
switch {
case errors.Is(err, gorm.ErrRecordNotFound):
if createDefaultSettingErr := tx.Create(&defaultSetting).Error; createDefaultSettingErr != nil {
return fmt.Errorf("failed to create default setting %s: %w", defaultSetting.Key, createDefaultSettingErr)
}
case err != nil:
return fmt.Errorf("failed to check for existing setting %s: %w", defaultSetting.Key, err)
case slices.Contains(retiredSettingValues[defaultSetting.Key], existing.Value),
existing.Value != "" && s.GetSettingType(defaultSetting.Key) == "cron" && func() bool {
_, parseErr := schedule.Parser().Parse(existing.Value)
return parseErr != nil
}():
replaceDefaultSettingErr := tx.Model(&SettingVariable{}).Where("key = ?", defaultSetting.Key).Update("value", defaultSetting.Value).Error
if replaceDefaultSettingErr != nil {
return fmt.Errorf("failed to replace setting %s with default: %w", defaultSetting.Key, replaceDefaultSettingErr)
}
slog.InfoContext(ctx, "Replaced invalid setting value with default", "key", defaultSetting.Key, "from", existing.Value, "to", defaultSetting.Value)
}
}
return nil
})
}
func (s *SettingsService) PruneUnknownSettings(ctx context.Context) error {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
fields, _ := getSettingsFieldCacheInternal()
keys := make([]string, 0, len(fields)+1)
for _, field := range fields {
keys = append(keys, field.key)
}
keys = append(keys, "encryptionKey")
result := s.db.WithContext(ctx).Where("key NOT IN ?", keys).Delete(&SettingVariable{})
if result.Error != nil {
return fmt.Errorf("failed to prune unknown settings: %w", result.Error)
}
if result.RowsAffected > 0 {
slog.InfoContext(ctx, "Pruned unknown settings", "count", result.RowsAffected)
}
return nil
}
func (s *SettingsService) PersistEnvSettingsIfMissing(ctx context.Context) error {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
isEnvOnlyMode := s.appConfig.AgentMode || s.appConfig.UIConfigurationDisabled
fields, _ := getSettingsFieldCacheInternal()
if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
for _, field := range fields {
attrs := splitSettingAttrsInternal(field.attrs)
// Outside env-only mode, only persist fields explicitly marked as envOverride.
if slices.Contains(attrs, "internal") || field.isSensitive || (!isEnvOnlyMode && !slices.Contains(attrs, "envOverride")) {
continue
}
envVal, ok, _ := utils.LookupEnvOrFile(settingEnvName(field.key))
if !ok {
continue
}
envVal = kit.TrimQuotes(envVal)
var existing SettingVariable
err := tx.Where("key = ?", field.key).First(&existing).Error
switch {
case errors.Is(err, gorm.ErrRecordNotFound):
if createEnvSettingErr := tx.Create(&SettingVariable{Key: field.key, Value: envVal}).Error; createEnvSettingErr != nil {
return fmt.Errorf("persist env setting %s: %w", field.key, createEnvSettingErr)
}
slog.DebugContext(ctx, "Created setting from environment", "key", field.key)
case err != nil:
return fmt.Errorf("check setting %s: %w", field.key, err)
case existing.Value != envVal:
if updateEnvSettingErr := tx.Model(&existing).Update("value", envVal).Error; updateEnvSettingErr != nil {
return fmt.Errorf("update env setting %s: %w", field.key, updateEnvSettingErr)
}
slog.DebugContext(ctx, "Updated setting from environment", "key", field.key)
}
}
return nil
}); err != nil {
return err
}
return s.LoadDatabaseSettings(context.WithoutCancel(ctx))
}
func (s *SettingsService) EncryptStoredSensitiveSettings(ctx context.Context) error {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
fields, _ := getSettingsFieldCacheInternal()
keys := make([]string, 0, len(fields))
for _, field := range fields {
if field.isEncrypted {
keys = append(keys, field.key)
}
}
encryptedCount := 0
completed := false
if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
var marker SettingVariable
if findErr := tx.Where("key = ?", sensitiveSettingsEncryptedKey).Limit(1).Find(&marker).Error; findErr != nil {
return fmt.Errorf("load sensitive settings marker: %w", findErr)
}
if marker.Value == "true" {
completed = true
return nil
}
var stored []SettingVariable
if findErr := tx.Where("key IN ? AND value <> ''", keys).Find(&stored).Error; findErr != nil {
return fmt.Errorf("load sensitive settings: %w", findErr)
}
for _, setting := range stored {
if _, decryptErr := crypto.Decrypt(setting.Value); decryptErr == nil {
continue
}
encrypted, encryptErr := crypto.Encrypt(setting.Value)
if encryptErr != nil {
return fmt.Errorf("encrypt setting %s: %w", setting.Key, encryptErr)
}
if updateErr := tx.Model(&SettingVariable{}).Where("key = ?", setting.Key).Update("value", encrypted).Error; updateErr != nil {
return fmt.Errorf("update setting %s: %w", setting.Key, updateErr)
}
encryptedCount++
}
if saveErr := tx.Save(&SettingVariable{Key: sensitiveSettingsEncryptedKey, Value: "true"}).Error; saveErr != nil {
return fmt.Errorf("save sensitive settings marker: %w", saveErr)
}
return nil
}); err != nil {
return err
}
if completed {
return nil
}
slog.InfoContext(ctx, "Encrypted stored sensitive settings", "count", encryptedCount)
return s.LoadDatabaseSettings(context.WithoutCancel(ctx))
}
func looksLikeCiphertext(value string, decryptErr error) bool {
_, isDecryptErr := errors.AsType[*crypto.DecryptError](decryptErr)
decoded, decodeErr := base64.StdEncoding.DecodeString(value)
return isDecryptErr && decodeErr == nil && len(decoded) >= minCiphertextBytes
}
func (s *SettingsService) ListSettings(visibility SettingVisibility) []SettingVariable {
return s.GetSettingsConfig().ToSettingVariableSlice(visibility, true)
}
// GetSettingType returns the type from the setting metadata
func (s *SettingsService) GetSettingType(key string) string {
_, byKey := getSettingsFieldCacheInternal()
if field, ok := byKey[key]; ok {
metaTag := reflect.TypeFor[Settings]().Field(field.index).Tag.Get("meta")
for part := range strings.SplitSeq(metaTag, ";") {
if after, found := strings.CutPrefix(part, "type="); found {
return after
}
}
}
return "text"
}
func (s *SettingsService) settingValue[T any](ctx context.Context, key string, parse func(string) (T, error)) mo.Option[T] {
cfg := s.GetSettingsOrDefaults(ctx)
value, _, _, err := cfg.FieldByKey(key)
if err != nil || value == "" {
return mo.None[T]()
}
parsed, err := parse(value)
if err != nil {
return mo.None[T]()
}
return mo.Some(parsed)
}
func (s *SettingsService) GetBoolSetting(ctx context.Context, key string, defaultValue bool) bool {
return s.settingValue(ctx, key, strconv.ParseBool).OrElse(defaultValue)
}
func (s *SettingsService) GetIntSetting(ctx context.Context, key string, defaultValue int) int {
return s.settingValue(ctx, key, strconv.Atoi).OrElse(defaultValue)
}
func (s *SettingsService) GetStringSetting(ctx context.Context, key, defaultValue string) string {
return s.settingValue(ctx, key, func(value string) (string, error) { return value, nil }).OrElse(defaultValue)
}
func (s *SettingsService) SetBoolSetting(ctx context.Context, key string, value bool) error {
return s.UpdateSetting(ctx, key, strconv.FormatBool(value))
}
func (s *SettingsService) SetIntSetting(ctx context.Context, key string, value int) error {
return s.UpdateSetting(ctx, key, strconv.Itoa(value))
}
func (s *SettingsService) SetStringSetting(ctx context.Context, key, value string) error {
return s.UpdateSetting(ctx, key, value)
}
// SetContainerAutoUpdateExclusionInternal adds (excluded) or removes a container name
// in the autoUpdateExcludedContainers setting.
func (s *SettingsService) SetContainerAutoUpdateExclusionInternal(ctx context.Context, containerName string, excluded bool) error {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
ordered := kit.Unique(kit.TrimNonEmpty(strings.Split(s.GetStringSetting(ctx, "autoUpdateExcludedContainers", ""), ",")))
if excluded {
ordered = kit.Unique(append(ordered, containerName))
} else {
ordered = slices.DeleteFunc(ordered, func(name string) bool { return name == containerName })
}
return s.persistSettings(ctx, []SettingVariable{{Key: "autoUpdateExcludedContainers", Value: strings.Join(ordered, ",")}})
}
func (s *SettingsService) EnsureEncryptionKey(ctx context.Context) (string, error) {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return "", err
}
return ensureSettingValue(ctx, s.db, "encryptionKey", "encryption key", func() (string, error) {
sum := sha256.Sum256([]byte(uuid.New().String()))
return base64.StdEncoding.EncodeToString(sum[:]), nil
})
}
func (s *SettingsService) EnsureJwtSigningKey(ctx context.Context) (*mldsa.PrivateKey, error) {
seed, err := s.ensureEncryptedKey(ctx, "jwtSigningKeySeed", mldsa.PrivateKeySize)
if err != nil {
return nil, err
}
key, err := mldsa.NewPrivateKey(mldsa.MLDSA87(), seed)
if err != nil {
return key, fmt.Errorf("failed to load jwt signing key: %w", err)
}
return key, nil
}
func (s *SettingsService) EnsureBrowserSessionSigningKey(ctx context.Context) ([]byte, error) {
return s.ensureEncryptedKey(ctx, "browserSessionSigningKey", browserSessionSigningKeySize)
}
func (s *SettingsService) ensureEncryptedKey(ctx context.Context, keyName string, size int) ([]byte, error) {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return nil, err
}
var generated []byte
stored, err := ensureSettingValue(ctx, s.db, keyName, "signing key", func() (string, error) {
generated = make([]byte, size)
if _, genErr := rand.Read(generated); genErr != nil {
return "", fmt.Errorf("failed to generate signing key: %w", genErr)
}
encrypted, encErr := crypto.Encrypt(base64.StdEncoding.EncodeToString(generated))
if encErr != nil {
return "", fmt.Errorf("failed to encrypt signing key: %w", encErr)
}
return encrypted, nil
})
if err != nil {
return nil, err
}
if generated != nil {
return generated, nil
}
decoded, err := crypto.Decrypt(stored)
if err != nil {
return nil, fmt.Errorf("failed to decrypt signing key: %w", err)
}
key, err := base64.StdEncoding.DecodeString(decoded)
if err != nil {
return nil, fmt.Errorf("failed to decode signing key: %w", err)
}
if len(key) != size {
return nil, fmt.Errorf("invalid signing key length: got %d, want %d", len(key), size)
}
return key, nil
}
func (s *SettingsService) NormalizeProjectsDirectory(ctx context.Context, projectsDirEnv string) error {
if projectsDirEnv != "" {
slog.DebugContext(ctx, "PROJECTS_DIRECTORY environment variable is set, skipping normalization", "value", projectsDirEnv)
return nil
}
return s.normalizeDirectorySetting(ctx, "projectsDirectory")
}
func (s *SettingsService) NormalizeBuildsDirectory(ctx context.Context) error {
if envVal, ok, _ := utils.LookupEnvOrFile(settingEnvName("buildsDirectory")); ok && strings.TrimSpace(envVal) != "" {
slog.DebugContext(ctx, "BUILDS_DIRECTORY environment variable is set, skipping normalization", "value", envVal)
return nil
}
return s.normalizeDirectorySetting(ctx, "buildsDirectory")
}
func (s *SettingsService) normalizeDirectorySetting(ctx context.Context, key string) error {
s.writes.Lock()
defer s.writes.Unlock()
if err := ctx.Err(); err != nil {
return err
}
var setting SettingVariable
err := s.db.WithContext(ctx).Where("key = ?", key).First(&setting).Error
if errors.Is(err, gorm.ErrRecordNotFound) {
slog.DebugContext(ctx, "No directory setting found, skipping normalization", "key", key)
return nil
}
if err != nil {
return fmt.Errorf("failed to load %s setting: %w", key, err)
}
value := strings.TrimSpace(setting.Value)
isMapping := strings.Contains(value, ":") && (strings.HasPrefix(value, "/") || projects.IsWindowsDrivePath(value))
if value == "" || filepath.IsAbs(value) || isMapping {
slog.DebugContext(ctx, "Directory setting already normalized, custom, or empty, skipping", "key", key, "value", setting.Value)
return nil
}
cwd, _ := os.Getwd()
absPath, err := filepath.Abs(value)
if err != nil {
return fmt.Errorf("failed to resolve relative path to absolute: %w", err)
}
slog.InfoContext(ctx, "Normalizing directory setting from relative to absolute path", "key", key, "from", value, "to", absPath, "base", cwd)
if persistSettingsErr := s.persistSettings(ctx, []SettingVariable{{Key: key, Value: absPath}}); persistSettingsErr != nil {
return persistSettingsErr
}
slog.InfoContext(ctx, "Successfully normalized directory setting", "key", key)
s.publishSettingsChanges([]libarcane.SettingUpdate{{Key: key, Value: absPath}})
return nil
}
func (s *SettingsService) enqueueEffect(effect func()) error {
s.effectsMu.Lock()
defer s.effectsMu.Unlock()
if s.effectsClosed {
return errors.New("settings effects stopped")
}
s.effects = append(s.effects, effect)
select {
case s.effectsWake <- struct{}{}:
default:
}
return nil
}
// Stop drains accepted effects and joins the settings worker.
func (s *SettingsService) Stop(ctx context.Context) error {
s.writes.Lock()
s.effectsMu.Lock()
s.effectsClosed = true
s.effectsMu.Unlock()
s.writes.Unlock()
select {
case s.effectsWake <- struct{}{}:
default:
}
select {
case <-s.effectsDone:
return nil
case <-ctx.Done():
return ctx.Err()
}
}
// IsFeatureEnabled resolves feature availability on this environment.
func (s *SettingsService) IsFeatureEnabled(ctx context.Context, id features.ID) bool {
definition, ok := features.Lookup(id)
if !ok {
return false
}
if s == nil {
return definition.DefaultEnabled
}
cfg := s.GetSettingsOrDefaults(ctx)
value, _, _, err := cfg.FieldByKey(definition.SettingKey)
if err != nil || value == "" {
return definition.DefaultEnabled
}
enabled, err := strconv.ParseBool(value)
return kit.Ternary(err != nil, definition.DefaultEnabled, enabled)
}
// RequireFeature rejects operations when their runtime feature is disabled.
func (s *SettingsService) RequireFeature(ctx context.Context, id features.ID) error {
if s.IsFeatureEnabled(ctx, id) {
return nil
}
return fmt.Errorf("feature %s is disabled: %w", id, common.ErrFeatureDisabled)
}
type SettingsSearchService struct {
categories []category.Category
}
func NewSettingsSearchService() *SettingsSearchService {
return &SettingsSearchService{categories: search.BuildCategories[Settings](searchtypes.SettingsProfile)}
}
// GetSettingsCategories returns the category index initialized by the service.
func (s *SettingsSearchService) GetSettingsCategories() []category.Category {
return s.categories
}