Choose your path

Both paths produce the same end state: a new image version running on the device. They differ in who pulls the trigger and how traceable the rollout is. Most teams start with the manual path and graduate to the automated path once releases settle into a cadence.

Prerequisites

Before either update path, make sure your build environment, registry account, and target devices are ready.

Dockerfile templates for ALPON

Every update starts with a rebuilt image. Use these production-tested Dockerfile templates as a starting point. All templates use slim or alpine base images, install only runtime dependencies, run as a non-root user, and produce small layer caches that push quickly over cellular links.

Common rules across stacks

• Always pin the base image to a specific minor version (for example, python:3.12-slim instead of python:slim).
• Use multi-stage builds for compiled languages (Go, Rust, Node TypeScript) to keep runtime images small.
• Copy requirements.txt, package.json, or go.mod before the rest of the source so Docker can cache dependency layers.
• Set WORKDIR /app and run the process as a non-root USER when possible.
• Define EXPOSE with the container-side port, not the host port. Host ports are configured at deploy time in ALPON Cloud and must fall in the 30000-32767 range.

Pick a starting point

Python application

For a Python service such as an MQTT publisher, REST API, or data collector. The template installs system dependencies in a single layer, then installs Python packages in a separate cached layer.

FROM python:3.12-slim AS base

ENV PYTHONDONTWRITEBYTECODE=1     PYTHONUNBUFFERED=1     PIP_NO_CACHE_DIR=1

WORKDIR /app

