Dockerized-NorLab project application (DNA)

^{NorLab TeamCity GUI (VPN/intranet access)   •   norlabulaval (Docker Hub)}  

A containerized workflow tailor-made for robotic research.

Dockerized-NorLab project application (DNA) manage Dockerized-NorLab (DN) container lifecycle
providing functionality for robotic software development, deployment, testing,
continuous integration, slurm job experimentation, and release publishing.

DNA is the user side companion of Dockerized-NorLab (DN) image builder
which produces multi‑arch, GPU‑enabled, ROS2‑ready base images consumed by DNA.

_{Maintainer Luc Coupal}

---

What it does

• Containerized robotic development environment: Provides a complete containerized workflow for robotic research, development, deployment, testing, continuous integration, running slurm jobs, and source code release.
• Multi-platform support: Runs seamlessly on l4t/arm64 (Jetson), darwin/arm64 (Mac OS X), and linux/x86 without configuration changes.
• Flexible deployment modes: Supports both local and remote workflows for personal workstations, remote embedded computers, and servers.
• Robotic Software System (ROS2) ready: Ready to roll, out of the box.
• GPU acceleration: Provides GPU support through NVIDIA Container Toolkit for both l4t/arm64 and linux/x86 platforms.
• Transparent configuration: Makes project configuration easy while keeping Docker and Docker Compose logic transparent and accessible.
• Rootless enough: The stack is designed to run containers as a non‑root user inside the container, but it does not target Docker’s full “rootless mode” (rootless daemon/user‑namespaces) since it need to support robotic related capabilities such as GPU, host networking/IPC/PID, that typically require a rootful Docker engine.

Why

Dockerized-NorLab (DN) and the Dockerized-NorLab project application (DNA) solve critical challenges in robotic research and development by providing a standardized, reproducible, and scalable containerized environment.

Key Benefits

🔄 Reproducibility
Ensure consistent environments across different machines, operating systems, and team members. Your code runs the same way everywhere, eliminating "it works on my machine" problems.

🔒 Isolation
Keep your development environment clean and isolated from your host system. Experiment freely without affecting your main system configuration.

👥 Project Collaboration
Streamline team collaboration with standardized development environments. New team members can get up and running in minutes, not hours or days.

🚀 Fast Deployment
Deploy your robotic applications quickly and reliably across different platforms - from development workstations to production servers and embedded systems.

✅ Code Quality
Maintain high code quality with integrated testing, continuous integration, and standardized development practices built into the containerized workflow.

Use Cases

DNA and DN support a wide range of robotic development and deployment scenarios:

Development, Deployment and Release Modes

🛠 Local and Remote Development (Develop Mode)
Set up consistent development environments on local workstations and remote machines. DNA is installed on both local and remote hosts, enabling seamless development workflows across different locations.

⏯️ Deployment (Deploy Mode)
Deploy your robotic applications to target hosts with DNA installed. Streamlined deployment process ensures your applications run consistently in production environments.

📦 Release Mode
Create and distribute source code release. Released containers can run independently without requiring DNA installation on the target system.

Specialized Workflows

🔄 Testing and Continuous Integration (CI)
Run automated CI tests in isolated, reproducible environments. Perfect for validating code changes and maintaining code quality across your robotic projects. DN/DNA is CI framework agnostic, it can run tests localy or on any CI server.

🧪 SLURM Job Experiment
Execute compute-intensive robotic algorithms and simulations on SLURM-managed clusters with consistent containerized environments.

◐ Multi-Platform Support
Work seamlessly across different operating systems and architectures:

• l4t/arm64 (NVIDIA Jetson platforms)
• darwin/arm64 (Mac OS X with Apple Silicon)
• linux/x86 (Standard Linux systems)

🎮 GPU Acceleration
Leverage GPU computing power for robotics applications through NVIDIA Container Toolkit integration, supporting both ARM64 and x86 platforms.

---

Getting started

Install dna, the Dockerized-NorLab project app

# Clone repository on host computer
git clone --recurse-submodule https://github.com/norlab-ulaval/dockerized-norlab-project.git
cd dockerized-norlab-project

# Install DNA on host (Check install option with $ bash install.bash --help) 
# Note: 
#   - Installation supports both online and offline scenarios
#   - Might require sudo if dockerized-norlab-project/ is owned by root
bash install.bash

# Check available commands
dna

Make a repository ready to use with DNA

# To DNA-initialize a project repository (must be git initialized)
cd <path/to/your/project/repository>
dna init

Which add a few directories to your project repository

your-project-repository/
  ├── .dockerized_norlab/             <- DNA configuration
  ├── artifact/                       ← Runtime produced data (mounted rw, vcs ignored)
  ├── data/
  │   ├── external_data/              ← Non-tracked data not required by src/tests code logic (mounted rw, vcs ignored)
  │   ├── repository_data/            ← Data that are required by the src/test code logic (mounted rw in develop, copied otherwise)
  │   └── shared_data/                ← Placeholder directory replaced by an optional local data volume (mounted ro, vcs ignored)
  ├── src/                            <- Your repository source code (mounted/copied)
  ├── tests/                          <- Your repository test code (mounted/copied)
  ...
  ├── .dockerignore                   <- Specify files/dir that won't be copied in container on build
  ├── .gitignore                      <- Specify files/dir to keep out of VCS
  └── README.md                       <- Created if it did not already exist

Note:

• Existing file and directories with the same name will be safeguarded with the suffix .old, not overriden.
• Content of the artifact directory is persistent. It will remain available even if the container is stopped or removed.

Create, run, and stop DN container

To spin a DN container and open a terminal in it, run the following command from anywhere in the DNA initialized repository

dna build develop
dna up

# When your done 
dna down

📖 For detailed configuration and command documentation, see the Documentation section below.

---

Documentation

📚 Complete Documentation

• Command Reference - Complete guide to all dna commands
  • dna init - Initialize a new DNA project
  • dna build - Build DNA Docker images
  • dna up - Start and attach to containers
  • dna down - Stop containers
  • dna attach - Attach to running containers
  • dna exec - Execute commands in containers
  • dna run - Run commands in containers
  • dna project - Super project commands
  • dna save - Save Docker images for offline use
  • dna load - Load Docker images from files
  • dna config - Show configuration
  • dna version - Show DNA version
  • dna update - Update DNA to latest version

⚙️ Setup & Configuration

• Installation Guide - Detailed installation instructions for all supported platforms
• Project Initialization & Configuration - Complete guide to setting up and configuring DNA projects
• Compose Overrides & Orchestration - How DNA discovers and applies Docker Compose override files, with simple recipes
• Offline Installation Guide - Complete guide for installing DNA in environments without internet connectivity
• IDE Integration - Setup instructions for development environments and IDEs

---

🧪 For Beta Testers and Developer

To try DNA in a throwaway project or for development on initialization related feature:

# Clone dockerized-norlab-project-mock-EMPTY
git clone https://github.com/norlab-ulaval/dockerized-norlab-project-mock-EMPTY.git
cd dockerized-norlab-project-mock-EMPTY
dna init

For general DNA development in a throwaway project:

# Clone dockerized-norlab-project-mock-EMPTY
git clone https://github.com/norlab-ulaval/dockerized-norlab-project-mock.git
cd dockerized-norlab-project-mock
dna [build|up|down|attach|run|...]