Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Keep Docker update plans on the saved deployment

pulse-triage[bot]816b20bfc587
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index 658cc857e0..0f3363e3e4 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -15,6 +15,30 @@
## Purpose
+### Docker server update plans preserve the saved deployment
+
+The existing update-plan API and banner's copyable instructions must not guess
+the container name or a replacement command without the operator's deployment
+definition. The Community Docker plan provides only a shell-literal image pull;
+it then requires a consistent private mounted-data backup, the previous image
+and the original Compose, saved run or container-manager definition. Recreation
+keeps mounts, ports, environment and restart policy, affects only Pulse and uses
+the actual service/container name. A failed pull leaves the running container
+unchanged; a second Pulse must not share its data. Installed image, version and
+health need readback, and image rollback alone cannot undo data migrations.
+
+Configured image repositories and the version remain one literal POSIX shell
+argument, including quotes, substitutions, whitespace and newlines. No backend
+shell execution, automatic Docker apply, schema change, guessed stop/remove/run
+or Compose mutation is added. The Pro edition still withholds Community pulls
+and uses its private digest-pinned broker/portal route.
+
+`TestDockerUpdatePlanPreservesSavedDeployment`, the real-shell
+`TestDockerUpdatePullInstructionIsLiteral` controls (a function replaces Docker,
+never a daemon), and `TestHandleGetUpdatePlan_DockerSavedDeployment` verify plan
+safety and the actual JSON handler path. These are source/recipe proofs, not a
+native Docker upgrade, published availability or an installed recovery result.
+
### Server service discovery cannot short-read or default after an unknown inventory
The server installer consumes one bounded, complete `systemctl list-unit-files`
diff --git a/internal/api/updates_test.go b/internal/api/updates_test.go
index 08c8a6e64e..adb1bdb2e9 100644
--- a/internal/api/updates_test.go
+++ b/internal/api/updates_test.go
@@ -1060,6 +1060,41 @@ func TestUpdateHandlersRegistryProvidesPlans(t *testing.T) {
}
}
+func TestHandleGetUpdatePlan_DockerSavedDeployment(t *testing.T) {
+ setMockModeForTest(t, true)
+ t.Setenv("PULSE_DOCKER_IMAGE_REPO", "registry.example:5000/team/pulse")
+ h := NewUpdateHandlers(nil, nil)
+ // Exercise the real registered adapter through the handler, independent
+ // of the test host's deployment detection and without a Docker daemon.
+ h.registry.Register("mock", updates.NewDockerUpdater())
+ w := httptest.NewRecorder()
+ r := httptest.NewRequest(http.MethodGet, "/api/updates/plan?version=v6.5.0", nil)
+ h.HandleGetUpdatePlan(w, r)
+ if w.Code != http.StatusOK {
+ t.Fatalf("plan status = %d: %s", w.Code, w.Body.String())
+ }
+ var plan updates.UpdatePlan
+ if err := json.NewDecoder(w.Body).Decode(&plan); err != nil {
+ t.Fatal(err)
+ }
+ if plan.CanAutoUpdate || plan.RequiresRoot || !plan.RollbackSupport {
+ t.Fatalf("Docker plan capabilities changed: %+v", plan)
+ }
+ if len(plan.Instructions) != 5 || plan.Instructions[0] != "docker pull 'registry.example:5000/team/pulse:6.5.0'" {
+ t.Fatalf("copyable Docker plan = %v", plan.Instructions)
+ }
+ for _, instruction := range plan.Instructions[1:] {
+ if strings.HasPrefix(instruction, "docker ") || strings.Contains(instruction, "--name pulse") {
+ t.Fatalf("wire plan guesses a deployment mutation: %q", instruction)
+ }
+ }
+ if !strings.Contains(plan.Instructions[2], "original Compose file") ||
+ !strings.Contains(plan.Instructions[3], "leave the running container unchanged") ||
+ len(plan.Prerequisites) != 2 {
+ t.Fatalf("saved-deployment safety did not reach the API: %+v", plan)
+ }
+}
+
func TestHandleGetUpdatePlan_IncludesUpgradeReadiness(t *testing.T) {
setMockModeForTest(t, true)
diff --git a/internal/updates/adapter_installsh.go b/internal/updates/adapter_installsh.go
index fcd558e192..47d3417710 100644
--- a/internal/updates/adapter_installsh.go
+++ b/internal/updates/adapter_installsh.go
@@ -98,9 +98,15 @@ func (u *DockerUpdater) PrepareUpdate(ctx context.Context, request UpdateRequest
return &UpdatePlan{
CanAutoUpdate: false,
Instructions: []string{
- fmt.Sprintf("docker pull %s", imageRef),
- "docker stop pulse",
- fmt.Sprintf("docker run -d --name pulse %s", imageRef),
+ "docker pull " + quoteShellArgument(imageRef),
+ "Before recreating Pulse, record the current image and take a consistent private backup of its mounted data. Keep the previous image and backup; do not delete volumes.",
+ "Set the image above in the original Compose file, saved docker run command or container manager. Recreate only Pulse with the same data mounts, ports, environment and restart policy, using your actual service or container name.",
+ "If the image pull failed, leave the running container unchanged. Do not start a second Pulse against the same data.",
+ "Check the running image, Pulse version and health after recreation. Rolling back an image alone does not undo data migrations.",
+ },
+ Prerequisites: []string{
+ "Access to the original saved deployment and the Docker daemon",
+ "A consistent private backup of the mounted Pulse data and the previous image reference",
},
RequiresRoot: false,
RollbackSupport: true,
@@ -108,6 +114,13 @@ func (u *DockerUpdater) PrepareUpdate(ctx context.Context, request UpdateRequest
}, nil
}
+// The plan is copyable in the update banner. Keep even a caller-supplied version
+// or configured repository as one literal argument, never shell syntax. The
+// server cannot infer a safe replacement command from its own container.
+func quoteShellArgument(value string) string {
+ return "'" + strings.ReplaceAll(value, "'", "'\\''") + "'"
+}
+
// AURUpdater provides instructions for Arch Linux AUR deployments
type AURUpdater struct{}
diff --git a/internal/updates/adapter_installsh_test.go b/internal/updates/adapter_installsh_test.go
index 62f0c207d6..e1b183cd0b 100644
--- a/internal/updates/adapter_installsh_test.go
+++ b/internal/updates/adapter_installsh_test.go
@@ -2,7 +2,13 @@ package updates
import (
"context"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "runtime"
+ "strings"
"testing"
+ "time"
)
func TestDockerUpdater(t *testing.T) {
@@ -25,12 +31,9 @@ func TestDockerUpdater(t *testing.T) {
if err != nil {
t.Fatalf("PrepareUpdate() error = %v", err)
}
- if got := plan.Instructions[0]; got != "docker pull rcourtman/pulse:4.25.0" {
+ if got := plan.Instructions[0]; got != "docker pull 'rcourtman/pulse:4.25.0'" {
t.Fatalf("pull instruction = %q", got)
}
- if got := plan.Instructions[2]; got != "docker run -d --name pulse rcourtman/pulse:4.25.0" {
- t.Fatalf("run instruction = %q", got)
- }
})
t.Run("PrepareUpdate uses configured image repo", func(t *testing.T) {
@@ -40,15 +43,99 @@ func TestDockerUpdater(t *testing.T) {
if err != nil {
t.Fatalf("PrepareUpdate() error = %v", err)
}
- if got := plan.Instructions[0]; got != "docker pull example/pulse-enterprise:4.25.0" {
+ if got := plan.Instructions[0]; got != "docker pull 'example/pulse-enterprise:4.25.0'" {
t.Fatalf("pull instruction = %q", got)
}
- if got := plan.Instructions[2]; got != "docker run -d --name pulse example/pulse-enterprise:4.25.0" {
- t.Fatalf("run instruction = %q", got)
- }
})
}
+func TestDockerUpdatePlanPreservesSavedDeployment(t *testing.T) {
+ t.Setenv("PULSE_DOCKER_IMAGE_REPO", "")
+ plan, err := NewDockerUpdater().PrepareUpdate(context.Background(), UpdateRequest{Version: "v6.5.0"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if plan.CanAutoUpdate || plan.RequiresRoot || !plan.RollbackSupport {
+ t.Fatalf("manual Docker plan capabilities changed: %+v", plan)
+ }
+ // Only the image pull is a shell recipe. We do not know the operator's
+ // service name, Compose project, mounts or recreation/recovery procedure.
+ for _, instruction := range plan.Instructions[1:] {
+ if strings.HasPrefix(instruction, "docker ") || strings.Contains(instruction, "--name pulse") {
+ t.Fatalf("plan guesses a deployment mutation: %q", instruction)
+ }
+ }
+ text := strings.Join(plan.Instructions, "\n")
+ for _, required := range []string{
+ "consistent private backup", "do not delete volumes", "original Compose file",
+ "saved docker run command", "container manager", "same data mounts, ports, environment and restart policy",
+ "actual service or container name", "pull failed, leave the running container unchanged",
+ "Do not start a second Pulse", "running image, Pulse version and health",
+ "does not undo data migrations",
+ } {
+ if !strings.Contains(text, required) {
+ t.Errorf("Docker plan omits %q", required)
+ }
+ }
+ if len(plan.Prerequisites) != 2 || !strings.Contains(plan.Prerequisites[0], "original saved deployment") {
+ t.Fatalf("saved deployment prerequisite absent: %v", plan.Prerequisites)
+ }
+}
+
+func TestDockerUpdatePullInstructionIsLiteral(t *testing.T) {
+ if runtime.GOOS == "windows" {
+ t.Skip("the copied Docker plan is a POSIX shell recipe")
+ }
+ bash, err := exec.LookPath("bash")
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, tc := range []struct{ name, repository, version string }{
+ {"stable", "", "v6.5.0"},
+ {"preview", "registry.example:5000/team/pulse", "6.6.0-rc.1"},
+ {"blank-override", " ", "v6.5.0"},
+ {"version-shell-syntax", "", "v6.5.0; printf unexpected > \"$DOCKER_PLAN_SENTINEL\" #"},
+ {"repository-shell-syntax", "example/pulse'; printf unexpected > \"$DOCKER_PLAN_SENTINEL\"; #", "v6.5.0"},
+ {"substitution", "$(printf unexpected > \"$DOCKER_PLAN_SENTINEL\")/pulse", "v6.5.0"},
+ {"multiline", "example/pulse", "v6.5.0\nprintf unexpected > \"$DOCKER_PLAN_SENTINEL\""},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Setenv("PULSE_DOCKER_IMAGE_REPO", tc.repository)
+ plan, err := NewDockerUpdater().PrepareUpdate(context.Background(), UpdateRequest{Version: tc.version})
+ if err != nil {
+ t.Fatal(err)
+ }
+ directory := t.TempDir()
+ capture, sentinel := filepath.Join(directory, "arguments"), filepath.Join(directory, "unexpected")
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+ // This function replaces Docker entirely. No daemon, socket or
+ // external image is used; the actual shell parses the copied text.
+ cmd := exec.CommandContext(ctx, bash, "-c", `
+docker() { printf '%s\0' "$@" > "$DOCKER_PLAN_CAPTURE"; }
+eval "$DOCKER_PLAN_COMMAND"
+`)
+ cmd.Env = append(os.Environ(), "DOCKER_PLAN_COMMAND="+plan.Instructions[0],
+ "DOCKER_PLAN_CAPTURE="+capture, "DOCKER_PLAN_SENTINEL="+sentinel)
+ if output, err := cmd.CombinedOutput(); err != nil {
+ t.Fatalf("copied pull failed: %v: %s", err, output)
+ }
+ repository := strings.TrimSpace(tc.repository)
+ if repository == "" {
+ repository = defaultDockerImageRepo
+ }
+ want := "pull\x00" + repository + ":" + strings.TrimPrefix(tc.version, "v") + "\x00"
+ got, err := os.ReadFile(capture)
+ if err != nil || string(got) != want {
+ t.Errorf("copied pull arguments = %q, %v; want %q", got, err, want)
+ }
+ if _, err := os.Lstat(sentinel); !os.IsNotExist(err) {
+ t.Errorf("copied pull executed embedded shell syntax: %v", err)
+ }
+ })
+ }
+}
+
func TestAURUpdater(t *testing.T) {
updater := NewAURUpdater()