Skip to content

You are viewing documentation for Immuta version 2023.1.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Single Node Installation with Docker

Single Node Docker Support

Single Node Docker is not supported for production use cases.

Prerequisites

Review the potential impacts of Immuta's Rocky Linux 9 upgrade to your environment before proceeding.

Requirements

Software

The following packages need to be installed on the host system.

Sizing

Immuta recommends a size of m5.xlarge - m5.2xlarge (or equivalent).

TLS Certificates

All Immuta services use TLS certificates and HTTPS. For simplicity, these instructions generate a self-signed CA certificate and issue certificates for all internal connections between Immuta services. By default these certificates also will be valid for the external hostname you specify, but you can, and should, replace the external-facing portion with certificates issued by a Certificate Authority trusted by your users.

1 - Initialize Installation

If Docker is installed on a host with limited disk space.

Immuta recommends symlinking /var/lib/docker to a path mounted outside of /var if partitioned with less than 50GB.

Create a new directory called $DOCKER_HOME and copy the contents of /var/lib/docker to $DOCKER_HOME.

DOCKER_HOME=</path/to/new/var/lib/docker>
mkdir -p "${DOCKER_HOME:?}"
sudo systemctl stop docker
sudo rsync -a /var/lib/docker/ "${DOCKER_HOME:?}"/
sudo rm -rf /var/lib/docker
sudo ln -sv "${DOCKER_HOME:?}" /var/lib/docker
sudo systemctl start docker

1.1 - Download Single Node Docker CLI Utility

The Single Node Docker (SND) installation is managed by a command line utility called immuta-snd. You may download the utility using a web browser or your preferred CLI tool such as curl, or wget. Unless otherwise instructed, download the latest available version.

Web Browser

Navigate to https://archives.immuta.com/snd/. If you are prompted to log in and need basic authentication credentials, reach out to your Immuta support professional.

Select the desired version, then select the .tar.gz archive.

Console

curl --user <user> https://archives.immuta.com/snd/<version>/snd-v<version>.tar.gz --output snd-v<version>.tar.gz

wget --user <user> --ask-password https://archives.immuta.com/snd/<version>/snd-v<version>.tar.gz

Once the command is executed, you will be prompted for a password. Use your archive credentials. If you need the archive credentials again, reach out to your Immuta support professional.

1.2 - Install Single Node Docker CLI Utility

Best Practice: Recommended immuta-snd Installation Path

Immuta recommends installing immuta-snd to /usr/local/bin, however this is not a requirement. You may save the cli tool to your working directory instead.

User Privileges

Depending on how your user and host are configured it might be necessary to prefix the following command(s) with sudo.

tar -xvf snd-v<version>.tar.gz
mv snd-v<version> /usr/local/bin/immuta-snd
chmod +x /usr/local/bin/immuta-snd

1.3 - Create Configuration File

Best Practice: Recommended immuta.toml Path

Immuta recommends saving the immuta.toml to /etc/opt/immuta.

Create directory /etc/opt/immuta 

mkdir -m 755 /etc/opt/immuta

You may specify an alternative configuration path by redefining environment variable IMMUTA_SND_CONF.

Set environment variable IMMUTA_SND_CONF.

export IMMUTA_SND_CONF="/etc/opt/immuta/immuta.toml"
User Privileges

Depending on how your user and host are configured it might be necessary to prefix the following command(s) with sudo.

Create immuta.toml.

cat > $IMMUTA_SND_CONF <<EOF
version = 1

[immuta]

# Override default immuta installation path
# install_path =

# Override default immuta version
version = 2023.1.2

# Log Level    Numeric Value
# unset         0
# trace         5
# debug        10
# info         20
# notice       25
# warn         30
# error        40
# fatal        50
# alert        60
#
# logging_level =

# Override default docker registry url
# docker_registry_url =

# Override image pull policy (Accepted Values = ["Always","IfNotPresent","Never"]; default = "IfNotPresent")
# docker_image_pull_policy

# Override the hostname that will be used to access the Immuta Web Service
# and Query Engine. Must match external tls certificate
# hostname =

# Specify a custom certificate that is signed by a Certificate Authority that
# you trust. Used for all external communication.
# external_tls_cert =
# external_tls_key =

[db]

# Override default docker image url
# image =

# The maximum amount of memory the container can use. Integer in gigabytes
# memory_limit =

# Set custom environment variables inside container
# environment = []

# Append additional docker options to 'docker build' and 'docker run' command
# docker_options = []

# Bind mount a host path inside container
# volumes = []

[db.shared_memory]

# Size of /dev/shm. Integer in gigabytes.
# To disable set to '-1'
# size =

