feat: configurable options for the project up command

Author: kmendell

backend/internal/huma/handlers/projects.go

@@ -59,6 +59,7 @@ type GetProjectStatusCountsOutput struct {
 type DeployProjectInput struct {
 	EnvironmentID string `path:"id" doc:"Environment ID"`
 	ProjectID     string `path:"projectId" doc:"Project ID"`
+	Body          *project.UpRequest
 }
 
 type DeployProjectOutput struct {
@@ -404,6 +405,24 @@ func (h *ProjectHandler) DeployProject(ctx context.Context, input *DeployProject
 		return nil, huma.Error400BadRequest((&common.ProjectIDRequiredError{}).Error())
 	}
 
+	deployOptions := &project.UpRequest{
+		PullPolicy:    project.UpPullPolicyMissing,
+		ForceRecreate: false,
+	}
+
+	if input.Body != nil {
+		deployOptions.ForceRecreate = input.Body.ForceRecreate
+
+		switch input.Body.PullPolicy {
+		case "", project.UpPullPolicyMissing:
+			deployOptions.PullPolicy = project.UpPullPolicyMissing
+		case project.UpPullPolicyAlways:
+			deployOptions.PullPolicy = project.UpPullPolicyAlways
+		default:
+			return nil, huma.Error400BadRequest("invalid pullPolicy, expected one of: missing, always")
+		}
+	}
+
 	user, exists := humamw.GetCurrentUserFromContext(ctx)
 	if !exists {
 		return nil, huma.Error401Unauthorized((&common.NotAuthenticatedError{}).Error())
@@ -424,7 +443,7 @@ func (h *ProjectHandler) DeployProject(ctx context.Context, input *DeployProject
 			}
 
 			deployCtx := context.WithValue(humaCtx.Context(), projects.ProgressWriterKey{}, writer)
-			if err := h.projectService.DeployProject(deployCtx, input.ProjectID, *user); err != nil {
+			if err := h.projectService.DeployProjectWithOptions(deployCtx, input.ProjectID, *user, deployOptions); err != nil {
 				_, _ = fmt.Fprintf(writer, `{"error":%q}`+"\n", err.Error())
 				if f, ok := writer.(http.Flusher); ok {
 					f.Flush()

backend/internal/models/settings.go

@@ -101,10 +101,12 @@ type Settings struct {
 	OidcProviderLogoUrl             SettingVariable `key:"oidcProviderLogoUrl,public,envOverride" meta:"label=OIDC Provider Logo URL;type=text;keywords=oidc,provider,logo,url,image,icon,sso;category=security;description=Custom logo URL for the OIDC provider"`
 
 	// Appearance category
-	MobileNavigationMode       SettingVariable `key:"mobileNavigationMode,public,local" meta:"label=Mobile Navigation Mode;type=select;keywords=mode,style,type,floating,docked,position,layout,design,appearance,bottom;category=appearance;description=Choose between floating or docked navigation on mobile" catmeta:"id=appearance;title=Appearance;icon=appearance;url=/settings/appearance;description=Customize navigation, theme, and interface behavior"`
-	MobileNavigationShowLabels SettingVariable `key:"mobileNavigationShowLabels,public,local" meta:"label=Show Navigation Labels;type=boolean;keywords=labels,text,icons,display,show,hide,names,captions,titles,visible,toggle;category=appearance;description=Display text labels alongside navigation icons"`
-	SidebarHoverExpansion      SettingVariable `key:"sidebarHoverExpansion,public,local" meta:"label=Sidebar Hover Expansion;type=boolean;keywords=sidebar,hover,expansion,expand,desktop,mouse,over,collapsed,collapsible,icon,labels,text,preview,peek,tooltip,overlay,temporary,quick,access,navigation,menu,items,submenu,nested;category=appearance;description=Expand sidebar on hover in desktop mode"`
-	KeyboardShortcutsEnabled   SettingVariable `key:"keyboardShortcutsEnabled,public,local" meta:"label=Keyboard Shortcuts;type=boolean;keywords=keyboard,shortcuts,hotkeys,keybindings,navigation,tooltips,disable;category=appearance;description=Enable keyboard shortcuts for navigation and show shortcut hints in tooltips"`
+	MobileNavigationMode          SettingVariable `key:"mobileNavigationMode,public,local" meta:"label=Mobile Navigation Mode;type=select;keywords=mode,style,type,floating,docked,position,layout,design,appearance,bottom;category=appearance;description=Choose between floating or docked navigation on mobile" catmeta:"id=appearance;title=Appearance;icon=appearance;url=/settings/appearance;description=Customize navigation, theme, and interface behavior"`
+	MobileNavigationShowLabels    SettingVariable `key:"mobileNavigationShowLabels,public,local" meta:"label=Show Navigation Labels;type=boolean;keywords=labels,text,icons,display,show,hide,names,captions,titles,visible,toggle;category=appearance;description=Display text labels alongside navigation icons"`
+	SidebarHoverExpansion         SettingVariable `key:"sidebarHoverExpansion,public,local" meta:"label=Sidebar Hover Expansion;type=boolean;keywords=sidebar,hover,expansion,expand,desktop,mouse,over,collapsed,collapsible,icon,labels,text,preview,peek,tooltip,overlay,temporary,quick,access,navigation,menu,items,submenu,nested;category=appearance;description=Expand sidebar on hover in desktop mode"`
+	KeyboardShortcutsEnabled      SettingVariable `key:"keyboardShortcutsEnabled,public,local" meta:"label=Keyboard Shortcuts;type=boolean;keywords=keyboard,shortcuts,hotkeys,keybindings,navigation,tooltips,disable;category=appearance;description=Enable keyboard shortcuts for navigation and show shortcut hints in tooltips"`
+	ProjectUpDefaultPullPolicy    SettingVariable `key:"projectUpDefaultPullPolicy,public" meta:"label=Project Up Default Pull Policy;type=select;keywords=project,compose,up,pull,policy,default,images;category=appearance;description=Default image pull policy for project Up actions (missing or always)"`
+	ProjectUpDefaultForceRecreate SettingVariable `key:"projectUpDefaultForceRecreate,public" meta:"label=Project Up Default Force Recreate;type=boolean;keywords=project,compose,up,force,recreate,default;category=appearance;description=Default force-recreate behavior for project Up actions"`
 
 	// Notifications category (placeholder for category metadata only - actual settings managed via notification service)
 	NotificationsCategoryPlaceholder SettingVariable `key:"notificationsCategory,internal" meta:"label=Notifications;type=internal;keywords=notifications,alerts,email,discord,webhooks,events,messages;category=notifications;description=Configure notification providers and alerts" catmeta:"id=notifications;title=Notifications;icon=bell;url=/settings/notifications;description=Configure email and Discord notifications for container and image updates"`

backend/internal/services/project_service.go

@@ -698,7 +698,59 @@ func (s *ProjectService) GetProjectStatusCounts(ctx context.Context) (folderCoun
 
 // Project Actions
 
+type deployPullPolicy string
+
+const (
+	deployPullPolicyMissing deployPullPolicy = "missing"
+	deployPullPolicyAlways  deployPullPolicy = "always"
+)
+
+type deployOptions struct {
+	pullPolicy    deployPullPolicy
+	forceRecreate bool
+}
+
+func defaultDeployOptions() deployOptions {
+	return deployOptions{
+		pullPolicy:    deployPullPolicyMissing,
+		forceRecreate: false,
+	}
+}
+
+func normalizeDeployOptions(options *project.UpRequest) (deployOptions, error) {
+	normalized := defaultDeployOptions()
+	if options == nil {
+		return normalized, nil
+	}
+
+	switch options.PullPolicy {
+	case "", project.UpPullPolicyMissing:
+		normalized.pullPolicy = deployPullPolicyMissing
+	case project.UpPullPolicyAlways:
+		normalized.pullPolicy = deployPullPolicyAlways
+	default:
+		return deployOptions{}, fmt.Errorf("invalid pull policy: %q", options.PullPolicy)
+	}
+
+	normalized.forceRecreate = options.ForceRecreate
+
+	return normalized, nil
+}
+
 func (s *ProjectService) DeployProject(ctx context.Context, projectID string, user models.User) error {
+	return s.DeployProjectWithOptions(ctx, projectID, user, nil)
+}
+
+func (s *ProjectService) DeployProjectWithOptions(ctx context.Context, projectID string, user models.User, options *project.UpRequest) error {
+	normalizedOptions, err := normalizeDeployOptions(options)
+	if err != nil {
+		return err
+	}
+
+	return s.deployProject(ctx, projectID, user, normalizedOptions)
+}
+
+func (s *ProjectService) deployProject(ctx context.Context, projectID string, user models.User, options deployOptions) error {
 	projectFromDb, err := s.GetProjectFromDatabaseByID(ctx, projectID)
 	if err != nil {
 		return fmt.Errorf("failed to get project: %w", err)
@@ -732,15 +784,31 @@ func (s *ProjectService) DeployProject(ctx context.Context, projectID string, us
 		return fmt.Errorf("failed to update project status to deploying: %w", err)
 	}
 
-	if perr := s.EnsureProjectImagesPresent(ctx, projectID, io.Discard, nil); perr != nil {
-		slog.Warn("ensure images present failed (continuing to compose up)", "projectID", projectID, "error", perr)
+	progressWriter := io.Writer(io.Discard)
+	if writer, ok := ctx.Value(projects.ProgressWriterKey{}).(io.Writer); ok && writer != nil {
+		progressWriter = writer
+	}
+
+	switch options.pullPolicy {
+	case deployPullPolicyAlways:
+		if perr := s.PullProjectImages(ctx, projectID, progressWriter, nil); perr != nil {
+			slog.Warn("pull project images failed (continuing to compose up)", "projectID", projectID, "error", perr)
+		}
+	default:
+		if perr := s.EnsureProjectImagesPresent(ctx, projectID, progressWriter, nil); perr != nil {
+			slog.Warn("ensure images present failed (continuing to compose up)", "projectID", projectID, "error", perr)
+		}
 	}
 
 	removeOrphans := projectFromDb.GitOpsManagedBy != nil && *projectFromDb.GitOpsManagedBy != ""
+	composeUpOptions := projects.ComposeUpOptions{
+		RemoveOrphans: removeOrphans,
+		ForceRecreate: options.forceRecreate,
+	}
 
-	slog.Info("starting compose up with health check support", "projectID", projectID, "projectName", project.Name, "services", len(project.Services), "removeOrphans", removeOrphans)
+	slog.Info("starting compose up with health check support", "projectID", projectID, "projectName", project.Name, "services", len(project.Services), "removeOrphans", removeOrphans, "pullPolicy", options.pullPolicy, "forceRecreate", options.forceRecreate)
 	// Health/progress streaming (if any) is handled inside projects.ComposeUp via ctx.
-	if err := projects.ComposeUp(ctx, project, nil, removeOrphans); err != nil {
+	if err := projects.ComposeUp(ctx, project, nil, composeUpOptions); err != nil {
 		slog.Error("compose up failed", "projectName", project.Name, "projectID", projectID, "error", err)
 		if containers, psErr := s.GetProjectServices(ctx, projectID); psErr == nil {
 			slog.Info("containers after failed deploy", "projectID", projectID, "containers", containers)

backend/internal/services/project_service_test.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/getarcaneapp/arcane/backend/internal/database"
 	"github.com/getarcaneapp/arcane/backend/internal/models"
+	projecttypes "github.com/getarcaneapp/arcane/types/project"
 )
 
 func setupProjectTestDB(t *testing.T) *database.DB {
@@ -252,3 +253,71 @@ func TestProjectService_NormalizeComposeProjectName(t *testing.T) {
 		})
 	}
 }
+
+func TestNormalizeDeployOptions(t *testing.T) {
+	tests := []struct {
+		name             string
+		input            *projecttypes.UpRequest
+		wantPullPolicy   deployPullPolicy
+		wantForceCreate  bool
+		wantError        bool
+		wantErrorContain string
+	}{
+		{
+			name:            "nil uses defaults",
+			input:           nil,
+			wantPullPolicy:  deployPullPolicyMissing,
+			wantForceCreate: false,
+		},
+		{
+			name: "empty pull policy uses default",
+			input: &projecttypes.UpRequest{
+				PullPolicy: "",
+			},
+			wantPullPolicy:  deployPullPolicyMissing,
+			wantForceCreate: false,
+		},
+		{
+			name: "missing pull policy",
+			input: &projecttypes.UpRequest{
+				PullPolicy: projecttypes.UpPullPolicyMissing,
+			},
+			wantPullPolicy:  deployPullPolicyMissing,
+			wantForceCreate: false,
+		},
+		{
+			name: "always with force recreate",
+			input: &projecttypes.UpRequest{
+				PullPolicy:    projecttypes.UpPullPolicyAlways,
+				ForceRecreate: true,
+			},
+			wantPullPolicy:  deployPullPolicyAlways,
+			wantForceCreate: true,
+		},
+		{
+			name: "invalid pull policy",
+			input: &projecttypes.UpRequest{
+				PullPolicy: "latest",
+			},
+			wantError:        true,
+			wantErrorContain: "invalid pull policy",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := normalizeDeployOptions(tt.input)
+			if tt.wantError {
+				require.Error(t, err)
+				if tt.wantErrorContain != "" {
+					assert.Contains(t, err.Error(), tt.wantErrorContain)
+				}
+				return
+			}
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantPullPolicy, got.pullPolicy)
+			assert.Equal(t, tt.wantForceCreate, got.forceRecreate)
+		})
+	}
+}

backend/internal/services/settings_service.go

@@ -111,30 +111,32 @@ func (s *SettingsService) getDefaultSettings() *models.Settings {
 		AuthPasswordPolicy:         models.SettingVariable{Value: "strong"},
 		TrivyImage:                 models.SettingVariable{Value: "ghcr.io/aquasecurity/trivy:latest"},
 		// AuthOidcConfig DEPRECATED will be removed in a future release
-		AuthOidcConfig:             models.SettingVariable{Value: "{}"},
-		OidcEnabled:                models.SettingVariable{Value: "false"},
-		OidcClientId:               models.SettingVariable{Value: ""},
-		OidcClientSecret:           models.SettingVariable{Value: ""},
-		OidcIssuerUrl:              models.SettingVariable{Value: ""},
-		OidcAuthorizationEndpoint:  models.SettingVariable{Value: ""},
-		OidcTokenEndpoint:          models.SettingVariable{Value: ""},
-		OidcUserinfoEndpoint:       models.SettingVariable{Value: ""},
-		OidcJwksEndpoint:           models.SettingVariable{Value: ""},
-		OidcScopes:                 models.SettingVariable{Value: "openid email profile"},
-		OidcAdminClaim:             models.SettingVariable{Value: ""},
-		OidcAdminValue:             models.SettingVariable{Value: ""},
-		OidcSkipTlsVerify:          models.SettingVariable{Value: "false"},
-		OidcAutoRedirectToProvider: models.SettingVariable{Value: "false"},
-		OidcMergeAccounts:          models.SettingVariable{Value: "false"},
-		OidcProviderName:           models.SettingVariable{Value: ""},
-		OidcProviderLogoUrl:        models.SettingVariable{Value: ""},
-		MobileNavigationMode:       models.SettingVariable{Value: "floating"},
-		MobileNavigationShowLabels: models.SettingVariable{Value: "true"},
-		SidebarHoverExpansion:      models.SettingVariable{Value: "true"},
-		KeyboardShortcutsEnabled:   models.SettingVariable{Value: "true"},
-		AccentColor:                models.SettingVariable{Value: "oklch(0.606 0.25 292.717)"},
-		MaxImageUploadSize:         models.SettingVariable{Value: "500"},
-		EnvironmentHealthInterval:  models.SettingVariable{Value: "0 */2 * * * *"},
+		AuthOidcConfig:                models.SettingVariable{Value: "{}"},
+		OidcEnabled:                   models.SettingVariable{Value: "false"},
+		OidcClientId:                  models.SettingVariable{Value: ""},
+		OidcClientSecret:              models.SettingVariable{Value: ""},
+		OidcIssuerUrl:                 models.SettingVariable{Value: ""},
+		OidcAuthorizationEndpoint:     models.SettingVariable{Value: ""},
+		OidcTokenEndpoint:             models.SettingVariable{Value: ""},
+		OidcUserinfoEndpoint:          models.SettingVariable{Value: ""},
+		OidcJwksEndpoint:              models.SettingVariable{Value: ""},
+		OidcScopes:                    models.SettingVariable{Value: "openid email profile"},
+		OidcAdminClaim:                models.SettingVariable{Value: ""},
+		OidcAdminValue:                models.SettingVariable{Value: ""},
+		OidcSkipTlsVerify:             models.SettingVariable{Value: "false"},
+		OidcAutoRedirectToProvider:    models.SettingVariable{Value: "false"},
+		OidcMergeAccounts:             models.SettingVariable{Value: "false"},
+		OidcProviderName:              models.SettingVariable{Value: ""},
+		OidcProviderLogoUrl:           models.SettingVariable{Value: ""},
+		MobileNavigationMode:          models.SettingVariable{Value: "floating"},
+		MobileNavigationShowLabels:    models.SettingVariable{Value: "true"},
+		SidebarHoverExpansion:         models.SettingVariable{Value: "true"},
+		KeyboardShortcutsEnabled:      models.SettingVariable{Value: "true"},
+		ProjectUpDefaultPullPolicy:    models.SettingVariable{Value: "missing"},
+		ProjectUpDefaultForceRecreate: models.SettingVariable{Value: "false"},
+		AccentColor:                   models.SettingVariable{Value: "oklch(0.606 0.25 292.717)"},
+		MaxImageUploadSize:            models.SettingVariable{Value: "500"},
+		EnvironmentHealthInterval:     models.SettingVariable{Value: "0 */2 * * * *"},
 
 		DockerAPITimeout:       models.SettingVariable{Value: "30"},
 		DockerImagePullTimeout: models.SettingVariable{Value: "600"},
@@ -540,6 +542,12 @@ func (s *SettingsService) prepareUpdateValues(updates settings.Update, cfg, defa
 			value = fieldValue.Elem().String()
 		}
 
+		if key == "projectUpDefaultPullPolicy" && value != "" {
+			if value != "missing" && value != "always" {
+				return nil, false, false, false, false, nil, fmt.Errorf("invalid value for %s: %s", key, value)
+			}
+		}
+
 		// Validate cron settings
 		cronFields := []string{"scheduledPruneInterval", "autoUpdateInterval", "pollingInterval", "environmentHealthInterval", "eventCleanupInterval", "analyticsHeartbeatInterval", "vulnerabilityScanInterval"}
 		if slices.Contains(cronFields, key) && value != "" {

backend/pkg/projects/cmds.go

@@ -42,7 +42,12 @@ func ComposeRestart(ctx context.Context, proj *types.Project, services []string)
 	return c.svc.Restart(ctx, proj.Name, api.RestartOptions{Services: services})
 }
 
-func ComposeUp(ctx context.Context, proj *types.Project, services []string, removeOrphans bool) error {
+type ComposeUpOptions struct {
+	RemoveOrphans bool
+	ForceRecreate bool
+}
+
+func ComposeUp(ctx context.Context, proj *types.Project, services []string, options ComposeUpOptions) error {
 	c, err := NewClient(ctx)
 	if err != nil {
 		return err
@@ -51,7 +56,7 @@ func ComposeUp(ctx context.Context, proj *types.Project, services []string, remo
 
 	progressWriter, _ := ctx.Value(ProgressWriterKey{}).(io.Writer)
 
-	upOptions, startOptions := composeUpOptions(proj, services, removeOrphans)
+	upOptions, startOptions := composeUpOptions(proj, services, options)
 
 	// If we don't need progress, just run compose up normally.
 	if progressWriter == nil {
@@ -61,12 +66,17 @@ func ComposeUp(ctx context.Context, proj *types.Project, services []string, remo
 	return composeUpWithProgress(ctx, c.svc, proj, api.UpOptions{Create: upOptions, Start: startOptions}, progressWriter)
 }
 
-func composeUpOptions(proj *types.Project, services []string, removeOrphans bool) (api.CreateOptions, api.StartOptions) {
+func composeUpOptions(proj *types.Project, services []string, options ComposeUpOptions) (api.CreateOptions, api.StartOptions) {
+	recreateMode := api.RecreateDiverged
+	if options.ForceRecreate {
+		recreateMode = api.RecreateForce
+	}
+
 	upOptions := api.CreateOptions{
 		Services:             services,
-		Recreate:             api.RecreateDiverged,
-		RecreateDependencies: api.RecreateDiverged,
-		RemoveOrphans:        removeOrphans,
+		Recreate:             recreateMode,
+		RecreateDependencies: recreateMode,
+		RemoveOrphans:        options.RemoveOrphans,
 	}
 
 	startOptions := api.StartOptions{

backend/pkg/projects/cmds_test.go

@@ -0,0 +1,28 @@
+package projects
+
+import (
+	"testing"
+
+	"github.com/compose-spec/compose-go/v2/types"
+	"github.com/docker/compose/v5/pkg/api"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestComposeUpOptions_DefaultRecreateMode(t *testing.T) {
+	proj := &types.Project{Name: "demo"}
+
+	createOpts, _ := composeUpOptions(proj, nil, ComposeUpOptions{RemoveOrphans: true})
+
+	assert.Equal(t, api.RecreateDiverged, createOpts.Recreate)
+	assert.Equal(t, api.RecreateDiverged, createOpts.RecreateDependencies)
+	assert.True(t, createOpts.RemoveOrphans)
+}
+
+func TestComposeUpOptions_ForceRecreateMode(t *testing.T) {
+	proj := &types.Project{Name: "demo"}
+
+	createOpts, _ := composeUpOptions(proj, nil, ComposeUpOptions{ForceRecreate: true})
+
+	assert.Equal(t, api.RecreateForce, createOpts.Recreate)
+	assert.Equal(t, api.RecreateForce, createOpts.RecreateDependencies)
+}