--- updatedAt: 2026-10-07T18:54:37.000Z agentTools: projectIndex: https://docs.sixfab.com/llms.txt --- # Containerize Apps for ALPON with Dockerfile Templates Learn how to containerize applications on the ALPON Edge Computers using Docker and optimized Dockerfile templates. Build lightweight ARM64 containers for edge computing and IoT deployments. {`

Containerize Apps for ALPON with Dockerfile Templates

Package your application as an ARM64 Docker image that runs on both ALPON X5 AI and ALPON X4. This guide walks through preparing your project, writing the Dockerfile, and using two ready-made templates (Debian for development, Alpine for production) so the resulting image can be deployed through ALPON Cloud.

ALPON X5 AI ALPON X4 Docker · ARM64 Dockerfile Templates
ALPON · Tutorial · App Containerization
How do I containerize an application for ALPON?

Place your source, dependencies, and a .dockerignore in one project folder, then write a Dockerfile that picks an ARM64 base image, sets a working directory, copies your code, installs dependencies, and declares the startup command. Build for ARM64 with docker buildx build --platform linux/arm64, then push the image to the Sixfab Container Registry at cr.sixfab.io. From there, deploy it to any ALPON X5 AI or ALPON X4 through ALPON Cloud.

Build for ARM64, not x86

Both ALPON X5 AI (Raspberry Pi CM5 with Cortex-A76) and ALPON X4 (Raspberry Pi CM4 with Cortex-A72) run on ARM64. Every image you deploy must include a linux/arm64 variant. Most official images on Docker Hub (nginx, redis, postgres, node, python) already ship multi-arch manifests. Custom images built on an x86 workstation must use docker buildx build --platform linux/arm64. A plain docker build on a Mac or PC produces an x86 image that fails to start on ALPON with exec format error.

Why ALPON for containerization

Every ALPON device ships with a Docker runtime preinstalled and authenticated against the Sixfab Container Registry out of the box. There is no SSH setup, no per-device credential rotation, no manual docker pull. The two devices in the line share the same ARM64 build target, so a single image works on both.

ALPON X5 AI Raspberry Pi CM5, Cortex-A76, 4-core ARM64, 8 GB RAM. Adds the DEEPX DX-M1 NPU for AI workloads.
ALPON X4 Raspberry Pi CM4, Cortex-A72, 4-core ARM64, 8 GB RAM. General-purpose IoT and edge compute.
Docker preinstalled Runtime ready on first boot. No apt install docker, no daemon config.
One image, two devices A single linux/arm64 image runs on both ALPON X5 AI and ALPON X4 without changes.

Traditional vs. containerized application management

In a traditional setup each application sits on its own OS or virtual machine, brings its own dependencies, and is updated through manual scp and systemctl rituals. Scaling means provisioning more hosts. Debugging means dialling into individual devices. On a fleet of edge devices that pattern collapses fast.

Containers flip the model. The application and every dependency it needs are baked into one immutable image. The same image runs identically on every device, deployments take seconds, and rollbacks are a tag change rather than a hot-fix shell session. For ALPON fleets, that is the only model we recommend.

Traditional setup
Dependencies Installed per device, drift over time
Deployment Manual file transfer, custom restart scripts
Rollback Reinstall older binaries, debug breakage live
Isolation Shared user-space, dependency conflicts
Fleet update SSH loop across devices
Containerized on ALPON
Dependencies Frozen in the image, identical on every device
Deployment Configured from ALPON Cloud; start time depends on image size and network conditions
Rollback Redeploy a previously tested immutable image tag
Isolation Each container runs in its own namespace
Fleet update Push a new tag, deploy from Connect

Prepare the project for containerization

Before writing the Dockerfile, get the project folder in shape. The image build process copies whatever is in this directory into the container, so anything that belongs out should be excluded explicitly.

  1. 1

    List every dependency

    Every library, runtime, and system tool the app needs must be declared somewhere the build can read. Use the convention for your language:

    • Python: requirements.txt (or pyproject.toml for Poetry or uv).
    • Node.js: package.json with package-lock.json.
    • Go: go.mod with go.sum.
    • System packages: list them in the Dockerfile RUN apt-get install (Debian) or RUN apk add (Alpine) line.

    A reference Python project layout:

    project layout tree 
    my_app/
├── app.py                 # Main application entrypoint
├── requirements.txt       # Python dependencies
├── Dockerfile
└── .dockerignore          # Files excluded from the image
  2. 2

    Add a .dockerignore file

    Without a .dockerignore, every log file, secret, and IDE folder gets copied into the image. That bloats the size, slows pulls over cellular, and can leak credentials. Treat it like a .gitignore for the build context:

    .dockerignore ignore 
    # Logs and runtime artefacts