[fingerprint]

# Override default docker image url
# image =

# The maximum amount of memory the container can use. Integer in gigabytes
# memory_limit =

# Set custom environment variables inside container
# environment = []

# Append additional docker options to 'docker build' and 'docker run' command
# docker_options = []

# Bind mount a host path inside container
# volumes = []

[service]

# Override default docker image url
# image =

# The maximum amount of memory the container can use. Integer in gigabytes
# memory_limit =

# Set custom environment variables inside container
# environment = []

# Append additional docker options to 'docker build' and 'docker run' command
# docker_options = []

# Bind mount a host path inside container
# volumes = []

[cache]

# Override docker image url
# image =

# Set custom environment variables inside container
# environment = []

# Append additional docker options to 'docker build' and 'docker run' command
# docker_options = []

# Bind mount a host path inside container
# volumes = []

[proxy]

# Override default docker image url
# image =

# The maximum amount of memory the container can use. Integer in gigabytes
# memory_limit =

# Set custom environment variables inside container
# environment = []

# Append additional docker options to 'docker build' and 'docker run' command
# docker_options = []

# Bind mount a host path inside container
# volumes = []

# Override the port that will be used to access the Immuta Web Service
# port =

EOF

2 - Configure Immuta

Docker Logging Driver

The Docker logging driver is set to json-file for all Immuta containers. If you use a different logging Driver such as journald, then you must update key: docker_options in immuta.toml.

Some distribution packaged versions of Docker, such as the official CentOS package, use the journald logging driver by default.

2.1 - (Optional) Set Memory Limits

Although not required, Immuta highly recommends that you set memory limits for a single node deployment. Otherwise, you may encounter performance issues. The recommended memory profiles for immuta.toml can be adjusted by selecting the corresponding tab below.

[db]

memory_limit = 8

[fingerprint]

memory_limit = 4

[service]

memory_limit = 4

[proxy]

memory_limit = 1

[db]

memory_limit = 17

[fingerprint]

memory_limit = 6

[service]

memory_limit = 6

[proxy]

memory_limit = 2

[db]

memory_limit = 41

[fingerprint]

memory_limit = 8

[service]

memory_limit = 8

[proxy]

memory_limit = 2

[db]

memory_limit = 98

[fingerprint]

memory_limit = 12

[service]

memory_limit = 12

[proxy]

memory_limit = 2

2.2 - (Optional) Use Own Certificates for External Communication

Warning

Only follow the instructions below if you have valid TLS certificates for $HOSTNAME. Otherwise, simply skip this step to use the generated certificates for external connectivity.

If you have certificates that are valid for the host and are signed by a Certificate Authority that your users and systems trust, use the following script to copy the certificate and key into the correct place for the external certificates.

Edit the following two keys in immuta.toml.

[immuta]

external_tls_cert = '/path/to/your/certificate'
external_tls_key = '/path/to/your/key'

2.3 - (Optional) Configure Passwords

Note

If custom passwords aren't specified ones will be procedurally generated.

Create passwords.txt in your home directory. Modify passwords.txt with your desired password values. Each line is a different password. They are as follows:

  1. Password to use for the Docker registry user
  2. Password to use for the Immuta metadata and Query Engine database super user
  3. Password to use for the Immuta metadata database service user
  4. Password to use for the Immuta Query Engine service user

Warning

The password order must not deviate from the order listed above.

When setting passwords the following limitations must be considered:

  • Passwords are declared line by line. It is not possible to declare a password for the Immuta Query Engine service user without first declaring a password for the Immuta metadata database service user.
  • If you only declare a password for the Docker registry user the remaining passwords will be procedurally generated.
  • Passwords must comprise only alphanumeric characters.
cat > ${HOME:?}/passwords.txt <<EOF
<docker_registery_password>
<immuta_superuser_password>
<immuta_metadata_password>
<immuta_query_engine_password>
EOF
Example passwords.txt File 
RnncSnc72NsnPsQap9nWseEoXz3a
5H2ueSGE8xiI6a3TwI3CreHSJyFgYOvxFBHTsMVUIXdS8QCbiNUw9zrejVJQtzGa
1ej9kn6BIe4OgAckwMSK1LthmRRmGYDurXtcaOiL910oNkywqVcivQ2mDBV9ocDN
cGhpn2iaCIntByH8pWfItcNQA7qH4vdsi4kvtmlUmCGqRvc1DBIyDIO9PcaiCMTc

2.4 - (Optional) Disable Query Engine Port

If you will only use integrations, port 5432 is optional and can be disabled.

Edit the following in immuta.toml.

[db]

publish_port = false

3 - (Only for Internet-Connected Environments) Install Immuta

