> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server. # Setup > Run Kumo from NVIDIA NGC with Docker Compose on one pre-provisioned Linux host. Use this guide when your Linux VM or bare-metal host is already provisioned and you have the Kumo Docker Compose bundle. The bundle runs the Kumo images from NVIDIA NGC, plus its bundled Postgres database and Temporal workflow service that schedules Kumo background work, on one host. The first path uses localhost and local storage on CPU. GPU-backed training and prediction are optional. ## Prerequisites Have the following before you start: * **Linux x86\_64 host:** Recommended sizing is 32 vCPU, 128 GB RAM, and durable storage for Docker, Postgres, and the Kumo dataplane, where Kumo stores ingested data and model artifacts. * **Dedicated fast local SSD:** Mount it at `/mnt/localssd` for DiskGraph working data. DiskGraph is Kumo's on-host graph-processing workspace. The SSD must not be the root filesystem. * **GPU host (optional):** An NVIDIA GPU with sufficient VRAM, a working host driver, and NVIDIA Container Toolkit configured for Docker. The primary path below uses CPU mode. * **Docker and host utilities:** Docker Engine, Docker Compose v2, `curl`, `openssl`, and `findmnt`. * **NGC access:** An API key entitled to `nvcr.io/1000161941370113/kumo-3`, plus network access to NGC and the upstream images referenced by Compose. * **Complete deployment bundle:** `kumo-compose`, all three Compose files, and both `config/` directories shown below. The supplied configuration disables application authentication and TLS. Keep the published HTTP port private, behind an SSH tunnel, or otherwise restricted to trusted clients. Verify the host: ```bash docker version docker compose version openssl version findmnt -n -o SOURCE,FSTYPE,TARGET -T /mnt/localssd test "$(findmnt -n -o SOURCE -T /mnt/localssd)" != "$(findmnt -n -o SOURCE -T /)" ``` ## Starting Kumo The deployment bundle includes the Compose wrapper, service definitions, and configuration for a single-host Kumo deployment. The steps below start the default CPU configuration with localhost access and local dataplane storage. Configure [external dataplane storage](#storage-and-dataplane), [Kumo authentication](#optional-kumo-authentication), or [a DNS name and TLS](#optional-tls-termination) before the first startup. Bootstrap preserves generated configuration, so changing these settings later does not migrate an existing deployment. The commands below assume this bundle layout. Run the Compose commands from `docker/compose/`. ```text ~/path-to-docker-compose/ ├── README.md ├── .env.template └── docker/compose/ ├── kumo-compose ├── docker-compose.singlehost.yml ├── docker-compose.singlehost.postgres.yml ├── docker-compose.singlehost.gpu.yml ├── config/ │ ├── postgres-initdb/ │ └── temporal/dynamicconfig/ └── .env (created in Step 1) ``` ### 1. Create the runtime directories and environment file ```bash cd ~/path-to-docker-compose/docker/compose mkdir -p data/{dataplane,glove,nginx,prometheus,secrets,tls} cp ../../.env.template .env chmod 600 .env sudo chown 999:999 /mnt/localssd sudo chmod 0750 /mnt/localssd ``` Before the first startup, edit `.env` and set a unique Postgres password: ```dotenv POSTGRES_PASSWORD=PASTE_A_UNIQUE_SECRET_HERE ``` Generate the password with `openssl rand -hex 32` if needed. Leave the local-storage defaults in place: ```dotenv PUBLIC_URL=http://localhost DISABLE_AUTH=true ENABLE_TLS=false DISKGRAPH_DATA_ROOT=/mnt/localssd LOCAL_DATAPLANE_HOST_MOUNT=./data/dataplane DATAPLANE_ROOT=/opt/app/data/dataplane ARTIFACT_ROOT=/opt/app/data/dataplane/artifacts KUMO_POSTGRES_MODE=bundled KUMO_BACKEND_VARIANT=cpu ``` ### 2. Authenticate to NGC and start the stack Use an API key that is entitled to the Kumo NGC organization. This command reads the key without displaying it: ```bash read -rsp 'NGC API key: ' NGC_API_KEY; echo printf '%s' "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin unset NGC_API_KEY ``` Validate the rendered configuration, pull the images, and start Kumo: ```bash ./kumo-compose config --quiet ./kumo-compose config --images | sort -u ./kumo-compose pull ./kumo-compose up -d ./kumo-compose ps --all ``` ### 3. Verify Kumo Cold startup can take several minutes. `kumo-bootstrap`, `temporal-schema`, and `temporal-namespace` should finish with exit status 0; the long-running services should become healthy. ```bash ./kumo-compose ps --all ./kumo-compose logs --no-color kumo-bootstrap temporal-schema temporal-namespace docker inspect --format '{{.State.Health.Status}}' kumo-rest kumo-rest-public curl --fail http://localhost/ -o /dev/null docker exec kumo-rest python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=10)" ``` Open `http://localhost` in a browser on the host, or reach it through a secure tunnel. With the default `DISABLE_AUTH=true`, Kumo does not display a sign-in prompt. ## Deployment-type variations Use these optional settings in place of the defaults from Step 1, before the first startup. ### Optional Kumo authentication Before the first startup: 1. Set `DISABLE_AUTH=false` in `.env`. 2. Uncomment `DIRECT_CONNECT_LOGIN_METHOD`, `ADMIN_EMAILS`, and `DIRECT_CONNECT_ADMIN_TEMP_PASSWORD`, then provide the administrator email and a unique temporary password. After startup, sign in as that administrator, change the temporary password, and create a real API key for SDK access. A random placeholder API key is not accepted when authentication is enabled. ### Optional TLS termination To terminate TLS in the bundled nginx service, set these values in `.env` before the first startup: ```dotenv ENABLE_TLS=true PUBLIC_URL=https://kumo.customer.example NGINX_PORT=443 ``` Install a trusted full-chain certificate and its matching unencrypted private key before starting Kumo: ```bash sudo install -o 999 -g 999 -m 0644 /path/to/fullchain.pem data/tls/server.crt sudo install -o 999 -g 999 -m 0600 /path/to/private-key.pem data/tls/server.key ``` The default `KUMO_TLS_DIR=./data/tls` mounts these files read-only at `/etc/kumo/tls` for bootstrap and nginx. Bootstrap generates the HTTP or TLS nginx configuration only on its first run. If a customer-managed proxy terminates TLS, leave `ENABLE_TLS=false` and allow the published HTTP port to be reached only from that proxy. ### Optional GPU-backed training and prediction To use a GPU, add an NVIDIA GPU with sufficient VRAM, a working host driver, and NVIDIA Container Toolkit configured for Docker. Verify the GPU and Docker runtime before setting the GPU backend variant: ```bash nvidia-smi docker info --format '{{json .Runtimes}}' | grep -q '"nvidia"' ``` Then set this value in `.env` before starting the stack: ```dotenv KUMO_BACKEND_VARIANT=gpu ``` `kumo-compose` adds the GPU overlay when this value is `gpu`. The overlay uses the NGC `kumo-backend-gpu` image for the pool worker and reserves all available NVIDIA GPUs. The included Compose file sets `POOL_GPU_CONCURRENCY: "1"`; on a multi-GPU host, change that Compose value to the number of physical GPUs you want to use concurrently. It fails early if the GPU or Docker runtime checks do not pass. ### Storage and dataplane | Deployment type | Dataplane setup | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AWS | For S3, set `DATAPLANE_ROOT=s3://YOUR_BUCKET/YOUR_PREFIX/dataplane`, `ARTIFACT_ROOT=s3://YOUR_BUCKET/YOUR_PREFIX/artifacts`, and `AWS_REGION` before the first start. Use an IMDSv2 instance profile with prefix-scoped access. Keep `/mnt/localssd` for DiskGraph. | | Azure | Provision ADLS Gen2 filesystems and set roots such as `abfss://dataplane@.dfs.core.windows.net/kumo/dataplane` and `abfss://artifacts@.dfs.core.windows.net/kumo`. Give the VM's managed identity contributor access to the dataplane and reader access to artifacts. | | On-premises or bare metal | Create `data/dataplane` for the local dataplane and mount a dedicated `/mnt/localssd` for DiskGraph. The bootstrap service sets the dataplane ownership. | | Brev | The deployment runner creates `/opt/dlami/nvme/kumo-data/dataplane` and uses `/opt/dlami/nvme/kumo-data/diskgraph` for `/mnt/localssd`. This local dataplane is erased when the Brev instance stops. | For the AWS S3 path, do not combine the S3 roots with the local roots unless you deliberately migrate the generated deployment configuration. The supplied Compose files do not inject `AWS_REGION` into application containers, so validate image and bundle support for the chosen region before using this optional path. ## Stop Kumo Stop the stack without deleting its data: ```bash ./kumo-compose down --remove-orphans ``` Do not run `down -v` unless deleting the Docker-managed Postgres and observability volumes is intentional. It does not remove the host-mounted `docker/compose/data/` directory or `/mnt/localssd`. ## Next steps #### [GPU Sizing](/get-started/docker/gpu-sizing) Choose GPU resources for a Docker Compose deployment. #### [User Guide: Kumo Studio](/data-connectors) Connect data and use the platform workflow. #### [Admin Setup Guide](/admin-setup-guide) For admins only: set up Groups and create and manage identities.