Loading the documentation…

Install in depth

This page covers the install in full, for IT teams and anyone who wants to know what each step does. To just install, follow the short Install DataMind OS instead.

With this server's DataMind License Key, one command checks the server, installs Docker when it is missing and starts the DataMind Installer. You then run the first installation from the Installer's screens. If DataMind issued you an Azure client secret instead, take the Azure path.

Important

Check System requirements first: this guide assumes a Linux host, and the page lists the operating system, hardware, network access and ports your server needs.

Before you start

You do not have to install Docker first. With a License Key, the install uses the Docker Engine it finds on the server, or installs Docker Engine and its Compose plugin when they are missing. Only the Azure path and the by-hand steps need Docker installed beforehand.

Install Docker yourself

Skip this section on the License Key path, unless you prefer to install Docker yourself. The Azure path and the by-hand steps need Docker Engine with the Compose v2 plugin on the host: install it by following the official instructions for your Linux distribution: Docker Engine installation.

To run the docker commands of those steps without sudo, add your user to the docker group:

bash
sudo usermod -aG docker $USER
newgrp docker

Membership of the docker group gives the same control of the server as root. The License Key path does not need it and adds nobody to the group.

Install the DataMind Installer

Install it with this server's License Key, or take the Azure path if DataMind issued you a client_id and client_secret instead.

With a DataMind License Key

  1. Download the install script and run it:

    bash
    curl -fsSL https://platform.datamind.ai/install.sh -o install.sh && sh install.sh
  2. Paste this server's License Key when the script asks DataMind License Key:. The key is not shown as you type.

  3. When sudo asks for your password, enter it. The script prints Downloading DataMind setup from platform.datamind.ai ..., checks the download and runs DataMind setup as root. Run as root, nothing is asked.

  4. Read the checks. DataMind setup first checks the server and changes nothing while it does. Each line reads [ PASS ], [ INFO ], [ WARN ] or [ FAIL ], and the Summary repeats the warnings, because they scroll past. It then asks Preflight passed. Install the DataMind Installer now?, or, when the checks warned about anything, Preflight passed with <n> warning(s), listed above. Install the DataMind Installer now?. Choose Install to go on, or Stop to leave the server as it is.

  5. Confirm Docker's address ranges. Under Docker needs address ranges of its own it shows the ranges it picked and asks Use these ranges?. Choose Accept, or Change to enter the ranges your network team gave you. Docker's address ranges explains the choice. Ranges already set in Docker's configuration are kept, and this question is skipped. A Docker that already runs containers is asked about first; see A Docker that is already in use.

DataMind setup then installs Docker if it is missing, creates the shared Docker network, signs in to platform.datamind.ai with the key, pulls the DataMind Installer, writes its Compose file and an .env holding the key in the install directory, by default one under /opt, and starts it. It waits until the Installer reports healthy. Every image, file and update then comes from platform.datamind.ai. What the install changes on the server lists every change.

Check it worked. DataMind setup ends with The DataMind Installer is running. and the address to open: the server's public address, such as http://20.71.4.9:8000, marked public address, as the DataMind Platform sees it, followed by the addresses the server knows itself by. The public address is the one the server's requests reach DataMind Platform from. When the server goes out through a proxy or reaches the platform over a private network, setup cannot tell it, and the line reads http://<this server>:8000 instead. The page is plain HTTP. Across a network you do not control, open it through an SSH tunnel instead:

bash
ssh -L 8000:127.0.0.1:8000 <you>@<this server>

Then browse to http://localhost:8000. If the Installer answers on the server but the page does not load from your machine, inbound TCP 8000 is blocked in front of the server. Allow it from your own address only: the Installer configures the whole platform and should never face the open internet.

For an unattended run, run the command as root with PLATFORM_API_KEY set to the License Key. Without a terminal and without the variable, the script stops with install.sh: no terminal to ask for the License Key - set PLATFORM_API_KEY. Without a terminal DataMind setup asks nothing: it uses the address ranges it detected, and it leaves a Docker that already runs containers as it is. To install somewhere other than the default, set INSTALL_DIR.

With an Azure client secret

If DataMind issued you a client_id and client_secret instead of an API key, install from Azure:

  1. Create the install directory and download the Docker Compose file from the address in your licence details:

    bash
    sudo mkdir -p <install directory> && cd <install directory>
    sudo curl -fsSL <compose file address> -o docker-compose.yml
  2. Log in to the registry, create the shared network, pull the images and start the stack:

    bash
    docker login -u <client_id> <registry>
    docker network create <network>
    docker compose pull
    docker compose up -d

    The registry host is in your licence details, and the network name is the one the Compose file expects.

  3. When docker login prompts for the password, enter your client_secret.