*.log
*.pyc
__pycache__/

# Tests and dev tooling
tests/
.vscode/
.idea/

# Secrets and local config
.env
.env.*

# Version control
.git/
.gitignore
  3. 3

    Identify the runtime surface

    Decide upfront what the container needs from the host. These three answers shape the deployment form in ALPON Cloud later:

    • Environment variables: anything that changes between dev and prod (database URLs, API keys, feature flags). Never hard-code these in the source.
    • Ports: which TCP/UDP port the app listens on inside the container. Choose an available host port in the deployment form. The container-side port is defined by the application.
    • Bind mounts: host paths the container needs to read or write (persistent data, device files, or configuration). The source path must already exist on the device; the deployment form does not create named Docker volumes.

Write the Dockerfile

The Dockerfile is the recipe for the image. Each instruction creates a new image layer; ordered correctly, it lets Docker cache the slow steps and rebuild only what changed. The five instructions below cover the vast majority of edge applications.

Core Dockerfile instructions
FROM Picks the base image. Always pin a tag (e.g. python:3.11-slim), never use latest in production.
WORKDIR Sets the working directory inside the container. Subsequent instructions run here.
COPY Copies files from the build context into the image. Copy requirements.txt before the rest of the source to maximise cache reuse.
RUN Executes a shell command at build time. Use it to install system packages and language dependencies.
CMD Defines the command that runs when the container starts. Always exec-form: CMD ["python", "app.py"].

A minimal Python Dockerfile, walked through

Pick the base image. The -slim variants are far smaller than the default and still include enough to install most pure-Python packages:

Dockerfile dockerfile 
# Pinned, slim, ARM64-compatible Python runtime
FROM python:3.11-slim

Set the working directory. Every COPY and RUN that follows resolves relative to it:

Dockerfile dockerfile 
WORKDIR /app

Copy requirements.txt first, install, then copy the rest of the source. This ordering means Docker only rebuilds the dependency layer when requirements.txt changes, so code-only edits skip the slow pip install step entirely:

Dockerfile dockerfile 
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

Declare the startup command. Use exec-form (the JSON array, not the shell string) so signals like SIGTERM reach the app cleanly when the container stops:

Dockerfile dockerfile 
CMD ["python", "app.py"]

The complete Dockerfile

Combine the pieces above:

Dockerfile dockerfile 
# Pinned, slim, ARM64-compatible Python runtime
FROM python:3.11-slim

# Working directory for the rest of the build
WORKDIR /app

# Install dependencies first for better cache reuse
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy the rest of the source
COPY . .

# Start the application
CMD ["python", "app.py"]

Build it for ARM64

From the project root on your workstation:

terminal bash 
# 1. Enable buildx (one-time, if not already)
docker buildx create --use

# 2. Build the ARM64 image and load it locally
docker buildx build --load --platform linux/arm64 -t my-app:latest .

Dockerfile templates

Two ready-made templates cover the two phases of work. Use the Debian template while iterating; switch to the Alpine template before shipping to a fleet.

Development · Debian For iteration

Built on debian:bookworm-slim. Includes the build toolchain and git so you can compile native modules, debug from inside the container, and tweak dependencies without rebuilding the base.

  • Includes build-essential and git
  • Familiar apt ecosystem
  • Larger image (150 to 300 MB), fine for dev
Production · Alpine For deployment

Built on a versioned Alpine base. Stripped down to the minimum runtime, with no build tools or utilities the application does not need. Smaller images reduce cellular transfer and patching surface.

  • Uses the apk package manager
  • Image size depends on the application and runtime dependencies
  • Fewer packages to transfer and maintain

Development Dockerfile (Debian-based)

Drop this in the project root during active development:

Dockerfile.dev dockerfile 
# Development Dockerfile, Debian-based
FROM debian:bookworm-slim

WORKDIR /app

