Understanding the Dockerfiles in the Torizon VS Code Templates

Hello everyone! 

Following the article about Torizon VSCode Extension by my colleague Gabriel, I wanted to add a bit more explanation about how to effectively use it.

If you're getting started with the Torizon IDE Extension and wondering why your project has three Dockerfiles and a docker-compose file, this quick guide is for you. I'll use the cLvgl template as an example, but the same pattern applies to most C/C++ Torizon templates.

Overview

Every Torizon IDE C/C++ template includes these container-related files:

Let's walk through each one.

Dockerfile: Production Image

This is a multi-stage Dockerfile that both compiles and packages your app for production.

Stage 1 — build: Uses torizon/cross-toolchain-${IMAGE_ARCH} as a base. It installs cmake, copies your source code, and cross-compiles the application for your target architecture (arm64, armhf, etc.) in Release mode.

Stage 2 — deploy: Starts from a minimal torizon/debian image for the target platform. It copies only the compiled binary from the build stage (build-${IMAGE_ARCH}/bin) into the container. The final image is clean — no compiler, no build tools, just your app.

The entrypoint is simply:

CMD ["./main"]

This is the image you'll push to a registry and deploy to your devices in the field.

Dockerfile.debug: Development/Debug Image

This Dockerfile builds a container specifically for remote debugging during development. Unlike the production Dockerfile, it does not compile your code. Instead it:

1. Starts from the same torizon/debian base image for the target platform.
2. Installs debug tooling: openssh-server, gdb, rsync, curl, and file.
3. Configures an SSH server on a custom port (DEBUG_SSH_PORT) so VS Code can connect via Pipe Transport and attach the debugger.

The SSH setup is intentionally insecure (empty password, root login permitted) — this is fine for a development container, but obviously not something you'd ship.

Notice that there's no COPY of source or build artifacts in this file. During the debug workflow, the IDE Extension's tasks handle copying the compiled output (built by the SDK container) into this container at deploy time. The container's only job at runtime is to run the SSH daemon:

CMD [ "/usr/sbin/sshd", "-D" ]

VS Code then connects over SSH, uploads the binary, and attaches GDB.

Dockerfile.sdk: Cross-Compilation Toolchain

This Dockerfile creates the SDK container — the environment where your code gets cross-compiled during development.

It's based on torizon/cross-toolchain-${IMAGE_ARCH} and installs cmake plus any additional build dependencies you need. The key thing is how it's used: the Torizon IDE Extension runs this container on your host machine with your project workspace bind-mounted into it:

-v ${workspaceFolder}:${APP_ROOT}

This means:

• The SDK container has access to your source code.
• Build outputs land directly in your workspace (e.g., build-arm64/).
• Incremental builds work — artifacts persist between sessions.
• The container runs as user torizon (not root).

You only need this file for compiled languages. Templates for interpreted languages (Python, Node.js, etc.) won't have a Dockerfile.sdk.

docker-compose.yml: Making it run!

The compose file defines two services, separated by profiles:

__container__-debug (profile: debug)

This service uses Dockerfile.debug. It:

• Forwards the DEBUG_SSH_PORT so VS Code can connect.
• Grants access to device nodes (/dev) via a bind mount and cgroup rules for tty, input devices, DRI (GPU), and framebuffer — essential for an LVGL app that needs to render to a display.
• Is only started when the debug profile is active.

__container__ (profile: release)

This service uses the production Dockerfile. It has the same device access and volume configuration as the debug service, but no SSH port forwarding. The image tag uses ${DOCKER_LOGIN} instead of ${LOCAL_REGISTRY}, meaning it's intended to be pushed to a remote registry.

The __container__ placeholder gets replaced with your actual project name when you create a project from the template.

How the profiles work

The Torizon IDE Extension activates the appropriate profile automatically:

• During development/debugging → docker compose --profile debug up
• For production/release testing → docker compose --profile release up

This means both services are defined in the same file but never run simultaneously.

Wrap up: How They Work Together

Here's how the three Dockerfiles fit into the development workflow:

1. You write code on your host machine.
2. Dockerfile.sdk → The IDE Extension builds the SDK container and runs cmake inside it (with your workspace bind-mounted) to cross-compile your code.
3. Dockerfile.debug → The IDE Extension builds the debug container, deploys it to the target device, copies the compiled binary into it, and VS Code attaches GDB over SSH.
4. Dockerfile → When you're ready to release, this multi-stage Dockerfile compiles and packages everything into a minimal production image.

Adding Custom Dependencies

You'll notice special labels like __torizon_packages_build_start__ and __torizon_packages_prod_start__ in the Dockerfiles. The IDE Extension uses these markers to automatically inject packages you configure via torizonPackages.json. You can also add packages manually between those labels.

Conclusion

Hopefully this clears up the role of each file in those templates! The Torizon IDE Extension handles most of the orchestration for you, but understanding what each Dockerfile does helps a lot when you need to customize your build or debug a deployment issue!