3.1 - Pull Images and Create Containers

Tip

If a passwords.txt file has been created you must pipe the file contents into the stdin of immuta-snd while using option --passwords-stdin

cat ${HOME:?}/passwords.txt | /usr/local/bin/immuta-snd init --passwords-stdin
User Privileges

Depending on how your user and host are configured it might be necessary to prefix the following command(s) with sudo.

/usr/local/bin/immuta-snd init --docker-registry-username <user> --docker-registry-password <password>
Docker Registry Authentication

Reach out to your Immuta support professional for your Immuta Docker Registry credentials.

You will only need to provide your docker registry credentials the first time using immuta-snd. Passing in --docker-registry-password and --docker-registry-username on consecutive installs is not necessary as Docker will cache your credentials.

4 - (Only for Non-Internet-Connected Environments) Install Immuta

If your Immuta system is configured to not have direct Internet access and cannot directly download the Immuta artifacts from our repositories, you may download these artifacts to a machine that does have Internet connectivity and then transfer them to the environment where you intend to deploy them.

4.1 - Download Artifacts

Navigate to https://archives.immuta.com/docker/. If you are prompted to log in and need basic authentication credentials, reach out to your Immuta support professional. Once there, the docker image tarballs can be found under "/docker/2023.1.2/".

Simply download the appropriate

immuta-2023.1.2-all.tar.gz

file and transfer it to your destination system.

The *-all.tar.gz file is a single tarball that contains all the Immuta Docker images.

4.2 - Create Containers

Tip

If a passwords.txt file has been created you must pipe the file contents into the stdin of immuta-snd while using option --passwords-stdin

cat ${HOME:?}/passwords.txt | /usr/local/bin/immuta-snd init --passwords-stdin

/usr/local/bin/immuta-snd init --immuta-artifacts /path/to/immuta-2023.1.2-all.tar.gz
Docker Registry Authentication

Reach out to your Immuta support professional for your Immuta Docker Registry credentials.

You will only need to provide your docker registry credentials the first time using immuta-snd. Passing in --docker-registry-password and --docker-registry-username on consecutive installs is not necessary as Docker will cache your credentials.

5 - Start Immuta

5.1 - Start Containers

/usr/local/bin/immuta-snd start

6 - Post-Install Activities

6.1 - Verifying the Installation

After executing the immuta-snd start command, it's often a good idea to watch the Docker containers come online. The Linux watch command provides a great way of doing this. The command below causes a immuta-snd ps to be run every second until you press ctrl-C to stop it.

watch -n1 /usr/local/bin/immuta-snd ps
Example Output 
CONTAINER ID   IMAGE                                                    COMMAND                  CREATED             STATUS          PORTS                          NAMES
fbcbea73c2b2   registry.immuta.com/memcached:1.6-alpine                 "docker-entrypoint.s…"   33 seconds ago      Up 32 seconds   11211/tcp                      immuta-cache
fd4a8d05c017   registry.immuta.com/nginx:1.18-alpine                    "nginx -g 'daemon of…"   33 seconds ago      Up 32 seconds   80/tcp, 0.0.0.0:443->443/tcp   immuta-proxy
e3b53e44e1bd   registry.immuta.com/immuta/immuta-fingerprint:2023.1.2   "immuta-fingerprint …"   34 seconds ago      Up 32 seconds                                  immuta-fingerprint
c484a44f53f7   registry.immuta.com/immuta/immuta-service:2023.1.2       "/docker-entrypoint.…"   34 seconds ago      Up 32 seconds                                  immuta-service
6821e3c4291f   registry.immuta.com/immuta/immuta-db:2023.1.2            "/docker-entrypoint.…"   34 seconds ago      Up 24 seconds   0.0.0.0:5432->5432/tcp         immuta-db

A great first test is to confirm that all of the containers come up and stay up for more than a minute. Typical installation configuration issues will result in containers failing and attempting to restart. If restarts are noticed among any of your containers, please review the configuration sections above.

Once the services have started, open your web browser and navigate to your configured Immuta URL and follow the login screen prompts to create the initial admin user.

Once the initial user has been created, you can navigate to https://<immuta url>/#/configuration to edit advanced configuration values on the App Settings page.

6.2 - Password Management

If you set custom passwords in Step 2 be sure to delete the ${HOME}/passwords.txt file from the host.

6.3 - Reset the Installation

If you need to reset your Immuta instance to a blank slate for any reason, you can do so by running the following command:

/usr/local/bin/immuta-snd destroy

This will delete/stop all Immuta containers and delete data volumes so that you can start over with a fresh installation.

6.4 - Configure Backups

See Single Node Docker Backups for more information.