Setup

This page covers the BaseModel Python App delivered as a Docker container. Run Docker commands on the host machine; run Python commands in the container.

1. Pull the image

The Python App image is named monad. Log in to the container registry and pull the version provided by your BaseModel contact:

docker login -u USERNAME -p TOKEN_PASSWORD REGISTRY_URL
docker pull REGISTRY_URL/monad:VERSION

Replace USERNAME, TOKEN_PASSWORD, REGISTRY_URL, and VERSION with the values provided by your BaseModel contact.

Confirm the image is available:

docker images | grep monad

2. Run the container

Prepare writable output directories on the host, then start a detached container. Replace the host paths below with your own paths. The Ray temporary directory must exist and be writable by the container user (uid=1000).

Start the container

mkdir -p /your/workspace/{logs,model} /your/ray-tmp
chmod 0777 /your/workspace/logs /your/workspace/model /your/ray-tmp

docker run -dit \
  --gpus '"device=<GPU_INDEX>"' \
  --shm-size 64gb \
  -w /workspace \
  -e MONAD_LOGGING_DIRECTORY=/workspace/logs \
  -v /your/workspace:/workspace:z \
  -v /your/data:/data/datasets:ro,z \
  -v /your/ray-tmp:/data/tmp:rw,z \
  --name basemodel \
  REGISTRY_URL/monad:VERSION \
  tail -f /dev/null

tail -f /dev/null keeps this detached container running for subsequent docker exec commands.

• --gpus '"device=<GPU_INDEX>"' — exposes only the assigned GPU; replace <GPU_INDEX> with its host index. Use all only when every GPU is assigned to this run, and select the devices to train on in your configuration.
• --shm-size 64gb — shared memory for distributed processing and data loaders. Size it for your workload; insufficient shared memory can crash the node. 64gb is the reference setting used here.
• -w /workspace — makes the mounted workspace the working directory for docker exec commands.
• -e MONAD_LOGGING_DIRECTORY=/workspace/logs — keeps logs on the mounted workspace; optional when the image's default log location is already writable (see Logging).
• -v /your/workspace:/workspace:z — working directory for configs, onboarding package, and all model artefacts. Split into multiple mounts if needed.
• -v /your/data:/data/datasets:ro,z — optional local Parquet input, mounted read-only so training cannot alter source data.
• -v /your/ray-tmp:/data/tmp:rw,z — writable Ray overlay. Monad uses /data/tmp even when TMPDIR or RAY_TMPDIR points elsewhere.

The data mount is optional when all inputs come from a database. Keep the writable workspace and Ray mount in either case. The Python App may use /data/tmp/ray directly for temporary processing data, so setting TMPDIR alone does not replace this mount. Add your backend's environment settings when needed; see Connect Sources.

To open a shell in the running container:

docker exec -it basemodel bash

3. Verify the installation

Inside the container:

python -c "import monad"

If this results with no error, your environment is ready.

4. Run a configured training job

Create /your/workspace/configs/fm_config.yaml using Basic Configuration. For the running container above, execute the documented CLI directly; no separate pretrain.py is required:

docker exec -w /workspace basemodel python -m monad.run \
  --pretrain \
  --config-path /workspace/configs/fm_config.yaml \
  --output-path /workspace/project/model

Use a new output directory for a new run. See Key Flags before resuming or replacing existing results.

Alternatively, run the same job in a one-off container:

docker run --rm \
  --gpus all --shm-size 64gb \
  -w /workspace \
  -v /your/workspace:/workspace:z \
  -v /your/data:/data/datasets:ro,z \
  -v /your/ray-tmp:/data/tmp:rw,z \
  REGISTRY_URL/monad:VERSION \
  python -m monad.run --pretrain \
    --config-path /workspace/configs/fm_config.yaml \
    --output-path /workspace/project/model

Choose one execution method for a run; do not launch both commands against the same output directory.