feat: add --recreate flag for deploy command to force container recreation

README.md

@@ -323,6 +323,15 @@ SQLite database used to share Uncloud's cluster state.
   features, and be the first to know when it's ready for production use.
 * Watch this repository for releases.
 
+## 💖 Sponsors
+
+These companies and projects are helping Uncloud with their generous sponsorship and/or services:
+
+<!-- Sentry -->
+<a href="https://sentry.io/welcome/">
+  <img height="100" alt="Sentry" src="https://github.com/user-attachments/assets/6c1439c0-d20d-40dc-a669-c9aa94651dfa" />
+</a>
+
 ## ❤️ Contributors
 
 Thank you [@cedws](https://github.com/cedws) for being the first contributor to Uncloud! 🎉

cmd/uncloud/deploy.go

@@ -21,6 +21,7 @@ type deployOptions struct {
 	profiles []string
 	services []string
 	noBuild  bool
+	recreate bool
 
 	context string
 }
@@ -50,6 +51,8 @@ func NewDeployCommand() *cobra.Command {
 		"Name of the cluster context to deploy to (default is the current context)")
 	cmd.Flags().BoolVarP(&opts.noBuild, "no-build", "n", false,
 		"Do not build images before deploying services. (default false)")
+	cmd.Flags().BoolVar(&opts.recreate, "recreate", false,
+		"Recreate containers even if their configuration and image haven't changed.")
 
 	// TODO: Consider adding a filter flag to specify which machines to deploy to but keep the rest running.
 	//  Could be useful to test a new version on a subset of machines before rolling out to all.
@@ -108,7 +111,11 @@ func runDeploy(ctx context.Context, uncli *cli.CLI, opts deployOptions) error {
 	}
 	defer clusterClient.Close()
 
-	composeDeploy, err := compose.NewDeployment(ctx, clusterClient, project)
+	var strategy deploy.Strategy
+	if opts.recreate {
+		strategy = &deploy.RollingStrategy{ForceRecreate: true}
+	}
+	composeDeploy, err := compose.NewDeploymentWithStrategy(ctx, clusterClient, project, strategy)
 	if err != nil {
 		return fmt.Errorf("create compose deployment: %w", err)
 	}

cmd/uncloud/machine/add.go

@@ -41,7 +41,7 @@ func NewAddCommand() *cobra.Command {
 			if err != nil {
 				return fmt.Errorf("parse remote machine: %w", err)
 			}
-			remoteMachine := cli.RemoteMachine{
+			remoteMachine := &cli.RemoteMachine{
 				User:    user,
 				Host:    host,
 				Port:    port,
@@ -62,8 +62,9 @@ func NewAddCommand() *cobra.Command {
 			fmt.Sprintf("blank '' or '%s' to disable ingress on this machine, or specify an IP address.", PublicIPNone),
 	)
 	cmd.Flags().StringVarP(
-		&opts.sshKey, "ssh-key", "i", "~/.ssh/id_ed25519",
-		"Path to SSH private key for remote login (if not already added to SSH agent).",
+		&opts.sshKey, "ssh-key", "i", "",
+		fmt.Sprintf("Path to SSH private key for remote login (if not already added to SSH agent). (default %q)",
+			cli.DefaultSSHKeyPath),
 	)
 	cmd.Flags().StringVar(
 		&opts.version, "version", "latest",
@@ -77,7 +78,7 @@ func NewAddCommand() *cobra.Command {
 	return cmd
 }
 
-func add(ctx context.Context, uncli *cli.CLI, remoteMachine cli.RemoteMachine, opts addOptions) error {
+func add(ctx context.Context, uncli *cli.CLI, remoteMachine *cli.RemoteMachine, opts addOptions) error {
 	var publicIP *netip.Addr
 	switch opts.publicIP {
 	case "auto":

cmd/uncloud/machine/init.go

@@ -80,8 +80,9 @@ func NewInitCommand() *cobra.Command {
 			fmt.Sprintf("blank '' or '%s' to disable ingress on this machine, or specify an IP address.", PublicIPNone),
 	)
 	cmd.Flags().StringVarP(
-		&opts.sshKey, "ssh-key", "i", "~/.ssh/id_ed25519",
-		"Path to SSH private key for remote login (if not already added to SSH agent).",
+		&opts.sshKey, "ssh-key", "i", "",
+		fmt.Sprintf("Path to SSH private key for remote login (if not already added to SSH agent). (default %q)",
+			cli.DefaultSSHKeyPath),
 	)
 	cmd.Flags().StringVar(
 		&opts.version, "version", "latest",

cmd/uncloud/machine/rm.go

@@ -90,11 +90,13 @@ func remove(ctx context.Context, uncli *cli.CLI, nameOrID string, opts removeOpt
 
 	reset := !opts.noReset
 	var containers []api.ServiceContainer
+	reachable := false
 	if reset {
 		// Check if the machine is up and has service containers.
 		listOpts := container.ListOptions{All: true}
 		machineContainers, err := client.Docker.ListServiceContainers(mctx, "", listOpts)
 		if err == nil {
+			reachable = true
 			containers = machineContainers[0].Containers
 			if len(containers) > 0 {
 				plural := ""
@@ -104,7 +106,7 @@ func remove(ctx context.Context, uncli *cli.CLI, nameOrID string, opts removeOpt
 				fmt.Printf("Found %d service container%s on machine '%s':\n", len(containers), plural, m.Name)
 				fmt.Println(formatContainerTree(containers))
 				fmt.Println()
-				fmt.Println("This will remove all service containers on the machine, remove it from the cluster, " +
+				fmt.Println("This will remove all service containers from the machine, remove it from the cluster, " +
 					"and reset it to the uninitialised state.")
 			} else {
 				fmt.Printf("No service containers found on machine '%s'.\n", m.Name)
@@ -129,16 +131,14 @@ func remove(ctx context.Context, uncli *cli.CLI, nameOrID string, opts removeOpt
 		}
 	}
 
-	if reset {
-		if len(containers) > 0 {
-			err = progress.RunWithTitle(ctx, func(ctx context.Context) error {
-				return removeContainers(ctx, client, containers)
-			}, uncli.ProgressOut(), "Removing containers")
-			if err != nil {
-				return fmt.Errorf("remove containers: %w", err)
-			}
-			fmt.Println()
+	if reset && len(containers) > 0 {
+		err = progress.RunWithTitle(ctx, func(ctx context.Context) error {
+			return removeContainers(ctx, client, containers)
+		}, uncli.ProgressOut(), "Removing containers")
+		if err != nil {
+			return fmt.Errorf("remove containers: %w", err)
 		}
+		fmt.Println()
 	}
 
 	if _, err = client.RemoveMachine(ctx, &pb.RemoveMachineRequest{Id: m.Id}); err != nil {
@@ -146,7 +146,7 @@ func remove(ctx context.Context, uncli *cli.CLI, nameOrID string, opts removeOpt
 	}
 	fmt.Printf("Machine '%s' removed from the cluster.\n", m.Name)
 
-	if reset {
+	if reset && reachable {
 		_, err = client.MachineClient.Reset(mctx, &pb.ResetRequest{})
 		if err != nil {
 			fmt.Printf("WARNING: Failed to reset machine: %v\n", err)

internal/cli/cli.go

@@ -6,8 +6,8 @@ import (
 	"fmt"
 	"net/netip"
 	"os"
+	"slices"
 
-	"github.com/charmbracelet/huh"
 	"github.com/docker/cli/cli/streams"
 	"github.com/psviderski/uncloud/internal/cli/config"
 	"github.com/psviderski/uncloud/internal/fs"
@@ -22,7 +22,12 @@ import (
 	"google.golang.org/protobuf/types/known/emptypb"
 )
 
-const defaultContextName = "default"
+const (
+	// DefaultSSHKeyPath is the fallback location for the SSH private key when provisioning remote machines.
+	// Used when no key is explicitly provided and SSH agent authentication fails.
+	DefaultSSHKeyPath  = "~/.ssh/id_ed25519"
+	defaultContextName = "default"
+)
 
 type CLI struct {
 	Config *config.Config
@@ -173,7 +178,7 @@ func (cli *CLI) initRemoteMachine(ctx context.Context, opts InitClusterOptions)
 		return nil, fmt.Errorf("cluster context '%s' already exists", contextName)
 	}
 
-	machineClient, err := cli.provisionRemoteMachine(ctx, *opts.RemoteMachine, opts.Version)
+	machineClient, err := provisionRemoteMachine(ctx, opts.RemoteMachine, opts.Version)
 	if err != nil {
 		return nil, err
 	}
@@ -190,7 +195,7 @@ func (cli *CLI) initRemoteMachine(ctx context.Context, opts InitClusterOptions)
 		return nil, fmt.Errorf("inspect machine: %w", err)
 	}
 	if minfo.Id != "" {
-		if err = cli.promptResetMachine(); err != nil {
+		if err = promptResetMachine(ctx, machineClient.MachineClient); err != nil {
 			return nil, err
 		}
 	}
@@ -249,7 +254,7 @@ type AddMachineOptions struct {
 	Context       string
 	MachineName   string
 	PublicIP      *netip.Addr
-	RemoteMachine RemoteMachine
+	RemoteMachine *RemoteMachine
 	Version       string
 }
 
@@ -272,7 +277,7 @@ func (cli *CLI) AddMachine(ctx context.Context, opts AddMachineOptions) (*client
 		}
 	}()
 
-	machineClient, err := cli.provisionRemoteMachine(ctx, opts.RemoteMachine, opts.Version)
+	machineClient, err := provisionRemoteMachine(ctx, opts.RemoteMachine, opts.Version)
 	if err != nil {
 		return nil, nil, err
 	}
@@ -288,7 +293,18 @@ func (cli *CLI) AddMachine(ctx context.Context, opts AddMachineOptions) (*client
 		return nil, nil, fmt.Errorf("inspect machine: %w", err)
 	}
 	if minfo.Id != "" {
-		if err = cli.promptResetMachine(); err != nil {
+		// Check if the machine is already a member of this cluster.
+		machines, err := c.ListMachines(ctx, nil)
+		if err != nil {
+			return nil, nil, fmt.Errorf("list cluster machines: %w", err)
+		}
+		if slices.ContainsFunc(machines, func(m *pb.MachineMember) bool {
+			return m.Machine.Id == minfo.Id
+		}) {
+			return nil, nil, fmt.Errorf("machine is already a member of this cluster (%s)", minfo.Name)
+		}
+
+		if err = promptResetMachine(ctx, machineClient.MachineClient); err != nil {
 			return nil, nil, err
 		}
 	}
@@ -339,7 +355,7 @@ func (cli *CLI) AddMachine(ctx context.Context, opts AddMachineOptions) (*client
 		return nil, nil, fmt.Errorf("add machine to cluster (context '%s'): %w", contextName, err)
 	}
 
-	// List other machines in the cluster to include them in the join request.
+	// Get the most up-to-date list of other machines in the cluster to include them in the join request.
 	machines, err := c.ListMachines(ctx, nil)
 	if err != nil {
 		return nil, nil, fmt.Errorf("list cluster machines: %w", err)
@@ -382,11 +398,20 @@ func (cli *CLI) AddMachine(ctx context.Context, opts AddMachineOptions) (*client
 // provisionRemoteMachine installs the Uncloud daemon and dependencies on the remote machine over SSH and returns
 // a machine API client to interact with the machine. The client should be closed after use by the caller.
 // The version parameter specifies the version of the Uncloud daemon to install. If empty, the latest version is used.
-func (cli *CLI) provisionRemoteMachine(
-	ctx context.Context, remoteMachine RemoteMachine, version string,
+// The remoteMachine.SSHKeyPath could be updated to the default SSH key path if it is not set and the SSH agent
+// authentication fails.
+func provisionRemoteMachine(
+	ctx context.Context, remoteMachine *RemoteMachine, version string,
 ) (*client.Client, error) {
 	// Provision the remote machine by installing the Uncloud daemon and dependencies over SSH.
 	sshClient, err := sshexec.Connect(remoteMachine.User, remoteMachine.Host, remoteMachine.Port, remoteMachine.KeyPath)
+	// If the SSH connection using SSH agent fails and no key path is provided, try to use the default SSH key.
+	if err != nil && remoteMachine.KeyPath == "" {
+		remoteMachine.KeyPath = DefaultSSHKeyPath
+		sshClient, err = sshexec.Connect(
+			remoteMachine.User, remoteMachine.Host, remoteMachine.Port, remoteMachine.KeyPath,
+		)
+	}
 	if err != nil {
 		return nil, fmt.Errorf(
 			"SSH login to remote machine %s: %w",
@@ -420,31 +445,6 @@ func (cli *CLI) provisionRemoteMachine(
 	return machineClient, nil
 }
 
-func (cli *CLI) promptResetMachine() error {
-	var confirm bool
-	form := huh.NewForm(
-		huh.NewGroup(
-			huh.NewConfirm().
-				Title(
-					"The remote machine is already initialised as a cluster member. Do you want to reset it first?",
-				).
-				Affirmative("Yes!").
-				Negative("No").
-				Value(&confirm),
-		),
-	).WithAccessible(true)
-	if err := form.Run(); err != nil {
-		return fmt.Errorf("prompt user to confirm: %w", err)
-	}
-
-	if !confirm {
-		return fmt.Errorf("remote machine is already initialised as a cluster member")
-	}
-	// TODO: implement resetting the remote machine.
-	return fmt.Errorf("resetting the remote machine is not implemented yet. " +
-		"Please manually run 'uncloud-uninstall' on the remote machine to fully uninstall Uncloud from it")
-}
-
 // ProgressOut returns an output stream for progress writer.
 func (cli *CLI) ProgressOut() *streams.Out {
 	return streams.NewOut(os.Stdout)

internal/cli/machine.go

@@ -5,12 +5,20 @@ import (
 	"fmt"
 	"os"
 	"strings"
+	"time"
 
+	"github.com/cenkalti/backoff/v4"
+	"github.com/charmbracelet/huh"
+	"github.com/psviderski/uncloud/internal/machine/api/pb"
 	"github.com/psviderski/uncloud/internal/sshexec"
+	"google.golang.org/protobuf/types/known/emptypb"
 )
 
-// TODO: support pinning the script version to the CLI version.
-const installScriptURL = "https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/install.sh"
+const (
+	// TODO: support pinning the script version to the CLI version.
+	installScriptURL = "https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/install.sh"
+	rootUser         = "root"
+)
 
 type RemoteMachine struct {
 	User    string
@@ -24,7 +32,7 @@ func installCmd(user string, version string) string {
 	var env []string
 
 	// Add the SSH user (non-root) to the uncloud group to allow access to the Uncloud daemon unix socket.
-	if user != "root" {
+	if user != rootUser {
 		sudoPrefix = "sudo"
 		env = append(env, "UNCLOUD_GROUP_ADD_USER="+sshexec.Quote(user))
 	}
@@ -46,6 +54,26 @@ func provisionMachine(ctx context.Context, exec sshexec.Executor, version string
 		return fmt.Errorf("run whoami: %w", err)
 	}
 
+	if user != rootUser {
+		// 'sudo -n' is not used because it fails with 'sudo: a password is required' when the user has no password
+		// in /etc/shadow even though it may have valid sudo access.
+		out, err := exec.Run(ctx, "sudo true")
+		if err != nil {
+			if strings.Contains(out, "password is required") {
+				return fmt.Errorf(
+					"user '%[1]s' requires a password for sudo, but Uncloud needs passwordless sudo or root access "+
+						"to install and configure the uncloudd daemon on the remote machine.\n\n"+
+						"Possible solutions:\n"+
+						"1. Use root user or a user with passwordless sudo instead.\n"+
+						"2. Configure passwordless sudo for the user '%[1]s' by running on the remote machine:\n"+
+						"   echo '%[1]s ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/%[1]s",
+					user)
+			}
+			return fmt.Errorf("sudo command failed for user '%s': %w. "+
+				"Please ensure the user has sudo privileges or use root user instead", user, err)
+		}
+	}
+
 	cmd := installCmd(user, version)
 
 	fmt.Println("Downloading Uncloud install script:", installScriptURL)
@@ -56,3 +84,56 @@ func provisionMachine(ctx context.Context, exec sshexec.Executor, version string
 	}
 	return nil
 }
+
+func promptResetMachine(ctx context.Context, machineClient pb.MachineClient) error {
+	var confirm bool
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewConfirm().
+				Title(
+					"The remote machine is already initialised as a cluster member. Do you want to reset it first?\n" +
+						"This will:\n" +
+						"- Remove all service containers from the machine\n" +
+						"- Reset the machine to the uninitialised state",
+				).
+				Affirmative("Yes!").
+				Negative("No").
+				Value(&confirm),
+		),
+	).WithAccessible(true)
+	if err := form.Run(); err != nil {
+		return fmt.Errorf("prompt user to confirm: %w", err)
+	}
+
+	if !confirm {
+		return fmt.Errorf("remote machine is already initialised as a cluster member")
+	}
+
+	if _, err := machineClient.Reset(ctx, &pb.ResetRequest{}); err != nil {
+		return fmt.Errorf("reset remote machine: %w. You can also manually run 'uncloud-uninstall' "+
+			"on the remote machine to fully uninstall Uncloud from it", err)
+	}
+	fmt.Println("Resetting the remote machine...")
+	if err := waitMachineReady(ctx, machineClient, 1*time.Minute); err != nil {
+		return fmt.Errorf("wait for machine to be ready after reset: %w", err)
+	}
+
+	return nil
+}
+
+// waitMachineReady waits for the machine to be ready to serve requests.
+func waitMachineReady(ctx context.Context, machineClient pb.MachineClient, timeout time.Duration) error {
+	boff := backoff.WithContext(backoff.NewExponentialBackOff(
+		backoff.WithMaxInterval(1*time.Second),
+		backoff.WithMaxElapsedTime(timeout),
+	), ctx)
+
+	inspect := func() error {
+		_, err := machineClient.Inspect(ctx, &emptypb.Empty{})
+		if err != nil {
+			return fmt.Errorf("inspect machine: %w", err)
+		}
+		return nil
+	}
+	return backoff.Retry(inspect, boff)
+}

internal/machine/docker/server.go

@@ -546,10 +546,10 @@ func (s *Server) CreateServiceContainer(
 			Memory:            spec.Container.Resources.Memory,
 			MemoryReservation: spec.Container.Resources.MemoryReservation,
 		},
-		// Always restart service containers if they exit or a machine restarts.
+		// Restart service containers if they exit or a machine restarts unless they are explicitly stopped.
 		// For one-off containers and batch jobs we plan to use a different service type/mode.
 		RestartPolicy: container.RestartPolicy{
-			Name: container.RestartPolicyAlways,
+			Name: container.RestartPolicyUnlessStopped,
 		},
 	}
 

internal/machine/machine.go

@@ -446,10 +446,7 @@ func (m *Machine) Run(ctx context.Context) error {
 		slog.Info("Local API proxy server stopped.")
 
 		// Clean up the machine data and resources if the machine shutdown was initiated by a reset.
-		m.mu.RLock()
-		resetting := m.resetting
-		m.mu.RUnlock()
-		if resetting {
+		if m.resetting {
 			slog.Info("Cleaning up machine data and resources.")
 			if err = m.cleanup(); err != nil {
 				slog.Error("Failed to clean up machine data and resources.", "err", err)

pkg/client/compose/deploy.go

@@ -25,11 +25,16 @@ type Deployment struct {
 	Client       Client
 	Project      *types.Project
 	SpecResolver *deploy.ServiceSpecResolver
+	Strategy     deploy.Strategy
 	state        *scheduler.ClusterState
 	plan         *deploy.SequenceOperation
 }
 
 func NewDeployment(ctx context.Context, cli Client, project *types.Project) (*Deployment, error) {
+	return NewDeploymentWithStrategy(ctx, cli, project, nil)
+}
+
+func NewDeploymentWithStrategy(ctx context.Context, cli Client, project *types.Project, strategy deploy.Strategy) (*Deployment, error) {
 	state, err := scheduler.InspectClusterState(ctx, cli)
 	if err != nil {
 		return nil, fmt.Errorf("inspect cluster state: %w", err)
@@ -39,16 +44,20 @@ func NewDeployment(ctx context.Context, cli Client, project *types.Project) (*De
 	if err != nil && !errors.Is(err, api.ErrNotFound) {
 		return nil, fmt.Errorf("get cluster domain: %w", err)
 	}
-
 	resolver := &deploy.ServiceSpecResolver{
 		// If the domain is not found (not reserved), an empty domain is used for the resolver.
 		ClusterDomain: domain,
 	}
 
+	if strategy == nil {
+		strategy = &deploy.RollingStrategy{State: state}
+	}
+
 	return &Deployment{
 		Client:       cli,
 		Project:      project,
 		SpecResolver: resolver,
+		Strategy:     strategy,
 		state:        state,
 	}, nil
 }
@@ -90,7 +99,7 @@ func (d *Deployment) Plan(ctx context.Context) (deploy.SequenceOperation, error)
 	for _, spec := range serviceSpecs {
 		// TODO: properly handle depends_on conditions in the service deployment plan as the first operation.
 		// Pass the update cluster state with scheduled volumes to the deployment.
-		deployment := deploy.NewDeployment(d.Client, spec, &deploy.RollingStrategy{State: d.state})
+		deployment := deploy.NewDeployment(d.Client, spec, d.Strategy)
 		servicePlan, err := deployment.Plan(ctx)
 		if err != nil {
 			return plan, fmt.Errorf("create deployment plan for service '%s': %w", spec.Name, err)

pkg/client/connector/ssh.go

@@ -63,7 +63,7 @@ func (c *SSHConnector) Connect(ctx context.Context) (*grpc.ClientConn, error) {
 				conn, dErr := c.client.DialContext(ctx, "unix", addr)
 				if dErr != nil {
 					return nil, fmt.Errorf(
-						"connect to machine API socket '%s' through SSH tunnel (is the Uncloud daemon running "+
+						"connect to machine API socket '%s' through SSH tunnel (is uncloud.service running "+
 							"on the remote machine and does the SSH user '%s' have permissions to access the socket?):"+
 							" %w",
 						addr, c.client.User(), dErr,

pkg/client/deploy/strategy.go

@@ -25,7 +25,8 @@ type Strategy interface {
 // RollingStrategy implements a rolling update deployment pattern where containers are updated one at a time
 // to minimize service disruption.
 type RollingStrategy struct {
-	State *scheduler.ClusterState
+	State         *scheduler.ClusterState
+	ForceRecreate bool
 }
 
 func (s *RollingStrategy) Type() string {
@@ -92,7 +93,12 @@ func (s *RollingStrategy) planReplicated(svc *api.Service, spec api.ServiceSpec)
 				continue
 			}
 
-			status := EvalContainerSpecChange(c.Container.ServiceSpec, spec)
+			var status ContainerSpecStatus
+			if s.ForceRecreate {
+				status = ContainerNeedsRecreate
+			} else {
+				status = EvalContainerSpecChange(c.Container.ServiceSpec, spec)
+			}
 			containerSpecStatuses[c.Container.ID] = status
 
 			if status == ContainerUpToDate {
@@ -225,7 +231,7 @@ func (s *RollingStrategy) planGlobal(svc *api.Service, spec api.ServiceSpec) (Pl
 
 	for _, m := range availableMachines {
 		containers := containersOnMachine[m.Info.Id]
-		ops, err := reconcileGlobalContainer(containers, spec, plan.ServiceID, m.Info.Id)
+		ops, err := reconcileGlobalContainer(containers, spec, plan.ServiceID, m.Info.Id, s.ForceRecreate)
 		if err != nil {
 			return plan, err
 		}
@@ -252,7 +258,7 @@ func (s *RollingStrategy) planGlobal(svc *api.Service, spec api.ServiceSpec) (Pl
 // It ensures exactly one container with the desired spec is running on the machine by creating a new container and
 // removing old ones. If there is a host port conflict, it stops the old container before starting a new one.
 func reconcileGlobalContainer(
-	containers []api.MachineServiceContainer, spec api.ServiceSpec, serviceID, machineID string,
+	containers []api.MachineServiceContainer, spec api.ServiceSpec, serviceID, machineID string, forceRecreate bool,
 ) ([]Operation, error) {
 	var ops []Operation
 
@@ -274,7 +280,13 @@ func reconcileGlobalContainer(
 			continue
 		}
 
-		status := EvalContainerSpecChange(c.Container.ServiceSpec, spec)
+		var status ContainerSpecStatus
+		if forceRecreate {
+			status = ContainerNeedsRecreate
+		} else {
+			status = EvalContainerSpecChange(c.Container.ServiceSpec, spec)
+		}
+
 		if status == ContainerUpToDate {
 			// The container is already running with the same spec.
 			upToDate = true

test/e2e/assert.go

@@ -100,7 +100,7 @@ func assertContainerMatchesSpec(t *testing.T, ctr api.ServiceContainer, spec api
 	assert.Equal(t, portBindings, ctr.HostConfig.PortBindings)
 
 	assert.Equal(t, container.RestartPolicy{
-		Name:              container.RestartPolicyAlways,
+		Name:              container.RestartPolicyUnlessStopped,
 		MaximumRetryCount: 0,
 	}, ctr.HostConfig.RestartPolicy)
 

test/e2e/compose_deploy_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/psviderski/uncloud/internal/ucind"
 	"github.com/psviderski/uncloud/pkg/api"
 	"github.com/psviderski/uncloud/pkg/client/compose"
+	"github.com/psviderski/uncloud/pkg/client/deploy"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -34,14 +35,14 @@ func TestComposeDeployment(t *testing.T) {
 		project, err := compose.LoadProject(ctx, []string{"fixtures/compose-basic.yaml"})
 		require.NoError(t, err)
 
-		deploy, err := compose.NewDeployment(ctx, cli, project)
+		deployment, err := compose.NewDeployment(ctx, cli, project)
 		require.NoError(t, err)
 
-		plan, err := deploy.Plan(ctx)
+		plan, err := deployment.Plan(ctx)
 		require.NoError(t, err)
 		assert.Len(t, plan.Operations, 1, "Expected 1 service to deploy")
 
-		err = deploy.Run(ctx)
+		err = deployment.Run(ctx)
 		require.NoError(t, err)
 
 		svc, err := cli.InspectService(ctx, name)
@@ -71,6 +72,137 @@ func TestComposeDeployment(t *testing.T) {
 		assertServiceMatchesSpec(t, svc, expectedSpec)
 	})
 
+	t.Run("multi-service deployment with redeploy and recreate", func(t *testing.T) {
+		t.Parallel()
+
+		serviceNames := []string{
+			"test-compose-multi-web",
+			"test-compose-multi-api",
+			"test-compose-multi-worker",
+		}
+		t.Cleanup(func() {
+			removeServices(t, cli, serviceNames...)
+		})
+
+		// Initial deployment.
+		project, err := compose.LoadProject(ctx, []string{"fixtures/compose-multi-service.yaml"})
+		require.NoError(t, err)
+
+		deployment, err := compose.NewDeployment(ctx, cli, project)
+		require.NoError(t, err)
+
+		plan, err := deployment.Plan(ctx)
+		require.NoError(t, err)
+		assert.Len(t, plan.Operations, 3, "Expected 3 services to deploy")
+
+		err = deployment.Run(ctx)
+		require.NoError(t, err)
+
+		// Verify web service.
+		webSvc, err := cli.InspectService(ctx, "test-compose-multi-web")
+		require.NoError(t, err)
+		expectedWebSpec := api.ServiceSpec{
+			Name: "test-compose-multi-web",
+			Mode: api.ServiceModeReplicated,
+			Container: api.ContainerSpec{
+				Env: map[string]string{
+					"SERVICE": "web",
+					"VERSION": "1.0",
+				},
+				Image: "portainer/pause:3.9",
+			},
+			Ports: []api.PortSpec{
+				{
+					Hostname:      "multi.example.com",
+					ContainerPort: 80,
+					Protocol:      api.ProtocolHTTPS,
+					Mode:          api.PortModeIngress,
+				},
+			},
+			Replicas: 2,
+		}
+		assertServiceMatchesSpec(t, webSvc, expectedWebSpec)
+
+		// Verify api service.
+		apiSvc, err := cli.InspectService(ctx, "test-compose-multi-api")
+		require.NoError(t, err)
+		expectedApiSpec := api.ServiceSpec{
+			Name: "test-compose-multi-api",
+			Mode: api.ServiceModeReplicated,
+			Container: api.ContainerSpec{
+				Env: map[string]string{
+					"SERVICE": "api",
+					"PORT":    "8080",
+				},
+				Image: "portainer/pause:3.9",
+			},
+			Replicas: 3,
+		}
+		assertServiceMatchesSpec(t, apiSvc, expectedApiSpec)
+
+		// Verify worker service.
+		workerSvc, err := cli.InspectService(ctx, "test-compose-multi-worker")
+		require.NoError(t, err)
+		expectedWorkerSpec := api.ServiceSpec{
+			Name: "test-compose-multi-worker",
+			Mode: api.ServiceModeReplicated,
+			Container: api.ContainerSpec{
+				Env: map[string]string{
+					"SERVICE":     "worker",
+					"CONCURRENCY": "5",
+				},
+				Image: "portainer/pause:3.9",
+			},
+			Replicas: 1,
+		}
+		assertServiceMatchesSpec(t, workerSvc, expectedWorkerSpec)
+
+		// Save container IDs for later verification.
+		containers := serviceContainerIDs(webSvc).
+			Union(serviceContainerIDs(apiSvc)).
+			Union(serviceContainerIDs(workerSvc))
+
+		// Redeploy without changes - should be up to date.
+		redeploy, err := compose.NewDeployment(ctx, cli, project)
+		require.NoError(t, err)
+
+		redeployPlan, err := redeploy.Plan(ctx)
+		require.NoError(t, err)
+		assert.Len(t, redeployPlan.Operations, 0, "Expected no operations - deployment should be up to date")
+
+		// Deploy with ForceRecreate - should recreate all service containers.
+		strategy := &deploy.RollingStrategy{ForceRecreate: true}
+		recreateDeploy, err := compose.NewDeploymentWithStrategy(ctx, cli, project, strategy)
+		require.NoError(t, err)
+
+		recreatePlan, err := recreateDeploy.Plan(ctx)
+		require.NoError(t, err)
+		assert.Len(t, recreatePlan.Operations, 3, "Expected 3 services to be recreated")
+
+		err = recreateDeploy.Run(ctx)
+		require.NoError(t, err)
+
+		// Verify services match the expected specs after recreate.
+		webSvcAfter, err := cli.InspectService(ctx, "test-compose-multi-web")
+		require.NoError(t, err)
+		assertServiceMatchesSpec(t, webSvcAfter, expectedWebSpec)
+
+		apiSvcAfter, err := cli.InspectService(ctx, "test-compose-multi-api")
+		require.NoError(t, err)
+		assertServiceMatchesSpec(t, apiSvcAfter, expectedApiSpec)
+
+		workerSvcAfter, err := cli.InspectService(ctx, "test-compose-multi-worker")
+		require.NoError(t, err)
+		assertServiceMatchesSpec(t, workerSvcAfter, expectedWorkerSpec)
+
+		// Verify that all containers have been recreated.
+		afterContainers := serviceContainerIDs(webSvcAfter).
+			Union(serviceContainerIDs(apiSvcAfter)).
+			Union(serviceContainerIDs(workerSvcAfter))
+		assert.NotEqual(t, containers.ToSlice(), afterContainers.ToSlice(),
+			"Expected containers to be recreated after deployment with ForceRecreate strategy")
+	})
+
 	t.Run("multiple services with volumes", func(t *testing.T) {
 		t.Parallel()
 
@@ -94,10 +226,10 @@ func TestComposeDeployment(t *testing.T) {
 		project, err := compose.LoadProject(ctx, []string{"fixtures/compose-volumes.yaml"})
 		require.NoError(t, err)
 
-		deploy, err := compose.NewDeployment(ctx, cli, project)
+		deployment, err := compose.NewDeployment(ctx, cli, project)
 		require.NoError(t, err)
 
-		_, err = deploy.Plan(ctx)
+		_, err = deployment.Plan(ctx)
 		require.ErrorContains(t, err, "external volumes not found: 'test-compose-volumes-external'")
 
 		externalVolumeOpts := volume.CreateOptions{Name: "test-compose-volumes-external"}
@@ -105,14 +237,14 @@ func TestComposeDeployment(t *testing.T) {
 		require.NoError(t, err)
 
 		// Recreate the deployment as it caches the cluster state.
-		deploy, err = compose.NewDeployment(ctx, cli, project)
+		deployment, err = compose.NewDeployment(ctx, cli, project)
 		require.NoError(t, err)
 
-		plan, err := deploy.Plan(ctx)
+		plan, err := deployment.Plan(ctx)
 		require.NoError(t, err)
 		assert.Len(t, plan.Operations, 5, "Expected 2 volumes creation and 3 services to deploy")
 
-		err = deploy.Run(ctx)
+		err = deployment.Run(ctx)
 		require.NoError(t, err)
 
 		// Verify data1 and data2 volumes have been created.
@@ -247,10 +379,10 @@ func TestComposeDeployment(t *testing.T) {
 			"service3 should be on the same machine as external volume")
 
 		// Verify deployment is up-to-date.
-		deploy, err = compose.NewDeployment(ctx, cli, project)
+		deployment, err = compose.NewDeployment(ctx, cli, project)
 		require.NoError(t, err)
 
-		plan, err = deploy.Plan(ctx)
+		plan, err = deployment.Plan(ctx)
 		require.NoError(t, err)
 		assert.Len(t, plan.Operations, 0, "Expected no new operations after deployment")
 	})
@@ -266,14 +398,14 @@ func TestComposeDeployment(t *testing.T) {
 		project, err := compose.LoadProject(ctx, []string{"fixtures/compose-placement.yaml"})
 		require.NoError(t, err)
 
-		deploy, err := compose.NewDeployment(ctx, cli, project)
+		deployment, err := compose.NewDeployment(ctx, cli, project)
 		require.NoError(t, err)
 
-		plan, err := deploy.Plan(ctx)
+		plan, err := deployment.Plan(ctx)
 		require.NoError(t, err)
 		assert.Len(t, plan.Operations, 1, "Expected 1 service to deploy")
 
-		err = deploy.Run(ctx)
+		err = deployment.Run(ctx)
 		require.NoError(t, err)
 
 		svc, err := cli.InspectService(ctx, name)
@@ -319,14 +451,14 @@ func TestComposeDeployment(t *testing.T) {
 		project, err := compose.LoadProject(ctx, []string{"fixtures/compose-placement-nonexistent.yaml"})
 		require.NoError(t, err)
 
-		deploy, err := compose.NewDeployment(ctx, cli, project)
+		deployment, err := compose.NewDeployment(ctx, cli, project)
 		require.NoError(t, err)
 
-		plan, err := deploy.Plan(ctx)
+		plan, err := deployment.Plan(ctx)
 		require.NoError(t, err)
 		assert.Len(t, plan.Operations, 1, "Expected 1 service to deploy")
 
-		err = deploy.Run(ctx)
+		err = deployment.Run(ctx)
 		require.NoError(t, err)
 
 		svc, err := cli.InspectService(ctx, name)
@@ -367,14 +499,14 @@ func TestComposeDeployment(t *testing.T) {
 		project, err := compose.LoadProject(ctx, []string{"fixtures/compose-placement-comma.yaml"})
 		require.NoError(t, err)
 
-		deploy, err := compose.NewDeployment(ctx, cli, project)
+		deployment, err := compose.NewDeployment(ctx, cli, project)
 		require.NoError(t, err)
 
-		plan, err := deploy.Plan(ctx)
+		plan, err := deployment.Plan(ctx)
 		require.NoError(t, err)
 		assert.Len(t, plan.Operations, 1, "Expected 1 service to deploy")
 
-		err = deploy.Run(ctx)
+		err = deployment.Run(ctx)
 		require.NoError(t, err)
 
 		svc, err := cli.InspectService(ctx, name)

test/e2e/fixtures/compose-multi-service.yaml

@@ -0,0 +1,24 @@
+services:
+  test-compose-multi-web:
+    image: portainer/pause:3.9
+    environment:
+      SERVICE: web
+      VERSION: "1.0"
+    deploy:
+      replicas: 2
+    x-ports:
+      - multi.example.com:80/https
+
+  test-compose-multi-api:
+    image: portainer/pause:3.9
+    environment:
+      SERVICE: api
+      PORT: "8080"
+    deploy:
+      replicas: 3
+
+  test-compose-multi-worker:
+    image: portainer/pause:3.9
+    environment:
+      SERVICE: worker
+      CONCURRENCY: "5"

test/e2e/service_test.go

@@ -279,35 +279,11 @@ func TestDeployment(t *testing.T) {
 
 		svc, err := cli.InspectService(ctx, client.CaddyServiceName)
 		require.NoError(t, err)
-		assert.Equal(t, client.CaddyServiceName, svc.Name)
-		assert.Equal(t, api.ServiceModeGlobal, svc.Mode)
 		assert.Len(t, svc.Containers, 3)
+		assertServiceMatchesSpec(t, svc, deployment.Spec)
 
 		ctr := svc.Containers[0].Container
 		assert.Regexp(t, `^caddy:2\.\d+\.\d+$`, ctr.Config.Image)
-
-		ports, err := ctr.ServicePorts()
-		require.NoError(t, err)
-		expectedPorts := []api.PortSpec{
-			{
-				PublishedPort: 80,
-				ContainerPort: 80,
-				Protocol:      api.ProtocolTCP,
-				Mode:          api.PortModeHost,
-			},
-			{
-				PublishedPort: 443,
-				ContainerPort: 443,
-				Protocol:      api.ProtocolTCP,
-				Mode:          api.PortModeHost,
-			},
-		}
-		assert.Equal(t, expectedPorts, ports)
-
-		assert.Equal(t, container.RestartPolicy{
-			Name:              container.RestartPolicyAlways,
-			MaximumRetryCount: 0,
-		}, ctr.HostConfig.RestartPolicy)
 	})
 
 	t.Run("caddy with machine placement", func(t *testing.T) {

website/docs/2-getting-started/2-deploy-demo-app.md

@@ -9,8 +9,8 @@ infrastructure with secure internet access.
 Before you begin, you'll need:
 
 - **Uncloud CLI** [installed](1-install-cli.md) on your local machine
-- A **Ubuntu or Debian server** with **public IP address** and **SSH access** (as `root` or a user with `sudo`
-  privileges) using a **private key**.
+- A **Ubuntu or Debian server** with **public IP address** and **SSH access** using a **private key** (as `root` or a
+  user with **passwordless** `sudo` privileges).
 
 :::tip Need a server?
 
@@ -273,9 +273,11 @@ Add a CNAME record `excalidraw.example.com` in your DNS provider (Cloudflare, Na
 
 :::info note
 
-These instructions set up your own domain _in addition to_ uncloud's managed DNS service.
+These instructions set up your own domain **in addition to** the Uncloud managed DNS name
+`excalidraw.7za6s7.cluster.uncloud.run`.
 
-If you want to avoid the managed service altogether, add `--no-dns` to your `uc machine init` command, and point an `A`-type DNS record to your server(s)'s IP(s).
+If you want to avoid the managed service altogether, add `--no-dns` to your `uc machine init` command, and point an A
+DNS record to your server(s)'s IP(s).
 
 :::