# Build toolchain and dev utilities
RUN apt-get update && apt-get install -y \
    build-essential \
    git \
    && rm -rf /var/lib/apt/lists/*

COPY . .

# Mark the runtime environment
ENV APP_ENV=development

# Replace with your dev entrypoint
CMD ["./your-dev-app"]

Production Dockerfile (Alpine-based)

Switch to this template once the app is stable. It optimises for image size, pull time, and the smaller attack surface that matters on a fleet of edge devices:

Dockerfile dockerfile 
# Production Dockerfile, Alpine-based
FROM alpine:3.21

WORKDIR /app

# Runtime-only dependencies, no build tools
RUN apk add --no-cache \
    libc6-compat \
    && rm -rf /var/cache/apk/*

COPY . .

# Mark the runtime environment
ENV APP_ENV=production

# Replace with your prod entrypoint
CMD ["./your-prod-app"]
Alpine and Debian use different package managers

Alpine uses apk; Debian uses apt. Package names also differ. Debian's libssl-dev is Alpine's openssl-dev; Debian's libpq-dev is Alpine's postgresql-dev. When porting from the dev template to prod, look up each apt package on pkgs.alpinelinux.org and replace it with the Alpine equivalent. Native C extensions built against glibc may also need libc6-compat on Alpine (musl).

Best practices for ALPON containers

The same image runs on both ALPON X5 AI and ALPON X4, but small choices in the Dockerfile decide whether it pulls in 10 seconds or 10 minutes over a cellular link, and whether it survives the next dependency update.

01 · Image size

Pick small base images

Prefer -slim, -alpine, or distroless variants when they satisfy the application's runtime requirements. Measure the final manifest size; transfer time depends on image size and the deployment network.

FROM python:3.12-slim FROM python:3.12
02 · Stability

Pin every version

Avoid floating latest tags. Use a reviewed version tag and pin the digest where byte-for-byte reproducibility is required; update it deliberately after testing.

FROM nginx:1.27-alpine@sha256:<digest> FROM nginx:latest
03 · Build context

Always include a .dockerignore

Strip out .git, logs, secrets, IDE folders, and test artefacts. A clean build context is faster to send to the daemon and produces smaller, safer images.

04 · Layer cache

Order layers for cache reuse

Copy dependency manifests (requirements.txt, package.json) and install them before copying the rest of the source. Edits to app.py won't invalidate the dependency layer.

COPY requirements.txt . RUN pip install -r requirements.txt COPY . .
05 · Layer count

Combine RUN commands

Each RUN creates a layer. Chain related commands with && and clean up in the same line so removed files don't survive in the previous layer.

RUN apt-get update && \ apt-get install -y curl && \ rm -rf /var/lib/apt/lists/*
06 · Configuration

Use ENV for configuration, not source code

Database URLs, API keys, log levels. Set them as environment variables on the deploy form. Hard-coded values mean a code change for every environment.

07 · Architecture

Build with buildx for ARM64

A plain docker build on an x86 Mac or PC produces an x86 image that fails to start on ALPON. Always include --platform linux/arm64.

docker buildx build --platform linux/arm64 . docker build .
08 · Signal handling

Use exec-form CMD

Exec form passes signals (SIGTERM on stop) directly to your process, so the container shuts down cleanly instead of being killed nine seconds later.

CMD ["python", "app.py"] CMD python app.py

A polished, production-ready example

Applying the practices above to a real Dockerfile:

Dockerfile dockerfile 
# Pinned, slim, ARM64 base
FROM python:3.11-slim

WORKDIR /app

# System packages and Python deps in one layer, with cleanup
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

# Dependencies first, cached unless requirements.txt changes
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Then the source
COPY . .

# Runtime configuration via ENV (override on the deploy form)
ENV APP_ENV=production \
    LOG_LEVEL=info

# Exec-form CMD for clean signal handling
CMD ["python", "app.py"]

Next steps: push and deploy

The image is built and tested locally. Two things remain: push it to the Sixfab Container Registry, then deploy it from ALPON Cloud. Both are covered end-to-end in the Deploy Applications guide, including the exact docker login, docker tag, and docker push sequence plus the deploy form fields for ports, environment variables, bind mounts, and network mode.

Continue with Deploy Applications on ALPON Push the image to cr.sixfab.io and deploy it remotely from ALPON Cloud, with coverage of ports, environment variables, bind mounts, and network modes. docker push ALPON Cloud Dashboard deployment
`}
> **Production image policy:** Replace floating `:latest` references with a reviewed immutable tag or digest, then record the selected version for rollback. {`
Continue exploring

Related guides

Build on this workflow with deployment, fleet-management, and hardware guidance for the ALPON platform.

Workflow Deploy Applications on ALPON Push an ARM64 image, configure its runtime, and launch it from ALPON Cloud. Open guide Platform ALPON Cloud Manage devices, applications, connectivity, and remote operations from one workspace. Open guide Hardware Compare ALPON devices Compare ALPON X4 and ALPON X5 AI capabilities for your edge workload. Open guide
`}