TrueCommand Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Installing the TrueCommand Container using Docker on Linux.

4 minute read.

Last Modified 2024-03-15 13:07 EDT

Installing the TrueCommand Container

Requirements

Install the Docker Engine and Docker Desktop, or use Podman.

To run TrueCommand in Docker on Linux, you must have:

A 64-bit Linux distro (Debian recommended)
Linux kernel support: 4.x+
1 CPU with 2 GiB RAM
1 Hard disk with 10 - 50 GiB storage space
Customer networking settings and internet access

Fetch and Deploy the Container Image

Before fetching the TrueCommand container image, create a local directory to store TrueCommand container data.

Do not try to use the same host directory for two different containers! Doing so results in file conflicts and database corruption.

Enter mkdir directory, where directory is the new name.

After creating the new directory, fetch and run the TrueCommand image.

Open a terminal and enter docker run --detach -v "/hostdir:/data" -p port:80 -p ssl:443 ghcr.io/ixsystems/truecommand:v3.0.0 .

Where hostdir is a directory on the host machine for Docker container data, 80 is the TrueCommand web interface port number, and 443 is the port number for secure web interface access.

To install the container with an earlier TrueCommand release, replace v3.0.0 with the desired TrueCommand version tag. For example: docker run --detach -v "/DockerDir:/data" -p 9004:80 -p 9005:443 ghcr.io/ixsystems/truecommand:v2.3.3

To preview the latest features in a non-production experimental environment, install the container with the latest TrueCommand development build: docker run --detach -v "/DockerDir:/data" -p 9004:80 -p 9005:443 ghcr.io/ixsystems/truecommand:latest

Although Docker containers have several run methods, TrueCommand requires a bind mount or docker volume manage to keep the database consistent between runs. Recreating the database creates a new system ID and invalidates a previously created license.

Accessing the TrueCommand Web Interface

After fetching the TrueCommand Docker container, enter docker ps to see details about running containers.

DockerContainerList

Use the port assigned to the container to access the web interface. The list from docker ps contains a PORTS column. Find the port associated with the ghcr.io/ixsystems/truecommand image. The PORTS entry is listed as 0.0.0.0:port->80/tcp, 0.0.0.0:sslport->443/tcp where port and sslport are the ports specified earlier.

To access the web interface with no encryption, enter hostsystemIPaddress:port in a browser address bar, where hostsystemIPaddress is the IP address of the host system that is running the TrueCommand Docker container. To access the web interface with standard SSL encryption, enter https://hostsystemIPaddress:sslport in a browser address bar.

Access the container directly via shell with docker exec -it CONTAINER_ID /bin/bash to make advanced configuration changes.

The connection cannot be established?

If you cannot establish a connection to the web interface, add the container ports as an exception to the host system firewall.

Adding Browser Exceptions

TrueCommand uses a self signed certificate for a secure connection. Because of this, many Internet browsers consider the IP address or DNS host name untrustworthy. In these cases, you must add the IP address or DNS host name as an exception to the browser to access the web interface. Adding an exception is shown here for two different browsers, but the procedure is similar for most browsers.

After the initial login, prevent this in future logins by adding your own certificate keypair and / or certificate authority (CA).

Browser Security Exceptions

Chrome

Click Advanced to view information about the error code. Click Proceed to hostname (unsafe).

Firefox

Click Advanced to view information about the error code.

Click Add Exception. Set Permanently store this exception to permanently store the IP address or DNS host name in Firefox. Click Confirm Security Exception.

Back Up the Container Volume

Before updating the container, create and store a copy of the container /data directory in a separate location. You can use this to restore the TrueCommand configuration and saved data in the event of an issue appearing during the update process. In a command line, cp the TrueCommand container /data directory to a different temporary or storage location: For example:

joe@joe-minty:~$ cp -r /home/joe/Documents/TrueCommandContainer/data /home/joe/temp/

If something goes wrong and you need to create a new container, you can remove the empty /data directory from the container and replace it with the previously saved TrueCommand configuration. For example:

joe@joe-minty:~$ rm -d /home/joe/Documents/NewTrueCommandContainer/data
joe@joe-minty:~$ cp -r /home/joe/temp/data /home/joe/Documents/NewTrueCommandContainer/

Update Process

To update the docker container, download the latest TrueCommand image and remove the existing TrueCommand container. Then restart the container using the latest TrueCommand image and existing TrueCommand storage volume.

To remove the existing container, enter docker rm TrueCmd_contained.

Start a new container that uses the new image, but make sure to use the existing volume used for the original TrueCommand container. For example: docker run –name the name to call the container> -v “local host directory:/data” -p :80 sslport :443 –detach ghcr.io/ixsystems/truecommand:v3.0.0