https://github.com/norlab-ulaval/dockerized-norlab-project

The user side companion of Dockerized-NorLab. It provide a containerized workflow tailor-made for robotic research.
https://github.com/norlab-ulaval/dockerized-norlab-project
containerization nvidia-docker research robotics
Last synced: about 1 month ago
JSON representation
The user side companion of Dockerized-NorLab. It provide a containerized workflow tailor-made for robotic research.
Host: GitHub
URL: https://github.com/norlab-ulaval/dockerized-norlab-project
Owner: norlab-ulaval
Created: 2025-05-20T22:02:47.000Z (about 1 year ago)
Default Branch: beta
Last Pushed: 2026-04-24T01:52:21.000Z (about 1 month ago)
Last Synced: 2026-04-24T02:27:09.574Z (about 1 month ago)
Topics: containerization, nvidia-docker, research, robotics
Language: Shell
Homepage:
Size: 4.19 MB
Stars: 2
Watchers: 5
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project

README

          


[//]: # ( ==== Logo ================================================== ) 









    

      

      

      

    









[//]: # ( ==== Title ================================================= ) 

# _Dockerized-NorLab project application (DNA)_

[//]: # ( ==== Hyperlink ============================================= ) 

^{NorLab TeamCity GUI

    (VPN/intranet access)   •  

    norlabulaval

    (Docker Hub)}







[//]: # ( ==== Description =========================================== ) 

**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)](https://github.com/norlab-ulaval/dockerized-norlab/tree/main) image builder
 which produces multi‑arch, GPU‑enabled, ROS2‑ready base images consumed by DNA.





[//]: # ( ==== Badges ================================================ ) 

[//]: # (Note on shield.io release badge: it works only for public repository)

[![semantic-release: conventional commits](https://img.shields.io/badge/semantic--release-conventional_commits-453032?logo=semantic-release)](https://github.com/semantic-release/semantic-release)





[//]: # (Dockerhub image badge)

[//]: # (TODO: Un-comment the next line if you have docker images on dockerhub)

[//]: # (TODO: Change "norlabulaval/libpointmatcher" in both url to "your-dockerhub-domain/your-image-name")

[//]: # (  )




[//]: # ( ==== Maintainer ============================================ ) 

_{Maintainer Luc Coupal}








[//]: # ( ==== Body ================================================== ) 

![dna_splash.png](visual/dna_splash.png)

## What it does

[//]: # ()

[//]: # (  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](https://github.com/ros2)) ready**: Ready to roll, out of the box.

- **GPU acceleration**: Provides GPU support through [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-container-toolkit) for both `l4t/arm64` and `linux/x86` platforms.

- **Transparent configuration**: Makes project configuration easy while keeping [Docker](https://docs.docker.com/) and [Docker Compose](https://docs.docker.com/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

[//]: # ()

[//]: # (  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

[//]: # ()

[//]: # (  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.

**📦 Apptainer / HPC Support**  

Deploy slurm jobs on HPC servers using Apptainer (e.g., Ulaval Valeria, Compute Canada). DNA builds a `linux/amd64` Docker tar archive locally (macOS compatible) and generates standalone Apptainer exec scripts — `apptainer` is never executed locally. Supports Valeria and Compute Canada profiles.

**◐ 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

[//]: # ()

[//]: # (  Getting started)

### Install `dna`, the Dockerized-NorLab project app 

```shell

# 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

```shell

# To DNA-initialize a project repository (must be git initialized)

cd 

dna init

```

Which add a few directories to your project repository

```markup

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

```shell

dna build develop

dna up

# When your done 

dna down

```

> **📖 For detailed configuration and command documentation**, see the [Documentation](#documentation) section below.

[//]: # ()

---

## Documentation

### 📚 Complete Documentation

- **[Command Reference](documentation/dna.md)** - Complete guide to all `dna` commands

  - [dna init](documentation/command/init.md) - Initialize a new DNA project

  - [dna build](documentation/command/build.md) - Build DNA Docker images

  - [dna up](documentation/command/up.md) - Start and attach to containers

  - [dna down](documentation/command/down.md) - Stop containers

  - [dna attach](documentation/command/attach.md) - Attach to running containers

  - [dna exec](documentation/command/exec.md) - Execute commands in containers

  - [dna run](documentation/command/run.md) - Run commands in containers

  - [dna project](documentation/command/project.md) - Super project commands

  - [dna save](documentation/command/save.md) - Save Docker images for offline use

  - [Apptainer / HPC Workflow](documentation/command/apptainer.md) - Deploy slurm jobs on Apptainer HPC servers

  - [dna load](documentation/command/load.md) - Load Docker images from files

  - [dna config](documentation/command/config.md) - Show configuration

  - [dna version](documentation/command/version.md) - Show DNA version

  - [dna update](documentation/command/update.md) - Update DNA to latest version

### ⚙️ Setup & Configuration

- **[Installation Guide](documentation/install.md)** - Detailed installation instructions for all supported platforms

- **[Project Initialization & Configuration](documentation/project_initialization_and_configuration.md)** - Complete guide to setting up and configuring DNA projects

- **[Compose Overrides & Orchestration](documentation/compose_overrides_and_orchestration.md)** - How DNA discovers and applies Docker Compose override files, with simple recipes

- **[Offline Installation Guide](documentation/offline_installation.md)** - Complete guide for installing DNA in environments without internet connectivity

- **[IDE Integration](documentation/ide_integration.md)** - 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:

```shell

# 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:

```shell

# 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|...]

```
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/norlab-ulaval/dockerized-norlab-project

Awesome Lists containing this project

README