# System packages (kept minimal for cellular pull speed)
RUN apt-get update && apt-get install --no-install-recommends -y       ca-certificates curl     && rm -rf /var/lib/apt/lists/*

# Dependency layer (cached unless requirements.txt changes)
COPY requirements.txt ./
RUN pip install -r requirements.txt

# Application code
COPY . .

USER 1000:1000
EXPOSE 8080
CMD ["python", "-u", "main.py"]

Node.js application

For a Node.js HTTP service or worker. The multi-stage build separates dependency installation from the runtime image, producing a slimmer final layer.

# Stage 1 - install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

# Stage 2 - runtime
FROM node:20-alpine AS runtime
ENV NODE_ENV=production
WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules
COPY . .

USER node
EXPOSE 3000
CMD ["node", "server.js"]

Go application

For a compiled Go binary. The build stage compiles statically for ARM64, then the runtime stage uses scratch or alpine for a minimal image, often under 20 MB.

# Stage 1 - build for ARM64
FROM --platform=$BUILDPLATFORM golang:1.22-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
ENV CGO_ENABLED=0 GOOS=linux GOARCH=arm64
RUN go build -ldflags="-s -w" -o /out/app ./cmd/app

# Stage 2 - minimal runtime
FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=build /out/app /usr/local/bin/app
USER 1000:1000
EXPOSE 8080
CMD ["/usr/local/bin/app"]

Static site or Nginx reverse proxy

For a static frontend, dashboard, or thin Nginx layer in front of another container. Useful as a quick smoke test image too.

FROM nginx:1.27-alpine

# Static assets
COPY ./dist /usr/share/nginx/html

# Optional custom server block
COPY ./nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Tagging strategy

How you tag releases determines how you update them. The two patterns below cover almost every team's needs. You can also use both at once: ship every release with both an immutable tag and the :latest alias.

Manual update from the dashboard

The fastest path. You build and push from your workstation, then drive the rollout from ALPON Cloud with two clicks. Use this path for small fleets, staging environments, or one-off urgent fixes.

1. 1

   Authenticate to the registry

   From your build host, log in to cr.sixfab.io with the 6-digit username from the Registry page in ALPON Cloud. If you have not set a password yet, click Reset Password on that page and save the displayed value (it is shown once).

   

   bash

   docker login cr.sixfab.io --username <your_username>
   # Password: paste the registry password (hidden input)

2. 2

   Rebuild for ARM64 and tag

   Build the image with Docker Buildx, targeting linux/arm64, then tag it with the full registry path. Pick the new tag according to your tagging strategy.

   bash

   # 1. Build for ARM64 from the Dockerfile directory
   docker buildx build --load --platform linux/arm64   -t my-app:v1.2.3 .
   
   # 2. Tag with the registry path
   docker tag my-app:v1.2.3 cr.sixfab.io/<your_username>/my-app:v1.2.3

3. 3

   Push the new image

   Upload the image to your private repository. Layer caching means only changed layers are transferred. Refresh the Registry page in ALPON Cloud to confirm the new tag, size, and digest appear.

   bash

   docker push cr.sixfab.io/<your_username>/my-app:v1.2.3
   
   # The push refers to repository [cr.sixfab.io/719663/my-app]
   571fd9f78ac9: Pushed
   v1.2.3: digest: sha256:2aeab3830f8eaf2775fd599fda6a516a95c1480239ba5e64a632a68c1f3bd53d
   size: 31.07 MB

   

4. 4

   Roll the update out to the device

   Open the device's Assets → Applications tab in ALPON Cloud. Pick the action that matches your tagging strategy.

   If you re-pushed a mutable tag (:latest)

   Click Restart next to the running container. The device stops the container, pulls the latest digest from cr.sixfab.io, and starts a fresh instance. State held in mounted volumes is preserved; state in the container filesystem is reset.

   If you pushed a new immutable tag (:v1.2.3)

   Click Edit Deployment, change the image tag in the form, and save. The new tag is pulled and the container is recreated. Environment variables, ports, and volume mounts are preserved unless you change them in the form.

5. 5

   Verify the new version is running

   Watch the status flip back to Running in the Applications list. Then open Logs to confirm startup messages from the new version, or open the Container Terminal and inspect a version file or environment variable that you bumped with the release.

   

   See Verify the rollout for the full post-update checklist.

Automated update from CI/CD

The Sixfab Container Registry is a standard OCI registry, so any CI system that can run Docker can build and push to it. To turn a CI push into a live rollout, pair the push step with a call to the Sixfab Developer API that triggers a restart on every device running the deployment.

GitHub Actions: build, push, and trigger restart

Store the following values as repository secrets before running the workflow:

• SIXFAB_REGISTRY_USERNAME: your 6-digit registry username
• SIXFAB_REGISTRY_PASSWORD: your registry password
• SIXFAB_API_KEY: a Developer API key with asset management scope
• ASSET_ID: the ID of the device (or asset group) to update

name: Build, push, and roll out to ALPON

on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Sixfab Registry
        uses: docker/login-action@v3
        with:
          registry: cr.sixfab.io
          username: ${{ secrets.SIXFAB_REGISTRY_USERNAME }}
          password: ${{ secrets.SIXFAB_REGISTRY_PASSWORD }}

      - name: Build and push (linux/arm64)
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/arm64
          push: true
          tags: |
            cr.sixfab.io/${{ secrets.SIXFAB_REGISTRY_USERNAME }}/my-app:${{ github.ref_name }}
            cr.sixfab.io/${{ secrets.SIXFAB_REGISTRY_USERNAME }}/my-app:latest

      - name: Trigger restart on ALPON device
        env:
          SIXFAB_API_KEY: ${{ secrets.SIXFAB_API_KEY }}
          ASSET_ID: ${{ secrets.ASSET_ID }}
        run: |
          curl -X POST "https://api.sixfab.com/v1/assets/$ASSET_ID/applications/my-app/restart"             -H "Authorization: Bearer $SIXFAB_API_KEY"             -H "Content-Type: application/json"

GitLab CI equivalent

build_and_release:
  image: docker:24
  services: [docker:24-dind]
  variables:
    DOCKER_BUILDKIT: "1"
  only: [tags]
  before_script:
    - echo "$SIXFAB_REGISTRY_PASSWORD" | docker login cr.sixfab.io         -u "$SIXFAB_REGISTRY_USERNAME" --password-stdin
  script:
    - docker buildx create --use
    - docker buildx build --platform linux/arm64         -t cr.sixfab.io/$SIXFAB_REGISTRY_USERNAME/my-app:$CI_COMMIT_TAG         -t cr.sixfab.io/$SIXFAB_REGISTRY_USERNAME/my-app:latest         --push .
    - apk add --no-cache curl
    - curl -X POST "https://api.sixfab.com/v1/assets/$ASSET_ID/applications/my-app/restart"         -H "Authorization: Bearer $SIXFAB_API_KEY"         -H "Content-Type: application/json"

Two automation patterns

Pushing a new tag does not automatically redeploy a running container. You decide how the trigger fires.

Rollback

Rollback is only as easy as your tagging strategy permits. With immutable tags, you point the deployment at the previous tag and click save. With mutable tags, rollback is impossible unless you kept the previous image digest somewhere accessible.

Verify the rollout

The container status flipping back to Running is necessary but not sufficient. Run through the checks below before declaring the rollout complete.

Troubleshooting

Common failure modes when updating a container on ALPON, and how to recover from each.

exec /usr/local/bin/app: exec format error

# 1. Rebuild explicitly for ARM64
docker buildx build --load --platform linux/arm64   -t my-app:v1.2.3 .

# 2. Verify the architecture field reads "arm64"
docker manifest inspect cr.sixfab.io/<your_username>/my-app:v1.2.3

unauthorized: authentication required

docker login cr.sixfab.io --username <your_username>

COPY requirements.txt ./
RUN pip install -r requirements.txt

# Code goes last so it stays its own thin layer
COPY . .

Error: Bind for 0.0.0.0:30800 failed: port is already allocated

Your registry username appears at the top of the Registry page in ALPON Cloud.

Container Registry page on ALPON Cloud listing every pushed repository.

Image details page: repository, tag, digest, architecture, manifest layers.