Check it worked. The DataMind Installer answers on http://<server>:8000 once the containers start.

By hand, instead of the script

The published script is the recommended route. If you cannot run it, these are its steps:

  1. Sign in to the DataMind Platform gateway with your key:

    bash
    docker login -u apikey platform.datamind.ai

    Paste this server's License Key as the password when prompted.

  2. Render the Compose file with the Installer image's print-compose helper. Every image in it points at the gateway, so the host needs no Azure access:

    bash
    sudo mkdir -p <install directory> && cd <install directory>
    docker run --rm -e PLATFORM_REGISTRY_HOST=platform.datamind.ai \
      <installer image> print-compose > docker-compose.yml

    The host value must be a bare host[:port]. Anything else stops with print-compose: PLATFORM_REGISTRY_HOST must be a bare host[:port], got '<value>'.

  3. Copy .env.example to .env, and set PLATFORM_API_KEY to the License Key and PLATFORM_REGISTRY_HOST to platform.datamind.ai. The key seeds the Installer on its first start only; see Configuration for how it is managed afterwards.

  4. Create the shared network and start the stack:

    bash
    docker network create <network>
    docker compose pull
    docker compose up -d

    The network name is the one the Compose file expects.

Check it worked. The DataMind Installer answers on http://<server>:8000.

