Motrixlab/docs/source/en/user_guide/getting_started/container_deployment.md

Container Deployment

This document describes how to deploy MotrixLab using Docker containers to simplify environment configuration and enable rapid deployment.

Prerequisites

• Docker and Docker Compose: Installation Docs
• NVIDIA Container Toolkit (for GPU support): Installation Docs
• NVIDIA GPU: Graphics card supporting CUDA 12.8

Quick Start

1. Clone the Repository

git clone https://github.com/Motphys/MotrixLab.git

cd MotrixLab/docker

2. Start with Docker Compose

We provide a complete docker-compose.yml configuration file that supports one-click startup of training and TensorBoard visualization services.

# Start training and TensorBoard services
docker compose up -d

This will start the following services:

• motrixlab-training: Training container that executes reinforcement learning training tasks
• motrixlab-tensorboard: TensorBoard visualization service accessible via browser at http://localhost:6006

3. Configure Training Parameters

You can customize training configurations through environment variables:

# Set training backend (jax or torch)
export MOTRIX_TRAIN_BACKEND=jax

# Set number of parallel environments
export MOTRIX_NUM_ENVS=2048

# Set training environment name
export MOTRIX_ENV=cartpole

# Start services
docker compose up -d

Environment Variable	Default	Description
MOTRIX_TRAIN_BACKEND	jax	Training backend: jax or torch
MOTRIX_NUM_ENVS	2048	Number of parallel environments
MOTRIX_ENV	cartpole	Training environment name

4. Monitor Training Progress

Training logs are automatically saved to the Docker Volume motrixlab-data. You can view them through:

# View training container logs
docker logs -f motrixlab-training

# Access TensorBoard
# Open in browser: http://localhost:6006

5. Stop Services

# Stop all services
docker compose down

# Stop services and remove data volumes
docker compose down -v

Advanced Usage

Building Docker Images

If you need to customize the image, you can build from source:

# Execute from project root directory
cd docker
docker build -t motphys/motrixlab:latest .

Running Single Container

If you only want to run the training container without using Docker Compose:

docker run --gpus all \
    -v $(pwd)/runs:/root/motrixlab/runs \
    motphys/motrixlab:latest \
    scripts/train.py --train-backend jax --num-envs 2048 --env cartpole

Persisting Training Results

The default configuration uses the Docker Volume motrixlab-data to save training results. You can mount it to a host directory:

# Modify volumes configuration in docker-compose.yml
volumes:
  - ./runs:/root/motrixlab/runs

Image Details

Our Docker image is based on {bdg-primary-line}NVIDIA CUDA 12.8.1 runtime environment and comes pre-installed with the following components:

• UV Package Manager: Fast, reliable dependency management
• MotrixLab: Complete reinforcement learning training framework
• SKRL: Reinforcement learning library supporting both JAX and PyTorch backends
• TensorBoard: Training process visualization tool
• MotrixSim: High-performance physics simulation engine

Image layer build process:

1. Base Environment: NVIDIA CUDA 12.8.1 Runtime + Ubuntu 24.04
2. System Dependencies: Install UV package manager and necessary system tools
3. Python Dependencies: Use UV cache mechanism for fast Python package installation
4. Project Code: Copy MotrixLab source code and complete dependency installation

Troubleshooting

GPU Not Available

If the container cannot access the GPU:

# Check NVIDIA Docker Runtime
docker run --rm --gpus all nvidia/cuda:12.8.1-base-ubuntu24.04 nvidia-smi

# Verify NVIDIA Container Toolkit is correctly installed
which nvidia-container-cli

Insufficient Storage Space

Clean Docker cache and unused images:

# Clean build cache
docker builder prune

# Delete unused images
docker image prune -a

# Clean all unused resources
docker system prune -a

Performance Optimization

Accelerate Builds with UV Cache

The Dockerfile uses UV's cache mount feature, which can significantly speed up rebuilds:

# Rebuild using UV cache
docker build --cache-from motphys/motrixlab:latest -t motphys/motrixlab:latest .

GPU Resource Allocation

You can specify the number of GPUs to use in docker-compose.yml:

deploy:
    resources:
        reservations:
            devices:
                - driver: nvidia
                  device_ids: ["0", "1"] # Use GPU 0 and 1
                  capabilities: [gpu]

Next Steps

• Check out the Quick Start Tutorial to learn basic MotrixLab usage
• Read Training Examples for more training tasks
• Explore Basic Framework for in-depth understanding of the framework architecture