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.

Avoid repeated server payloads in Docker image layers

pulse-triage[bot]09299b60e7e4
diff --git a/.github/workflows/container-packaging.yml b/.github/workflows/container-packaging.yml
new file mode 100644
index 0000000000..ce5989f4fd
--- /dev/null
+++ b/.github/workflows/container-packaging.yml
@@ -0,0 +1,100 @@
+name: Container packaging
+
+# Product packaging regression, not a release build or publication. Both images
+# receive identical immutable public fixture bytes; only the Dockerfile differs.
+on:
+ pull_request:
+ branches: [main]
+ paths:
+ - Dockerfile
+ - docker-entrypoint.sh
+ - docker-healthcheck.sh
+ - scripts/prepare-release-container-context.sh
+ - scripts/test-container-packaging.py
+ - scripts/tests/test_container_packaging.py
+ - .github/workflows/container-packaging.yml
+ push:
+ branches: [main]
+ paths:
+ - Dockerfile
+ - docker-entrypoint.sh
+ - docker-healthcheck.sh
+ - scripts/prepare-release-container-context.sh
+ - scripts/test-container-packaging.py
+ - scripts/tests/test_container_packaging.py
+ - .github/workflows/container-packaging.yml
+
+permissions:
+ contents: read
+
+concurrency:
+ group: container-packaging-${{ github.ref }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+ packaging:
+ name: Same-payload packaging (${{ matrix.arch }})
+ runs-on: ubuntu-24.04
+ timeout-minutes: 30
+ strategy:
+ fail-fast: false
+ matrix:
+ arch: [amd64, arm64]
+ steps:
+ - name: Check out proposed source
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ fetch-depth: 0
+
+ - name: Test inventory and failure controls
+ run: python3 scripts/tests/test_container_packaging.py
+
+ - name: Set up QEMU
+ uses: docker/setup-qemu-action@1f40c72289eff860ee54a304f1438e3cff362e0a # v4.3.0
+ with:
+ platforms: arm64
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+
+ - name: Prepare immutable public fixture
+ # Release 423296089 is immutable. These exact archive digests are fixture
+ # identities, not a moving latest/version selector or signing authority.
+ run: |
+ set -euo pipefail
+ mkdir -p "$RUNNER_TEMP/packaging-fixture"
+ for arch in amd64 arm64; do
+ file="pulse-v6.6.0-linux-${arch}.tar.gz"
+ curl --disable --fail --location --proto '=https' --proto-redir '=https' \
+ --connect-timeout 15 --max-time 300 \
+ "https://github.com/rcourtman/Pulse/releases/download/v6.6.0/${file}" \
+ --output "$RUNNER_TEMP/packaging-fixture/${file}"
+ done
+ (cd "$RUNNER_TEMP/packaging-fixture" && sha256sum --check <<'HASHES'
+ 593d9422caa52286ab22ad332e5990ccd515f84f7496853c577cfccab162a0b8 pulse-v6.6.0-linux-amd64.tar.gz
+ a39e0ff47c825b58bc9e93ee9ded20544cd812202a923a1ca257b00b91db6900 pulse-v6.6.0-linux-arm64.tar.gz
+ HASHES
+ )
+ bash scripts/prepare-release-container-context.sh \
+ "$RUNNER_TEMP/packaging-fixture" 6.6.0 "$RUNNER_TEMP/packaging-payload"
+
+ - name: Compare exact parent packaging and exercise runtime
+ env:
+ BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+ ARCH: ${{ matrix.arch }}
+ run: |
+ set -euo pipefail
+ python3 scripts/test-container-packaging.py \
+ --base "$BASE_SHA" --arch "$ARCH" \
+ --payload "$RUNNER_TEMP/packaging-payload" \
+ --output "packaging-receipts/${ARCH}.json"
+
+ - name: Retain source-bound measurement and partial failures
+ if: always()
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+ with:
+ name: container-packaging-${{ matrix.arch }}-${{ github.sha }}
+ path: packaging-receipts/
+ if-no-files-found: error
+ retention-days: 7
diff --git a/Dockerfile b/Dockerfile
index 19334e4caa..f574b74254 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -316,9 +316,10 @@ FROM pulse-runtime-foundation AS pulse-runtime-base
ARG TARGETARCH
-COPY --from=backend-builder /app/pulse-linux-${TARGETARCH:-amd64} ./pulse
-COPY --from=backend-builder /app/VERSION .
-RUN chmod +x ./pulse && chown pulse:pulse ./pulse ./VERSION
+# Assign metadata while copying: a later chown/chmod layer carries the large
+# binary again even though its contents have not changed.
+COPY --from=backend-builder --chown=pulse:pulse --chmod=0755 /app/pulse-linux-${TARGETARCH:-amd64} ./pulse
+COPY --from=backend-builder --chown=pulse:pulse /app/VERSION .
# Exact-candidate runtime base. release_payload is a named BuildKit context
# produced from the verified linux-amd64 and linux-arm64 release archives.
@@ -326,9 +327,8 @@ FROM pulse-runtime-foundation AS prebuilt-runtime-base
ARG TARGETARCH
-COPY --from=release_payload /${TARGETARCH:-amd64}/bin/pulse ./pulse
-COPY --from=release_payload /${TARGETARCH:-amd64}/VERSION .
-RUN chmod +x ./pulse && chown pulse:pulse ./pulse ./VERSION
+COPY --from=release_payload --chown=pulse:pulse --chmod=0755 /${TARGETARCH:-amd64}/bin/pulse ./pulse
+COPY --from=release_payload --chown=pulse:pulse /${TARGETARCH:-amd64}/VERSION .
# Hosted tenant runtime excludes embedded release installer and agent artifacts.
# Those endpoints can still proxy canonical release assets instead of requiring
@@ -345,23 +345,22 @@ FROM pulse-runtime-base AS e2e_runtime
FROM pulse-runtime-base AS runtime
# Provide installer scripts for HTTP download endpoints
-RUN mkdir -p /opt/pulse/scripts
-COPY scripts/install-container-agent.sh /opt/pulse/scripts/install-container-agent.sh
-COPY scripts/install-docker.sh /opt/pulse/scripts/install-docker.sh
-COPY --from=release-assets-builder /app/rendered-installers/install.sh /opt/pulse/scripts/install.sh
-COPY --from=release-assets-builder /app/rendered-installers/install.sh.sig /opt/pulse/scripts/install.sh.sig
-COPY --from=release-assets-builder /app/rendered-installers/install.sh.sshsig /opt/pulse/scripts/install.sh.sshsig
-COPY --from=release-assets-builder /app/rendered-installers/install.ps1 /opt/pulse/scripts/install.ps1
-COPY --from=release-assets-builder /app/rendered-installers/install.ps1.sig /opt/pulse/scripts/install.ps1.sig
-COPY --from=release-assets-builder /app/rendered-installers/install.ps1.sshsig /opt/pulse/scripts/install.ps1.sshsig
-RUN chmod 755 /opt/pulse/scripts/*.sh /opt/pulse/scripts/*.ps1
+RUN mkdir -p /opt/pulse/scripts /opt/pulse/bin && \
+ chown pulse:pulse /opt/pulse /opt/pulse/scripts /opt/pulse/bin
+COPY --chown=pulse:pulse --chmod=0755 scripts/install-container-agent.sh /opt/pulse/scripts/install-container-agent.sh
+COPY --chown=pulse:pulse --chmod=0755 scripts/install-docker.sh /opt/pulse/scripts/install-docker.sh
+COPY --chown=pulse:pulse --chmod=0755 --from=release-assets-builder /app/rendered-installers/install.sh /opt/pulse/scripts/install.sh
+COPY --chown=pulse:pulse --from=release-assets-builder /app/rendered-installers/install.sh.sig /opt/pulse/scripts/install.sh.sig
+COPY --chown=pulse:pulse --from=release-assets-builder /app/rendered-installers/install.sh.sshsig /opt/pulse/scripts/install.sh.sshsig
+COPY --chown=pulse:pulse --chmod=0755 --from=release-assets-builder /app/rendered-installers/install.ps1 /opt/pulse/scripts/install.ps1
+COPY --chown=pulse:pulse --from=release-assets-builder /app/rendered-installers/install.ps1.sig /opt/pulse/scripts/install.ps1.sig
+COPY --chown=pulse:pulse --from=release-assets-builder /app/rendered-installers/install.ps1.sshsig /opt/pulse/scripts/install.ps1.sshsig
# Copy all binaries for download endpoint
-RUN mkdir -p /opt/pulse/bin
# Main pulse server binary (for validation) - copy both architectures
-COPY --from=backend-builder /app/pulse-linux-amd64 /opt/pulse/bin/pulse-linux-amd64
-COPY --from=backend-builder /app/pulse-linux-arm64 /opt/pulse/bin/pulse-linux-arm64
+COPY --chown=pulse:pulse --from=backend-builder /app/pulse-linux-amd64 /opt/pulse/bin/pulse-linux-amd64
+COPY --chown=pulse:pulse --from=backend-builder /app/pulse-linux-arm64 /opt/pulse/bin/pulse-linux-arm64
RUN if [ "$TARGETARCH" = "arm64" ]; then \
ln -s pulse-linux-arm64 /opt/pulse/bin/pulse; \
else \
@@ -369,7 +368,7 @@ RUN if [ "$TARGETARCH" = "arm64" ]; then \
fi
# Unified agent binaries (all platforms and architectures) plus detached signatures
-COPY --from=release-assets-builder /app/pulse-agent-* /opt/pulse/bin/
+COPY --chown=pulse:pulse --from=release-assets-builder /app/pulse-agent-* /opt/pulse/bin/
# Create complete binary/signature aliases for Windows without .exe extension.
# The download handler resolves this name and reads detached sidecars beside it.
RUN ln -s pulse-agent-windows-amd64.exe /opt/pulse/bin/pulse-agent-windows-amd64 && \
@@ -381,7 +380,7 @@ RUN ln -s pulse-agent-windows-amd64.exe /opt/pulse/bin/pulse-agent-windows-amd64
ln -s pulse-agent-windows-386.exe /opt/pulse/bin/pulse-agent-windows-386 && \
ln -s pulse-agent-windows-386.exe.sig /opt/pulse/bin/pulse-agent-windows-386.sig && \
ln -s pulse-agent-windows-386.exe.sshsig /opt/pulse/bin/pulse-agent-windows-386.sshsig && \
- chown -R pulse:pulse /opt/pulse
+ find /opt/pulse/bin -maxdepth 1 -type l -exec chown -h pulse:pulse {} +
# Arch-resolved /usr/local/bin/pulse-agent so the helm chart's agent workload
# and `docker run rcourtman/pulse --entrypoint /usr/local/bin/pulse-agent`
@@ -397,21 +396,28 @@ RUN if [ "$TARGETARCH" = "arm64" ]; then \
ln -s /opt/pulse/bin/pulse-agent-linux-amd64 /usr/local/bin/pulse-agent; \
fi
+# Normalise executable metadata outside the runtime's retained layers. The
+# agent glob includes detached sidecars: COPY --chmod on that glob would make
+# signatures executable too. Keep every candidate byte and sidecar unchanged.
+FROM alpine:3.24@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS prebuilt-downloads
+
+COPY --from=release_payload /amd64/scripts/ /payload/scripts/
+COPY --from=release_payload /amd64/bin/pulse-agent-* /payload/bin/
+COPY --from=release_payload /amd64/bin/pulse /payload/bin/pulse-linux-amd64
+COPY --from=release_payload /arm64/bin/pulse /payload/bin/pulse-linux-arm64
+RUN chmod 755 /payload/scripts/*.sh /payload/scripts/*.ps1 && \
+ find /payload/bin -maxdepth 1 -type f -name 'pulse-agent-*' \
+ ! -name '*.sig' ! -name '*.sshsig' -exec chmod 755 {} +
+
# Release qualification and publication target assembled from the immutable
-# candidate rather than recompiling source inside Docker.
+# candidate rather than recompiling source inside Docker. A single final copy
+# sets ownership without another layer containing the complete download set.
FROM prebuilt-runtime-base AS runtime_prebuilt
ARG TARGETARCH
-RUN mkdir -p /opt/pulse/scripts /opt/pulse/bin
-COPY --from=release_payload /amd64/scripts/ /opt/pulse/scripts/
-COPY --from=release_payload /amd64/bin/pulse-agent-* /opt/pulse/bin/
-COPY --from=release_payload /amd64/bin/pulse /opt/pulse/bin/pulse-linux-amd64
-COPY --from=release_payload /arm64/bin/pulse /opt/pulse/bin/pulse-linux-arm64
-RUN chmod 755 /opt/pulse/scripts/*.sh /opt/pulse/scripts/*.ps1 && \
- find /opt/pulse/bin -maxdepth 1 -type f -name 'pulse-agent-*' \
- ! -name '*.sig' ! -name '*.sshsig' -exec chmod 755 {} + && \
- if [ "$TARGETARCH" = "arm64" ]; then \
+COPY --from=prebuilt-downloads --chown=pulse:pulse /payload/ /opt/pulse/
+RUN if [ "$TARGETARCH" = "arm64" ]; then \
ln -sf pulse-linux-arm64 /opt/pulse/bin/pulse; \
ln -sf /opt/pulse/bin/pulse-agent-linux-arm64 /usr/local/bin/pulse-agent; \
else \
@@ -427,7 +433,7 @@ RUN chmod 755 /opt/pulse/scripts/*.sh /opt/pulse/scripts/*.ps1 && \
ln -sf pulse-agent-windows-386.exe /opt/pulse/bin/pulse-agent-windows-386 && \
ln -sf pulse-agent-windows-386.exe.sig /opt/pulse/bin/pulse-agent-windows-386.sig && \
ln -sf pulse-agent-windows-386.exe.sshsig /opt/pulse/bin/pulse-agent-windows-386.sshsig && \
- chown -R pulse:pulse /opt/pulse
+ find /opt/pulse/bin -maxdepth 1 -type l -exec chown -h pulse:pulse {} +
# Unified Agent image assembled from the same immutable candidate payload.
FROM alpine:3.24@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS agent_runtime_prebuilt
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index cf0ee7723a..63c8430e6c 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -16,6 +16,37 @@
## Purpose
+### Duplicate-free Docker payload layers (29 October 2026)
+
+The server runtime keeps its existing final binary bytes, cross-platform
+agent/helper/runner downloads, detached sidecars, Windows aliases, native-agent
+entrypoint, UID handling and health configuration. Large regular payload files
+must occur in only one retained filesystem layer per path. Source-built copies
+set ownership at COPY; the server sets executable mode there too. Prebuilt
+agent/script modes are normalised in a discarded staging image, then copied
+with final ownership. Signature sidecars remain non-executable. Final alias
+ownership changes touch links only, never recursively copy up regular payload.
+No download set is removed and no published tag is rewritten.
+
+The ordinary `Container packaging` PR/main workflow uses fresh hosted runners,
+read-only repository permission and identical digest-pinned immutable v6.6.0
+fixture archives for base and candidate Dockerfiles on amd64 and arm64. It
+compares final payload hashes, modes, owners and links, preserves runtime
+configuration, rejects repeated payload paths across layers, and exercises the
+real isolated server's health, default/custom UID, every bundled download's
+body/signature headers and native agent entrypoint. It publishes nothing.
+
+Receipts distinguish Docker's uncompressed size, uncompressed layer tar bytes,
+reencoded per-layer gzip bytes and fresh merged-rootfs regular-file bytes.
+Reencoding is not the registry's original transfer size; mutable container data
+and volumes are not image bytes. Source/mode/inventory unit controls and a green
+workflow definition do not establish real image savings or reporter recovery.
+Inspect both actual CI receipts, runtime results and owned cleanup before using
+a measurement. The fixed older application payload tests packaging equivalence,
+not the proposed application's runtime or next release's exact image size.
+`TestContainerPackagingProofIsReadOnlyAndSamePayload` and the normally discovered
+`test_container_packaging.py` preserve this boundary and its failure controls.
+
### OIDC JOSE security graph (28 October 2026)
The root graph advances only go-jose/v4 from 4.1.4 to 4.1.6 for the reachable
diff --git a/scripts/installtests/build_release_assets_test.go b/scripts/installtests/build_release_assets_test.go
index 2d858b1123..6867dd2b74 100644
--- a/scripts/installtests/build_release_assets_test.go
+++ b/scripts/installtests/build_release_assets_test.go
@@ -639,10 +639,11 @@ func TestReleaseContainerTargetsConsumeImmutableCandidate(t *testing.T) {
for _, needle := range []string{
"FROM pulse-runtime-foundation AS prebuilt-runtime-base",
- "COPY --from=release_payload /${TARGETARCH:-amd64}/bin/pulse ./pulse",
+ "COPY --from=release_payload --chown=pulse:pulse --chmod=0755 /${TARGETARCH:-amd64}/bin/pulse ./pulse",
"FROM prebuilt-runtime-base AS runtime_prebuilt",
- "COPY --from=release_payload /amd64/bin/pulse /opt/pulse/bin/pulse-linux-amd64",
- "COPY --from=release_payload /arm64/bin/pulse /opt/pulse/bin/pulse-linux-arm64",
+ "COPY --from=prebuilt-downloads --chown=pulse:pulse /payload/ /opt/pulse/",
+ "COPY --from=release_payload /amd64/bin/pulse /payload/bin/pulse-linux-amd64",
+ "COPY --from=release_payload /arm64/bin/pulse /payload/bin/pulse-linux-arm64",
"! -name '*.sig' ! -name '*.sshsig' -exec chmod 755 {} +",
"FROM alpine:3.24@sha256:",
"AS agent_runtime_prebuilt",
@@ -5806,3 +5807,53 @@ func TestProviderMSPStartupWorkflowRequiresMountedDaemonAcceptance(t *testing.T)
t.Fatal("missing mounted-daemon acceptance or unsafe credential/event scope")
}
}
+
+// Real Docker execution belongs to the fresh hosted PR job, not the worker's
+// daemon. Keep its fixture, exact source, read-only scope and negative controls
+// registered alongside the immutable-candidate packaging contract.
+func TestContainerPackagingProofIsReadOnlyAndSamePayload(t *testing.T) {
+ content, err := os.ReadFile(repoFile(".github", "workflows", "container-packaging.yml"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ var workflow struct {
+ Permissions map[string]string
+ Jobs map[string]struct {
+ RunsOn string `yaml:"runs-on"`
+ Timeout int `yaml:"timeout-minutes"`
+ Steps []struct {
+ Run, Uses string
+ With map[string]string
+ }
+ }
+ }
+ if err := yaml.Unmarshal(content, &workflow); err != nil {
+ t.Fatal(err)
+ }
+ if len(workflow.Permissions) != 1 || workflow.Permissions["contents"] != "read" || len(workflow.Jobs) != 1 {
+ t.Fatal("packaging proof must retain read-only permissions and one isolated matrix job")
+ }
+ job := workflow.Jobs["packaging"]
+ if job.RunsOn != "ubuntu-24.04" || job.Timeout != 30 {
+ t.Fatal("packaging proof must use a fresh, bounded hosted runner")
+ }
+ for _, step := range job.Steps {
+ if strings.Contains(step.Run, "secrets.") || strings.Contains(step.Uses, "login-action") ||
+ strings.Contains(step.Run, "--push") || strings.Contains(step.Run, "workflow run") {
+ t.Fatal("packaging proof must not publish or acquire a mutation credential")
+ }
+ }
+ assertFileContainsAll(t, repoFile(".github", "workflows", "container-packaging.yml"),
+ "arch: [amd64, arm64]", "persist-credentials: false", "fetch-depth: 0",
+ "python3 scripts/tests/test_container_packaging.py", "sha256sum --check",
+ "593d9422caa52286ab22ad332e5990ccd515f84f7496853c577cfccab162a0b8",
+ "a39e0ff47c825b58bc9e93ee9ded20544cd812202a923a1ca257b00b91db6900",
+ `--base "$BASE_SHA" --arch "$ARCH"`, "if-no-files-found: error",
+ )
+ assertFileContainsAll(t, repoFile("scripts", "test-container-packaging.py"),
+ `"--target", "runtime_prebuilt"`, `"--network", "none"`,
+ `compare(before["payload_rootfs"], after["payload_rootfs"])`,
+ `no_payload_copyups(after["layers"])`, `records["runtime"] = runtime_checks`,
+ `records["result"] = "failed"`, `"merged_rootfs_regular_file_bytes"`,
+ )
+}
diff --git a/scripts/test-container-packaging.py b/scripts/test-container-packaging.py
new file mode 100644
index 0000000000..8a55f886b5
--- /dev/null
+++ b/scripts/test-container-packaging.py
@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""Same-payload Docker packaging regression. Run only on disposable CI Docker.
+
+No publication, registry credentials or release qualification. The immutable
+published fixture is deliberately independent of the proposed application code.
+"""
+import argparse
+import hashlib
+import json
+import subprocess
+import tarfile
+import tempfile
+import time
+import zlib
+from pathlib import Path
+
+
+OWNED_PREFIXES = ("opt/pulse/",)
+OWNED_FILES = {"app/pulse", "app/VERSION", "usr/local/bin/pulse-agent", "opt/pulse"}
+
+
+def owned(name):
+ return name in OWNED_FILES or name.startswith(OWNED_PREFIXES)
+
+
+def digest(stream):
+ h = hashlib.sha256()
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def inventory(stream, totals=None):
+ """Never extract image paths or follow links on the runner."""
+ records = {}
+ regular_bytes = 0
+ with tarfile.open(fileobj=stream, mode="r|*") as archive:
+ for member in archive:
+ if member.isfile():
+ regular_bytes += member.size
+ name = member.name.removeprefix("./").rstrip("/")
+ if not owned(name):
+ continue
+ if name in records:
+ raise ValueError(f"duplicate exported path: {name}")
+ record = dict(mode=member.mode, uid=member.uid, gid=member.gid,
+ type=member.type.decode("ascii"), size=member.size,
+ link=member.linkname)
+ if member.isfile():
+ record["sha256"] = digest(archive.extractfile(member))
+ records[name] = record
+ if totals is not None:
+ totals["merged_rootfs_regular_file_bytes"] = regular_bytes
+ return records
+
+
+def layers(stream):
+ """Docker-save uncompressed bytes and explicit *reencoded* gzip sizes.
+
+ Reencoding each layer is comparable, not the registry's original compression
+ or a multi-platform index size. Neither number includes writable volumes.
+ """
+ result = []
+ with tarfile.open(fileobj=stream, mode="r|*") as outer:
+ for entry in outer:
+ if not entry.name.endswith("/layer.tar"):
+ continue
+ compressor = zlib.compressobj(level=6, wbits=31)
+ compressed = 0
+ contents = outer.extractfile(entry)
+ # Stream once into an owned temporary file; never expand its paths.
+ with tempfile.TemporaryFile() as raw:
+ for chunk in iter(lambda: contents.read(1024 * 1024), b""):
+ compressed += len(compressor.compress(chunk))
+ raw.write(chunk)
+ compressed += len(compressor.flush())
+ raw.seek(0)
+ files = inventory(raw)
+ result.append(dict(uncompressed_tar_bytes=entry.size,
+ reencoded_gzip_bytes=compressed, files=files))
+ if not result:
+ raise ValueError("Docker save returned no filesystem layers")
+ return result
+
+
+def no_payload_copyups(layer_records):
+ seen = set()
+ for layer in layer_records:
+ for name, record in layer["files"].items():
+ if record["type"] not in ("0", "\0"):
+ continue
+ if name in seen:
+ raise ValueError(f"payload stored in more than one layer: {name}")
+ seen.add(name)
+ if "app/pulse" not in seen or not any(n.startswith("opt/pulse/bin/") for n in seen):
+ raise ValueError("runtime payload missing from layer inventory")
+
+
+def compare(before, after):
+ if before != after:
+ changed = sorted(n for n in before.keys() | after.keys() if before.get(n) != after.get(n))
+ raise ValueError(f"packaging changed final payload bytes/metadata/links: {changed}")
+
+
+def command(*args):
+ return subprocess.check_output(args, text=True).strip()
+
+
+def stream_command(args, reader):
+ # Always drain/observe the exact process, including parser failures.
+ with subprocess.Popen(args, stdout=subprocess.PIPE) as process:
+ try:
+ result = reader(process.stdout)
+ finally:
+ for _ in iter(lambda: process.stdout.read(1024 * 1024), b""):
+ pass
+ status = process.wait()
+ if status:
+ raise subprocess.CalledProcessError(status, args)
+ return result
+
+
+# The container has no network other than its own loopback. Every download must
+# come from its bundled payload, not GitHub fallback. Check actual headers/body
+# through the running server, not a substitute fixture web page.
+DOWNLOAD_CHECK = r'''
+import base64, hashlib, json, pathlib, urllib.request
+root = pathlib.Path('/opt/pulse')
+requests = [('/install.sh', root/'scripts/install.sh'),
+ ('/install.ps1', root/'scripts/install.ps1')]
+linux = ['amd64', 'arm64', 'armv7', 'armv6', '386']
+for family, arches in [('pulse-agent', ['linux-'+a for a in linux] +
+ ['darwin-amd64', 'darwin-arm64', 'freebsd-amd64',
+ 'freebsd-arm64', 'windows-amd64', 'windows-arm64', 'windows-386']),
+ ('pulse-agent-helper', ['linux-'+a for a in linux]),
+ ('pulse-agent-runner', ['linux-'+a for a in linux])]:
+ for arch in arches:
+ name = family+'-'+arch+('.exe' if arch.startswith('windows-') else '')
+ requests.append(('/download/'+family+'?arch='+arch, root/'bin'/name))
+receipts = []
+for route, path in requests:
+ assert path.stat().st_mode & 0o111, str(path)
+ for suffix in ['.sig', '.sshsig']:
+ assert not (pathlib.Path(str(path)+suffix).stat().st_mode & 0o111), str(path)+suffix
+ with urllib.request.urlopen('http://127.0.0.1:7655'+route, timeout=30) as response:
+ h = hashlib.sha256()
+ for chunk in iter(lambda: response.read(1024*1024), b''): h.update(chunk)
+ with path.open('rb') as f: expected = hashlib.file_digest(f, 'sha256').hexdigest()
+ assert h.hexdigest() == expected, route
+ if route.startswith('/download/'):
+ assert response.headers['X-Checksum-Sha256'] == expected, route
+ assert response.headers['X-Signature-Ed25519'] == pathlib.Path(str(path)+'.sig').read_text().strip(), route
+ assert base64.b64decode(response.headers['X-Signature-SSHSIG']) == pathlib.Path(str(path)+'.sshsig').read_bytes(), route
+ receipts.append({'route': route, 'sha256': expected, 'signature_headers': True})
+print(json.dumps(receipts))
+'''
+
+
+def runtime_checks(image, arch):
+ receipts = []
+ for uid in (1000, 2345):
+ container = command("docker", "run", "-d", "--network", "none", "-e", f"PUID={uid}",
+ "-e", f"PGID={uid}", image)
+ try:
+ deadline = time.monotonic() + 90
+ while True:
+ status = command("docker", "inspect", "--format", "{{.State.Health.Status}}", container)
+ if status == "healthy":
+ break
+ if status == "unhealthy" or time.monotonic() > deadline:
+ raise RuntimeError(f"container health did not recover: {status}")
+ time.sleep(2)
+ actual = command("docker", "exec", container, "sh", "-ec",
+ "awk '/^Uid:/{print $2}' /proc/1/status; stat -c '%u:%g' /data")
+ if actual != f"{uid}\n{uid}:{uid}":
+ raise ValueError(f"wrong running UID or data owner: {actual}")
+ download = json.loads(command("docker", "exec", container, "python3", "-c", DOWNLOAD_CHECK))
+ receipts.append(dict(uid=uid, health=status, downloads=download))
+ finally:
+ subprocess.run(["docker", "rm", "-fv", container], check=True)
+ version = command("docker", "run", "--rm", "--network", "none", "--entrypoint",
+ "/usr/local/bin/pulse-agent", image, "--version")
+ if "6.6.0" not in version:
+ raise ValueError("native agent entrypoint did not execute the fixture version")
+ return dict(platform=f"linux/{arch}", native_agent_version=version, server=receipts)
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--base", required=True)
+ parser.add_argument("--payload", type=Path, required=True)
+ parser.add_argument("--arch", choices=("amd64", "arm64"), required=True)
+ parser.add_argument("--output", type=Path, required=True)
+ args = parser.parse_args()
+ if len(args.base) != 40 or any(c not in "0123456789abcdef" for c in args.base):
+ parser.error("base must be an exact commit")
+ head = command("git", "rev-parse", "HEAD")
+ baseline = subprocess.check_output(["git", "show", f"{args.base}:Dockerfile"])
+ records = dict(source_sha=head, base_sha=args.base, platform=f"linux/{args.arch}",
+ fixture_release="v6.6.0", fixture_release_id=423296089, images={},
+ dockerfiles_sha256=dict(base=hashlib.sha256(baseline).hexdigest(),
+ candidate=hashlib.sha256(Path("Dockerfile").read_bytes()).hexdigest()),
+ size_basis="Per-platform image/layer and fresh merged-rootfs bytes; gzip is reencoded, not original registry transfer. Writable data/volumes excluded.")
+ tags = []
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ try:
+ with tempfile.TemporaryDirectory(prefix="pulse-packaging-") as directory:
+ base_file = Path(directory)/"Dockerfile.base"
+ base_file.write_bytes(baseline)
+ for label, dockerfile in (("base", base_file), ("candidate", Path("Dockerfile"))):
+ tag = f"pulse-packaging-{label}:{args.arch}"
+ tags.append(tag)
+ subprocess.run(["docker", "buildx", "build", "--file", str(dockerfile),
+ "--target", "runtime_prebuilt", "--platform", f"linux/{args.arch}",
+ "--build-context", f"release_payload={args.payload.resolve()}",
+ "--load", "--tag", tag, "."], check=True)
+ info = json.loads(command("docker", "image", "inspect", tag))[0]
+ image_layers = stream_command(["docker", "image", "save", tag], layers)
+ container = command("docker", "create", "--network", "none", tag)
+ rootfs_totals = {}
+ try:
+ rootfs = stream_command(["docker", "export", container],
+ lambda stream: inventory(stream, rootfs_totals))
+ finally:
+ subprocess.run(["docker", "rm", "-v", container], check=True)
+ records["images"][label] = dict(image_id=info["Id"], config=info["Config"],
+ engine_uncompressed_bytes=info["Size"], layers=image_layers, payload_rootfs=rootfs,
+ **rootfs_totals,
+ payload_rootfs_file_bytes=sum(f["size"] for f in rootfs.values() if "sha256" in f),
+ uncompressed_layer_tar_bytes=sum(l["uncompressed_tar_bytes"] for l in image_layers),
+ reencoded_gzip_layer_bytes=sum(l["reencoded_gzip_bytes"] for l in image_layers))
+ if label == "base":
+ # Keep receipts, not a second multi-GB image, for comparison.
+ subprocess.run(["docker", "image", "rm", tag], check=True)
+ tags.remove(tag)
+ before, after = (records["images"][n] for n in ("base", "candidate"))
+ compare(before["payload_rootfs"], after["payload_rootfs"])
+ for field in ("Env", "Entrypoint", "Cmd", "Healthcheck", "WorkingDir", "User", "Volumes", "ExposedPorts"):
+ compare({field: before["config"].get(field)}, {field: after["config"].get(field)})
+ no_payload_copyups(after["layers"])
+ records["runtime"] = runtime_checks(tags[0], args.arch)
+ records["result"] = "passed"
+ except Exception as error:
+ records["result"] = "failed"
+ records["error"] = dict(type=type(error).__name__, detail=str(error)[:2000])
+ raise
+ finally:
+ # A partial/failed measurement is retained, never labelled a pass.
+ records["cleanup"] = []
+ for tag in tags:
+ result = subprocess.run(["docker", "image", "rm", tag], check=False)
+ records["cleanup"].append(dict(image=tag, exit=result.returncode))
+ cleanup_failed = any(r["exit"] for r in records["cleanup"])
+ if cleanup_failed:
+ records["result"] = "failed"
+ records["cleanup_error"] = "owned image cleanup failed"
+ args.output.write_text(json.dumps(records, indent=2)+"\n")
+ if cleanup_failed:
+ raise RuntimeError("owned image cleanup failed")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/tests/test_container_packaging.py b/scripts/tests/test_container_packaging.py
new file mode 100644
index 0000000000..814185de07
--- /dev/null
+++ b/scripts/tests/test_container_packaging.py
@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Packaging's normal smoke-suite controls; no Docker daemon is used here."""
+import hashlib
+import importlib.util
+import io
+import json
+import subprocess
+import tarfile
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+spec = importlib.util.spec_from_file_location('packaging', ROOT/'scripts/test-container-packaging.py')
+packaging = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(packaging)
+
+
+def archive(files):
+ stream = io.BytesIO()
+ with tarfile.open(fileobj=stream, mode='w') as tar:
+ for name, data, kind in files:
+ member = tarfile.TarInfo(name)
+ member.uid = member.gid = 1000
+ member.mode = 0o755
+ if kind == 'file':
+ member.size = len(data)
+ tar.addfile(member, io.BytesIO(data))
+ else:
+ member.type = tarfile.SYMTYPE
+ member.linkname = data
+ tar.addfile(member)
+ return stream.getvalue()
+
+
+class InventoryTests(unittest.TestCase):
+ def test_bytes_metadata_and_links_are_retained_without_extraction(self):
+ blob = archive([('app/pulse', b'actual-server', 'file'),
+ ('opt/pulse/bin/agent', b'agent', 'file'),
+ ('usr/local/bin/pulse-agent', '/opt/pulse/bin/agent', 'link'),
+ ('etc/hostname', b'ephemeral', 'file')])
+ result = packaging.inventory(io.BytesIO(blob))
+ self.assertEqual(set(result), {'app/pulse', 'opt/pulse/bin/agent', 'usr/local/bin/pulse-agent'})
+ self.assertEqual(result['app/pulse']['sha256'], hashlib.sha256(b'actual-server').hexdigest())
+ self.assertEqual(result['app/pulse']['uid'], 1000)
+ self.assertEqual(result['app/pulse']['mode'], 0o755)
+ self.assertEqual(result['usr/local/bin/pulse-agent']['link'], '/opt/pulse/bin/agent')
+
+ def test_duplicate_exported_paths_are_not_silently_overwritten(self):
+ with self.assertRaisesRegex(ValueError, 'duplicate exported path'):
+ packaging.inventory(io.BytesIO(archive([('app/pulse', b'a', 'file')]*2)))
+
+ def test_layer_inventory_counts_repeated_payload_and_explicit_reencoding(self):
+ layer = archive([('app/pulse', b'server', 'file'), ('opt/pulse/bin/agent', b'agent', 'file')])
+ image = archive([('one/layer.tar', layer, 'file'), ('two/layer.tar', layer, 'file')])
+ measured = packaging.layers(io.BytesIO(image))
+ self.assertEqual(len(measured), 2)
+ self.assertEqual(sum(l['uncompressed_tar_bytes'] for l in measured), len(layer)*2)
+ self.assertTrue(all(0 < l['reencoded_gzip_bytes'] < len(layer) for l in measured))
+ packaging.no_payload_copyups(measured[:1])
+ with self.assertRaisesRegex(ValueError, 'more than one layer'):
+ packaging.no_payload_copyups(measured)
+
+ def test_absent_layer_or_payload_cannot_pass(self):
+ with self.assertRaisesRegex(ValueError, 'no filesystem layers'):
+ packaging.layers(io.BytesIO(archive([])))
+ with self.assertRaisesRegex(ValueError, 'payload missing'):
+ packaging.no_payload_copyups([])
+
+ def test_every_compatibility_dimension_is_checked(self):
+ baseline = packaging.inventory(io.BytesIO(archive([('app/pulse', b'server', 'file')])))
+ for key, value in [('sha256', 'different'), ('mode', 0o644), ('uid', 0),
+ ('gid', 0), ('link', 'wrong'), ('size', 0), ('type', '2')]:
+ with self.subTest(key=key), self.assertRaisesRegex(ValueError, 'changed final payload'):
+ changed = json.loads(json.dumps(baseline))
+ changed['app/pulse'][key] = value
+ packaging.compare(baseline, changed)
+ with self.assertRaises(ValueError):
+ packaging.compare(baseline, {})
+
+ def test_process_failure_cannot_become_a_successful_inventory(self):
+ with self.assertRaises(subprocess.CalledProcessError):
+ packaging.stream_command(['sh', '-c', 'printf partial; exit 19'], lambda f: f.read())
+
+
+class DockerfileTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ text = (ROOT/'Dockerfile').read_text().replace('\\\n', '')
+ cls.stages = {}
+ current = None
+ for line in text.splitlines():
+ if line.startswith('FROM '):
+ current = line.split(' AS ')[1]
+ cls.stages[current] = []
+ elif current and line.strip() and not line.startswith('#'):
+ cls.stages[current].append(line)
+
+ def test_final_server_copies_assign_metadata_before_any_runtime_layer(self):
+ for stage in ['pulse-runtime-base', 'prebuilt-runtime-base']:
+ commands = self.stages[stage]
+ pulse = next(c for c in commands if c.startswith('COPY ') and c.endswith(' ./pulse'))
+ self.assertIn('--chown=pulse:pulse', pulse)
+ self.assertIn('--chmod=0755', pulse)
+ self.assertFalse(any(c.startswith('RUN ') for c in commands))
+
+ def test_all_source_payload_copies_have_final_ownership_not_recursive_copyup(self):
+ commands = self.stages['runtime']
+ for copy in (c for c in commands if c.startswith('COPY ')):
+ self.assertIn('--chown=pulse:pulse', copy)
+ if copy.endswith(('.sh', '.ps1')):
+ self.assertIn('--chmod=0755', copy)
+ text = '\n'.join(commands)
+ self.assertNotIn('chown -R', text)
+ self.assertIn('-type l -exec chown -h pulse:pulse {} +', text)
+
+ def test_final_candidate_copy_is_single_owned_payload_and_links_only(self):
+ commands = self.stages['runtime_prebuilt']
+ copies = [c for c in commands if c.startswith('COPY ')]
+ self.assertEqual(copies, ['COPY --from=prebuilt-downloads --chown=pulse:pulse /payload/ /opt/pulse/'])
+ text = '\n'.join(commands)
+ self.assertNotIn('chmod', text)
+ self.assertNotIn('chown -R', text)
+ self.assertIn('-type l -exec chown -h pulse:pulse {} +', text)
+ for arch in ['amd64', 'arm64', '386']:
+ for suffix in ['', '.sig', '.sshsig']:
+ self.assertIn(f'pulse-agent-windows-{arch}.exe{suffix}', text)
+
+ def test_actual_staging_recipe_preserves_every_byte_and_nonexecutable_sidecar(self):
+ recipe = next(c[4:] for c in self.stages['prebuilt-downloads'] if c.startswith('RUN '))
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp)/'payload'
+ (root/'bin').mkdir(parents=True)
+ (root/'scripts').mkdir()
+ files = {}
+ for family, arches in [('pulse-agent', ['linux-amd64', 'linux-arm64', 'linux-armv7',
+ 'linux-armv6', 'linux-386', 'darwin-amd64', 'darwin-arm64', 'windows-amd64.exe',
+ 'windows-arm64.exe', 'windows-386.exe', 'freebsd-amd64', 'freebsd-arm64']),
+ ('pulse-agent-helper', ['linux-'+a for a in ['amd64','arm64','armv7','armv6','386']]),
+ ('pulse-agent-runner', ['linux-'+a for a in ['amd64','arm64','armv7','armv6','386']])]:
+ for arch in arches:
+ for suffix in ['', '.sig', '.sshsig']:
+ files[root/'bin'/f'{family}-{arch}{suffix}'] = suffix == ''
+ for arch in ['amd64', 'arm64']:
+ files[root/'bin'/f'pulse-linux-{arch}'] = True
+ for script in ['install.sh','install.ps1','install-container-agent.sh','install-docker.sh']:
+ files[root/'scripts'/script] = True
+ if script in ['install.sh','install.ps1']:
+ for suffix in ['.sig','.sshsig']:
+ files[root/'scripts'/(script+suffix)] = False
+ for path, executable in files.items():
+ path.write_bytes(path.name.encode())
+ path.chmod(0o755 if path.name.startswith('pulse-linux-') else 0o644)
+ before = {p: p.read_bytes() for p in files}
+ subprocess.run(['sh', '-ec', recipe.replace('/payload', str(root))], check=True)
+ for path, executable in files.items():
+ with self.subTest(path=path.name):
+ self.assertEqual(path.read_bytes(), before[path])
+ self.assertEqual(path.stat().st_mode & 0o777, 0o755 if executable else 0o644)
+
+
+if __name__ == '__main__':
+ unittest.main()