Complete the first-run setup

  1. Open http://<server>:8000. On a brand-new install the first visit shows the account form: create the first administrator (Create admin account). Use a password that meets the Installer's rule: at least 8 characters with an uppercase letter, a lowercase letter, a number and a special character (Users keeps the full rule). The form appears only while no account exists; once an administrator exists, this screen is a sign-in form instead, and a registration attempt answers An admin account already exists. Please sign in instead. A DataMind Platform Administrator of your company can click Continue with DataMind Platform above the form instead: it creates the first administrator from their DataMind Platform account. (Sign in, sessions and account covers signing in and sessions.)

  2. Sign in. On a fresh host the Status screen shows the setup view; click Start. This does not start anything yet; it opens the setup chooser Set up DataMind OS, which asks Is this a fresh install, or are you migrating an existing Jenkins-managed setup?. Status offers Start until DataMind OS has containers on this host, or this Installer has installed or started it before. Images already on the host do not count, so a host where the install script has just set up the Installer shows Start.

  3. Choose First-time install (A brand-new DataMind OS on this machine.).

  4. Configure Platform opens and asks How will people reach DataMind OS?. When the install script saved this server's License Key, the step shows only the two cards. When no key is stored, it adds This server's DataMind License Key is needed too. and shows two fields above the cards: paste this server's key in DataMind License Key (Paste this server's License Key (dm-lic-…)), or, if you installed with Azure credentials, your secret in Azure client secret (Only without a License Key).

  5. Click a card. There is no Next button: the card opens its next page.

    • HTTPS, marked Recommended (Encrypted. Needs a domain name and its certificate.), when people open DataMind OS at a domain name and you have its certificate and private key.
    • HTTP (Not encrypted. People open DataMind OS at the server's address, usually its IP.) otherwise. If you chose HTTPS and have no domain or certificate yet, Back returns to this choice.

    The cards turn on once the Installer has checked whether a key is stored. Without a stored key, a key or a secret, a card stays on this page and answers This server's DataMind License Key is required.

  6. Give the address:

    • HTTPS: enter the Domain, then upload the Certificate file, with the chain and the Private key file, or click Use file paths on the server instead and enter their paths on the server. Click Next, and the Installer checks the domain and the certificate. When no check failed, click Finish; warnings do not block it. The upload, the paths and every check are on TLS and certificates.
    • HTTP: check the Server address, filled in from the address you opened the Installer with, such as http://10.0.0.5. Click Finish.
  7. Finish stores the key or the secret you entered, after checking a key with the platform, downloads the install files if they are not on the host yet, and saves the address, with the certificate for HTTPS. The modal then shows the saved address, and the Advanced configuration screen opens by itself. Change how DataMind OS is reached, under the address, starts the choice again. If you come back before starting the install, the button reads Review configuration and opens the settings again.

Start the installation

  1. On Advanced configuration, every value falls back to its default when left empty, so change only what you need now. PLATFORM_URL, and for HTTPS SSL_CERT_PATH and SSL_KEY_PATH, already hold what Configure Platform saved.

  2. Click Start Installation. The confirm dialog reads Installation deploys DataMind OS with the current configuration; you can still change values and restart afterward. Confirm with Start Installation, or go back with Go back. Any changes you made are saved as the installation starts.

  3. Watch the installation:

    • An overlay reads Initializing DataMind OS and Downloading catalog…, then Preparing deployment job….
    • The Services tree fills in as images download and services come up. Each service moves through Queued and a download percentage (0-99%, then 100%) to a final state: Created, Running, Waiting, Stopped, Completed, Error or Local copy.
    • While the last images finish, the percentage holds at 99% and a chip reads Finalizing pull — waiting on <services>.
    • If it fails, a toast reads Installation failed; open job logs from the toast. The Service status screen holds the full Job Logs panel.
  4. When the last service finishes, the hub switches to the running view: the deployment is up.

After the installation

DataMind OS now runs at the Platform URL you entered; the address pill at the top of the Installer opens it too. Sign in to DataMind OS for the first time with the administrator created during setup, or create the first administrator if the server has none: First sign-in to DataMind OS.

What the install command checks

DataMind setup, the program the install command downloads and runs, checks the server before it changes anything. The checks only read: the processor and the tools it needs, CPU, memory and free disk, Docker's configuration, the clock, the networks the server knows about and the address ranges Docker would get, a Docker that already runs containers, an existing DataMind Installer, the proxy, the connection to platform.datamind.ai and the License Key, the ports DataMind needs, and on-access virus scanning. A [ FAIL ] line stops the install, because DataMind cannot run there or the install would harm the server. Every other finding is a [ WARN ] with its reason.

Have the checks reviewed before anything changes

To show the result to your IT team first, run the install command and choose Stop at Preflight passed. Install the DataMind Installer now?. The run ends with Stopped before making changes. Nothing was changed., and the full report is in /var/log/datamind-setup.log.

After its first run, DataMind setup stays on the server as datamind-setup, and this runs the same checks, asks nothing and changes nothing:

bash
sudo datamind-setup preflight

It lists every network it found and where it learned it, every port DataMind needs and what holds it today, and the address ranges Docker would be given and why. Add --verbose to see all of it on screen; the log always has it. It checks the License Key too when PLATFORM_API_KEY is set and kept through sudo: sudo --preserve-env=PLATFORM_API_KEY datamind-setup preflight. It ends with Preflight only: nothing was changed. and exit code 0 when the install would go ahead, or with Preflight found blocking problems. Nothing was changed. and exit code 1 when something blocks it.

Docker's address ranges

Docker gives its networks private address ranges of their own. Where one of them overlaps a network your server reaches through a router or a VPN, such as another office, a data source or the subnets your users sit on, the server can no longer reach machines on that network, and SSH sessions from them drop. Docker checks only the networks attached to the server itself before it picks a range.

DataMind setup looks wider. It reads the networks this server knows about: its interfaces and routes, VPN configuration, firewall rules, DNS servers, network mounts, SSH sessions and known SSH hosts. It picks ranges clear of all of them and shows them before Docker is installed or changed:

The server cannot see subnets it has no route to, so it asks Use these ranges?. Choose Accept, or Change if your network team knows the ranges are used elsewhere. Change asks for the two ranges they confirmed free: docker0 bridge address, for example 10.99.0.1/24, and Base range for container networks, for example 10.99.64.0/18. A range that overlaps a network found on the server is used with a warning, because you chose it.

Ranges already set in /etc/docker/daemon.json are kept as they are, and nothing is asked about them. To give Docker your own ranges on a run without a terminal, add them to the file before you run the install command, for example:

json
{ "bip": "10.99.0.1/24", "default-address-pools": [{ "base": "10.99.64.0/18", "size": 24 }] }

After the first run you can also give them on the command line. To replace ranges the file already sets, add --yes:

bash
sudo datamind-setup --docker-bip 10.99.0.1/24 --docker-pool-base 10.99.64.0/18

A Docker that is already in use

DataMind setup never rewrites /etc/docker/daemon.json or restarts Docker without your yes when Docker already runs containers, or when DataMind is already installed on the server. It shows Docker is already in use on this server, what it would change and what leaving Docker alone means, and asks Change Docker now?:

Without a terminal, Docker is left as it is, with the same exception. To move it onto the new ranges later, run sudo datamind-setup --yes in a maintenance window. A Docker with nothing on it yet is restarted without asking, because there is nothing to interrupt.

If Docker runs rootless on the server, DataMind setup asks Use the system Docker for DataMind? before it installs or starts the system Docker beside it, because that changes how the server is secured. DataMind runs on the system Docker; Stop ends the install. A server runs one DataMind Installer: if one is already installed in another directory, the run stops before any change and prints the command that brings it up to date where it is.

What the install changes on the server

After you choose Install, DataMind setup makes these changes, in this order:

ChangeWhere
Saves the platform, the release channel and the install directory, so a later run needs no options/etc/datamind-setup/settings, readable by root only
Puts itself on the server, so you can run it again by name/usr/bin/datamind-setup
Adds Docker's address ranges, and your proxy when Docker needs it. Every other setting in the file is kept, and an existing file is saved first/etc/docker/daemon.json; the previous version is saved as /etc/docker/daemon.json.datamind-setup-backup
Installs Docker Engine and the Compose plugin when they are missing, starts Docker, and restarts it once when it must take up new rangesDocker's own packages
Creates the shared Docker network the DataMind Installer and DataMind OS useDocker
Signs the root account in to the registry with the License Keyplatform.datamind.ai
Downloads the DataMind Installer, then writes its Compose file and an .env holding the License Key; every other line of an existing .env is keptdocker-compose.yml and .env in the install directory, by default one under /opt
Pulls the Installer's images, starts it and waits until it reports healthyDocker
Logs the whole run. The log records every network the server knows about, so only root can read it/var/log/datamind-setup.log

On RHEL 10 and its rebuilds, when the kernel lacks a module Docker's networking needs, it also installs the kernel-modules-extra package before Docker starts. It adds nobody to the docker group.

When a step fails, DataMind setup prints Stopped during: <step>, then the changes it made so far, under Changes made to this host before stopping, so you know what is there:, and the command to run once the problem is fixed.

Run it again

Running it again is safe: it keeps what is already done and carries on. After the first run, from any directory:

bash
sudo datamind-setup

It uses the platform and install directory saved at the first run, asks for this server's License Key again, runs every check, then asks before it changes anything. Running the install command again does the same with a fresh download, and keeps the saved install directory unless you set INSTALL_DIR.

It is not how you update. The DataMind Installer updates itself, from its own screen; see Update the DataMind Installer.

Behind a proxy, keep your proxy settings through sudo, or the checks run without them. DataMind setup warns when sudo removed them and prints the command, for example sudo --preserve-env=https_proxy,http_proxy,no_proxy datamind-setup. The install command keeps them by itself; see Through a proxy.

Questions, answered

What do I need before I start?

A Linux server on x86_64, an account that can use sudo, and either this server's DataMind License Key or the client_id and client_secret DataMind issued you. See System requirements for the OS, hardware, network and ports.

Why does the install command ask for my password?

It runs DataMind setup as root with sudo, because the setup installs Docker and writes system settings such as /etc/docker/daemon.json. sudo asks for your password; run as root, nothing is asked. Nothing changes before you choose Install.

Can my IT team review the checks before anything changes?

Yes. Run the install command and choose Stop at the question that follows the checks: nothing changes, and the report is in /var/log/datamind-setup.log. After the first run, sudo datamind-setup preflight runs the same checks without asking anything. See Have the checks reviewed before anything changes.

Is it safe to run the install command again?

Yes. It keeps what is already done and carries on, and it never changes or restarts a Docker that runs containers without your yes. After the first run, sudo datamind-setup does the same with the saved settings. See Run it again.

Which address ranges should I give Docker?

Accept the ranges DataMind setup shows, unless your network team knows they are used somewhere this server cannot see, such as another office or the subnets your users sit on. Then choose Change and enter two private ranges they confirmed free. See Docker's address ranges.

Should I use the License Key or the Azure client secret?

Use the License Key if you have one: with it, every image, install file and update comes from platform.datamind.ai, and the host needs no Azure access. Use the Azure client secret only if DataMind issued you one instead of a key.

Can two servers share one License Key?

No. Each server needs its own. The first DataMind OS that checks in with a License Key keeps it, and another server that presents the same key is refused. Add an instance for each server.

How do I set up HTTPS?

Choose HTTPS on Configure Platform, enter the domain, and upload the certificate and its private key or give their paths on the server. The Installer checks the domain and the certificate, and Finish saves them once no check failed. To change the certificate after the install, set the paths in Configuration and click Apply changes. TLS and certificates has the full steps and every check.

Why does the download sit at 99%?

The percentage stops at 99% until every service group finishes its images, and the chip Finalizing pull — waiting on <services> names what is still pending. Wait for it to clear; the services then start.

What do I do when the installation finishes?

Open the Platform URL. That is your DataMind OS address. Continue with First sign-in to DataMind OS.