feat: add removeOrphans option to project deploy/redeploy (#2785)

Author: khanhx

backend/api/handlers/projects.go

@@ -108,6 +108,7 @@ type GetProjectFileOutput struct {
 type RedeployProjectInput struct {
 	EnvironmentID string `path:"id" doc:"Environment ID"`
 	ProjectID     string `path:"projectId" doc:"Project ID"`
+	Body          *project.DeployOptions
 }
 
 type RedeployProjectOutput struct {
@@ -811,7 +812,7 @@ func (h *ProjectHandler) RedeployProject(ctx context.Context, input *RedeployPro
 		return nil, huma.Error401Unauthorized((&common.NotAuthenticatedError{}).Error())
 	}
 
-	if err := h.projectService.RedeployProject(ctx, input.ProjectID, *user); err != nil {
+	if err := h.projectService.RedeployProject(ctx, input.ProjectID, *user, input.Body); err != nil {
 		var archivedErr *common.ProjectArchivedError
 		if errors.As(err, &archivedErr) {
 			return nil, huma.Error400BadRequest(err.Error())

backend/internal/services/gitops_sync_service.go

@@ -682,7 +682,7 @@ func (s *GitOpsSyncService) redeployIfRunningAfterSync(ctx context.Context, proj
 	}
 
 	slog.InfoContext(ctx, "Redeploying project due to content change from Git sync", "syncMode", syncMode, "projectName", project.Name, "projectId", project.ID)
-	if err := s.projectService.RedeployProject(ctx, project.ID, actor); err != nil {
+	if err := s.projectService.RedeployProject(ctx, project.ID, actor, nil); err != nil {
 		slog.ErrorContext(ctx, "Failed to redeploy project after Git sync", "syncMode", syncMode, "error", err, "projectId", project.ID)
 	}
 }
@@ -994,7 +994,7 @@ func (s *GitOpsSyncService) updateProjectForSyncInternal(ctx context.Context, sy
 		details, err := s.projectService.GetProjectDetails(ctx, project.ID, projecttypes.AllDetails())
 		if err == nil && (details.Status == string(models.ProjectStatusRunning) || details.Status == string(models.ProjectStatusPartiallyRunning)) {
 			slog.InfoContext(ctx, "Redeploying project due to content change from Git sync", "projectName", project.Name, "projectId", project.ID)
-			if err := s.projectService.RedeployProject(ctx, project.ID, actor); err != nil {
+			if err := s.projectService.RedeployProject(ctx, project.ID, actor, nil); err != nil {
 				slog.ErrorContext(ctx, "Failed to redeploy project after Git sync", "error", err, "projectId", project.ID)
 			}
 		}

backend/internal/services/project_service.go

@@ -1843,6 +1843,13 @@ func (s *ProjectService) UnarchiveProject(ctx context.Context, projectID string,
 	return nil
 }
 
+// resolveRemoveOrphansInternal decides whether compose up should remove orphan containers.
+// GitOps-managed projects always remove orphans so the running stack matches the
+// tracked compose file. Non-GitOps callers may opt in per request via DeployOptions.
+func resolveRemoveOrphansInternal(gitOpsManaged bool, options *project.DeployOptions) bool {
+	return gitOpsManaged || (options != nil && options.RemoveOrphans)
+}
+
 func (s *ProjectService) DeployProject(ctx context.Context, projectID string, user models.User, options *project.DeployOptions) error {
 	projectFromDb, err := s.GetProjectFromDatabaseByID(ctx, projectID)
 	if err != nil {
@@ -1880,7 +1887,8 @@ func (s *ProjectService) DeployProject(ctx context.Context, projectID string, us
 		return fmt.Errorf("failed to prepare project images for deploy: %w", perr)
 	}
 
-	removeOrphans := projectFromDb.GitOpsManagedBy != nil && *projectFromDb.GitOpsManagedBy != ""
+	gitOpsManaged := projectFromDb.GitOpsManagedBy != nil && *projectFromDb.GitOpsManagedBy != ""
+	removeOrphans := resolveRemoveOrphansInternal(gitOpsManaged, options)
 
 	slog.Info("starting compose up with health check support", "projectID", projectID, "projectName", project.Name, "services", len(project.Services), "removeOrphans", removeOrphans)
 	// Health/progress streaming (if any) is handled inside projects.ComposeUp via ctx.
@@ -2051,7 +2059,7 @@ func (s *ProjectService) DestroyProject(ctx context.Context, projectID string, r
 	return nil
 }
 
-func (s *ProjectService) RedeployProject(ctx context.Context, projectID string, user models.User) error {
+func (s *ProjectService) RedeployProject(ctx context.Context, projectID string, user models.User, options *project.DeployOptions) error {
 	proj, err := s.GetProjectFromDatabaseByID(ctx, projectID)
 	if err != nil {
 		return err
@@ -2077,7 +2085,7 @@ func (s *ProjectService) RedeployProject(ctx context.Context, projectID string,
 		slog.ErrorContext(ctx, "could not log project redeploy action", "error", logErr)
 	}
 
-	return s.DeployProject(ctx, projectID, user, nil)
+	return s.DeployProject(ctx, projectID, user, options)
 }
 
 func (s *ProjectService) projectRedeployDisabledInternal(ctx context.Context, proj models.Project) (bool, error) {

backend/internal/services/project_service_test.go

@@ -3805,3 +3805,25 @@ func dockerHostFromProjectRuntimeServerURLInternal(t *testing.T, serverURL strin
 func ptr(v string) *string {
 	return new(v)
 }
+
+func TestResolveRemoveOrphans(t *testing.T) {
+	tests := []struct {
+		name          string
+		gitOpsManaged bool
+		options       *projecttypes.DeployOptions
+		want          bool
+	}{
+		{"non-gitops, nil options", false, nil, false},
+		{"non-gitops, flag false", false, &projecttypes.DeployOptions{RemoveOrphans: false}, false},
+		{"non-gitops, flag true opts in", false, &projecttypes.DeployOptions{RemoveOrphans: true}, true},
+		{"gitops, nil options stays true", true, nil, true},
+		{"gitops, flag false stays true", true, &projecttypes.DeployOptions{RemoveOrphans: false}, true},
+		{"gitops, flag true stays true", true, &projecttypes.DeployOptions{RemoveOrphans: true}, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			require.Equal(t, tt.want, resolveRemoveOrphansInternal(tt.gitOpsManaged, tt.options))
+		})
+	}
+}

backend/internal/services/webhook_service.go

@@ -576,7 +576,7 @@ func (s *WebhookService) executeProjectWebhookActionInternal(ctx context.Context
 		}
 		return nil, nil
 	case models.WebhookActionTypeRedeploy:
-		if err := s.projectService.RedeployProject(ctx, wh.TargetID, systemUser); err != nil {
+		if err := s.projectService.RedeployProject(ctx, wh.TargetID, systemUser, nil); err != nil {
 			return nil, s.wrapWebhookActionErrorInternal(ctx, wh, "project", actionType, err)
 		}
 		return nil, nil

backend/pkg/projects/cmds_test.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	composetypes "github.com/compose-spec/compose-go/v2/types"
+	"github.com/docker/compose/v5/pkg/api"
 	"github.com/stretchr/testify/require"
 )
 
@@ -107,3 +108,28 @@ func TestFilterProjectServicesForPullInternalReturnsDeepCopiedProject(t *testing
 	require.Contains(t, project.Services["web"].DependsOn, "db")
 	require.Contains(t, project.Networks, "default")
 }
+
+func TestComposeUpOptions_RemoveOrphans(t *testing.T) {
+	proj := &composetypes.Project{Name: "test"}
+
+	t.Run("removeOrphans true propagates to CreateOptions", func(t *testing.T) {
+		upOptions, _ := composeUpOptions(proj, nil, true, false)
+		require.True(t, upOptions.RemoveOrphans)
+	})
+
+	t.Run("removeOrphans false leaves CreateOptions disabled", func(t *testing.T) {
+		upOptions, _ := composeUpOptions(proj, nil, false, false)
+		require.False(t, upOptions.RemoveOrphans)
+	})
+
+	t.Run("removeOrphans is independent of forceRecreate", func(t *testing.T) {
+		// forceRecreate drives the Recreate policy, not RemoveOrphans.
+		upOptions, _ := composeUpOptions(proj, nil, true, true)
+		require.True(t, upOptions.RemoveOrphans)
+		require.Equal(t, api.RecreateForce, upOptions.Recreate)
+
+		upOptions, _ = composeUpOptions(proj, nil, false, true)
+		require.False(t, upOptions.RemoveOrphans)
+		require.Equal(t, api.RecreateForce, upOptions.Recreate)
+	})
+}

types/project/project.go

@@ -80,6 +80,11 @@ type DeployOptions struct {
 	//
 	// Required: false
 	ForceRecreate bool `json:"forceRecreate,omitempty"`
+
+	// RemoveOrphans removes containers for services not defined in the compose file.
+	//
+	// Required: false
+	RemoveOrphans bool `json:"removeOrphans,omitempty"`
 }
 
 // UpdateIncludeFile is used to update an include file within a project.