Skip to content

You are viewing documentation for Immuta version 2020.3.

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

cancel

Single Node Installation with Docker

Audience: System Administrators

Content Summary: This page details how to install the Immuta software on a single host using Docker.

Prerequisites:

Required Software

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

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 - specifically in production.

To install Single Node with Docker you must,

  1. Initialize Installation
  2. Source Installation Environment
  3. Generate TLS Certificates
  4. Initialize Immuta Configuration
  5. Initialize Fingerprint Configuration
  6. Initialize Nginx Proxy Configuration
  7. Initialize Docker Configuration
  8. Enable Backups/Restoration Support
  9. Start Immuta
  10. Post-Install Activities
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 - Initialize Installation

1.1 - Create Installation Directory

To begin the installation, create a directory then set it as your working directory.

Best Practice: Recommended Directory

Immuta recommends the directory /opt/immuta, but this is not a requirement.

mkdir -p /opt/immuta
cd /opt/immuta

1.2 - Configure Installation Environment

Before starting the service, you need to update and generate the configuration files. To do so, you will need to set the following environment variables. These variables are set in the scripts below.

  • IMMUTA_HOME: Directory where the Immuta installation resides.
  • IMMUTA_HOSTNAME: The hostname that will be used to access the Immuta Web Service and Query Engine.
  • IMMUTA_VERSION: The Immuta version number.
  • IMMUTA_SERVICE_IMAGE: The Docker image to use for the Immuta Web Service. Should be in the format of repository:tag.
  • IMMUTA_DB_IMAGE: The Docker image to use for the Immuta Query Engine. Should be in the format of repository:tag.
  • IMMUTA_FINGERPRINT_IMAGE: The Docker image to use for the Immuta Fingerprint Service. Should be in the format of repository:tag.
  • IMMUTA_CACHE_IMAGE: The Docker image to use for the cache service. Should be in the format of repository:tag.
  • IMMUTA_PROXY_IMAGE: The Docker image to use for the proxy service. Should be in the format of repository:tag.
  • IMMUTA_SUPERUSER_PASSWORD: Password to use for the Immuta metadata and Query Engine database super user.
  • IMMUTA_METADATA_PASSWORD: Password to use for the Immuta metadata database service user.
  • IMMUTA_QUERY_ENGINE_PASSWORD: Password to use for the Immuta Query Engine service user.

These values are set properly by the script below, which will create an immuta-env file file in your IMMUTA_HOME. This file will hold your environment settings for future use.

The values at the end set a memory limit profile that corresponds to the amount of memory available on the installation node.

Best Practice: 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 profile configurations are adjusted by selecting the appropriate tab below.

cat > immuta-env <<EOF
export IMMUTA_HOME=$(pwd)
export IMMUTA_HOSTNAME=immuta.my-company.com
export IMMUTA_VERSION=2020.3.6
export IMMUTA_SERVICE_IMAGE=registry.immuta.com/immuta/immuta-service:\${IMMUTA_VERSION}
export IMMUTA_DB_IMAGE=registry.immuta.com/immuta/immuta-db:\${IMMUTA_VERSION}
export IMMUTA_FINGERPRINT_IMAGE=registry.immuta.com/immuta/immuta-fingerprint:\${IMMUTA_VERSION}
export IMMUTA_CACHE_IMAGE=registry.immuta.com/memcached:1.5-alpine
export IMMUTA_PROXY_IMAGE=registry.immuta.com/nginx:1.13-alpine
export IMMUTA_SUPERUSER_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_METADATA_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_QUERY_ENGINE_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_MEM_LIMIT_DB=8g
export IMMUTA_MEM_LIMIT_SERVICE=2g
export IMMUTA_MEM_LIMIT_FINGERPRINT=1g
export IMMUTA_MEM_LIMIT_PROXY=1g
EOF
chmod 600 immuta-env

cat > immuta-env <<EOF
export IMMUTA_HOME=$(pwd)
export IMMUTA_HOSTNAME=immuta.my-company.com
export IMMUTA_VERSION=2020.3.6
export IMMUTA_SERVICE_IMAGE=registry.immuta.com/immuta/immuta-service:\${IMMUTA_VERSION}
export IMMUTA_DB_IMAGE=registry.immuta.com/immuta/immuta-db:\${IMMUTA_VERSION}
export IMMUTA_FINGERPRINT_IMAGE=registry.immuta.com/immuta/immuta-fingerprint:\${IMMUTA_VERSION}
export IMMUTA_CACHE_IMAGE=registry.immuta.com/memcached:1.5-alpine
export IMMUTA_PROXY_IMAGE=registry.immuta.com/nginx:1.13-alpine
export IMMUTA_SUPERUSER_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_METADATA_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_QUERY_ENGINE_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_MEM_LIMIT_DB=17g
export IMMUTA_MEM_LIMIT_SERVICE=5g
export IMMUTA_MEM_LIMIT_FINGERPRINT=2g
export IMMUTA_MEM_LIMIT_PROXY=2g
EOF
chmod 600 immuta-env

cat > immuta-env <<EOF
export IMMUTA_HOME=$(pwd)
export IMMUTA_HOSTNAME=immuta.my-company.com
export IMMUTA_VERSION=2020.3.6
export IMMUTA_SERVICE_IMAGE=registry.immuta.com/immuta/immuta-service:\${IMMUTA_VERSION}
export IMMUTA_DB_IMAGE=registry.immuta.com/immuta/immuta-db:\${IMMUTA_VERSION}
export IMMUTA_FINGERPRINT_IMAGE=registry.immuta.com/immuta/immuta-fingerprint:\${IMMUTA_VERSION}
export IMMUTA_CACHE_IMAGE=registry.immuta.com/memcached:1.5-alpine
export IMMUTA_PROXY_IMAGE=registry.immuta.com/nginx:1.13-alpine
export IMMUTA_SUPERUSER_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_METADATA_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_QUERY_ENGINE_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
head -n 1)
export IMMUTA_MEM_LIMIT_DB=41g
export IMMUTA_MEM_LIMIT_SERVICE=12g
export IMMUTA_MEM_LIMIT_FINGERPRINT=2g
export IMMUTA_MEM_LIMIT_PROXY=2g
EOF
chmod 600 immuta-env

cat > immuta-env <<EOF
export IMMUTA_HOME=$(pwd)
export IMMUTA_HOSTNAME=immuta.my-company.com
export IMMUTA_VERSION=2020.3.6
export IMMUTA_SERVICE_IMAGE=registry.immuta.com/immuta/immuta-service:\${IMMUTA_VERSION}
export IMMUTA_DB_IMAGE=registry.immuta.com/immuta/immuta-db:\${IMMUTA_VERSION}
export IMMUTA_FINGERPRINT_IMAGE=registry.immuta.com/immuta/immuta-fingerprint:\${IMMUTA_VERSION}
export IMMUTA_CACHE_IMAGE=registry.immuta.com/memcached:1.5-alpine
export IMMUTA_PROXY_IMAGE=registry.immuta.com/nginx:1.13-alpine
export IMMUTA_SUPERUSER_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
    head -n 1)
export IMMUTA_METADATA_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
    head -n 1)
export IMMUTA_QUERY_ENGINE_PASSWORD=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 30 | \
    head -n 1)
export IMMUTA_MEM_LIMIT_DB=98g
export IMMUTA_MEM_LIMIT_SERVICE=12g
export IMMUTA_MEM_LIMIT_FINGERPRINT=3g
export IMMUTA_MEM_LIMIT_PROXY=2g
EOF
chmod 600 immuta-env

After generating the immuta-env file, update the file to set values that are unique to your installation.

Warning

Ensure your IMMUTA_HOSTNAME is specified correctly or you may have issues with the installation process.

2 - Source Installation Environment

Source the environment variables that you created by running the command below:

source ./immuta-env
Tip

You may verify your environment is properly configured at any time by running

env | grep 'IMMUTA_'

3 - Generate TLS Certificates

In order to secure the internal docker network traffic between Immuta services, generate a self-signed Certificate Authority using openssl and then issue a certificate that will be valid for all of the necessary Subject Alternative Names.

3.1 - Generate Certificates for Internal Communication

Run the script below to generate a certificate authority and sign certificates for internal communication.

Certificate Expiration

By default this CA and certificate will be valid for 3 years. To increase or decrease the validity period, change all occurrences of 1024 to something else.

TLS_BASE_DIR="${IMMUTA_HOME}/tls"
GEN_DIR="${TLS_BASE_DIR}/_generated"
EXT_DIR="${TLS_BASE_DIR}/_external"
mkdir -p "${GEN_DIR}" "${EXT_DIR}"

openssl req -new -sha256 -nodes -days 1024 -newkey rsa:2048 -x509 \
    -out "${GEN_DIR}/immuta-ca.crt" -keyout "${GEN_DIR}/immuta-ca.key" \
    -config <(
cat <<-EOF
[req]
prompt = no
extensions = req_ext
distinguished_name = dn
[dn]
C=US
ST=Maryland
L=College Park
O=Immuta
OU=Immuta Deployment
CN=Immuta CA for Single Node Docker
[req_ext]
basicConstraints = CA:TRUE
keyUsage = digitalSignature, keyEncipherment
EOF
)

openssl req -new -sha256 -nodes -newkey rsa:2048 \
    -out "${GEN_DIR}/immuta.csr" -keyout "${GEN_DIR}/immuta.key" \
    -config <(
cat <<-EOF
[req]
prompt = no
distinguished_name = dn
[dn]
C=US
ST=Maryland
L=College Park
O=Immuta
OU=Immuta Deployment
CN=${IMMUTA_HOSTNAME}
EOF
)

openssl x509 -req -in "${GEN_DIR}/immuta.csr" -CA "${GEN_DIR}/immuta-ca.crt" \
    -CAkey "${GEN_DIR}/immuta-ca.key" \
    -CAserial "${GEN_DIR}/immuta-ca.srl" \
    -CAcreateserial \
    -out "${GEN_DIR}/immuta.crt" \
    -days 1024 -sha256 \
    -extfile <(cat <<-EOF
basicConstraints=CA:FALSE
keyUsage=digitalSignature,keyEncipherment
subjectAltName = @san
[san]
DNS.1 = ${IMMUTA_HOSTNAME}
DNS.2 = proxy.immuta
DNS.3 = service.immuta
DNS.4 = db.immuta
DNS.5 = fingerprint.immuta
EOF
)

3.2 - (OPTIONAL) Use Own Certificates for External Communication

Warning

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

If you have certificates that are valid for IMMUTA_HOSTNAME 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.

First, export variables that point to your certificate and key file.

export EXTERNAL_CERT="/path/to/your/certificate"
export EXTERNAL_KEY="/path/to/your/key"

Next, run the following script to copy your certificates to the required location.

EXT_DIR="${IMMUTA_HOME}/tls/_external"
mkdir -p "${EXT_DIR}"
if [ -f ${EXTERNAL_CERT} -a -f ${EXTERNAL_KEY} ]; then
    cp -f "${EXTERNAL_CERT}" "${EXT_DIR}/immuta.crt"
    cp -f "${EXTERNAL_KEY}" "${EXT_DIR}/immuta.key"
else
    echo "Invalid configuration. External ertificate or key not found"
fi

3.3 - Install/Migrate Certificates for Container Handling

Finally, run the script below to properly stage all certificates for the Immuta containers.

TLS_BASE_DIR="${IMMUTA_HOME}/tls"
GEN_DIR="${TLS_BASE_DIR}/_generated"
EXT_DIR="${TLS_BASE_DIR}/_external"

# migrate older deployments
if [ -d "${TLS_BASE_DIR}/internal" -a ! -d ${GEN_DIR} ]; then
    cp -a ${TLS_BASE_DIR}/internal ${GEN_DIR}
fi
if [ -d "${TLS_BASE_DIR}/external" -a ! -d ${EXT_DIR} ]; then
    cp -a ${TLS_BASE_DIR}/external ${EXT_DIR}
fi

mkdir -p "${GEN_DIR}" "${EXT_DIR}"

# external cert (default to same as internal if not present)
if [ ! -f "${EXT_DIR}/immuta.crt" ]; then
    cp -af "${GEN_DIR}/immuta-ca.crt" "${EXT_DIR}/immuta-ca.crt"
    cp -af "${GEN_DIR}/immuta.crt" "${EXT_DIR}/immuta.crt"
    cp -af "${GEN_DIR}/immuta.key" "${EXT_DIR}/immuta.key"
fi
chmod 640 ${EXT_DIR}/*.crt
chmod 600 ${EXT_DIR}/*.key

# fingerprint cert (internal/generated only)
SVC_DIR="${TLS_BASE_DIR}/fingerprint"
mkdir -p ${SVC_DIR}
cp -af "${GEN_DIR}/immuta-ca.crt" "${SVC_DIR}/immuta-ca.crt"
cp -af "${GEN_DIR}/immuta.crt" "${SVC_DIR}/immuta.crt"
cp -af "${GEN_DIR}/immuta.key" "${SVC_DIR}/immuta.key"
chown 15102:15102 ${SVC_DIR}/*
chmod 640 ${SVC_DIR}/*.crt
chmod 600 ${SVC_DIR}/*.key

## service cert (internal/generated only, behind proxy)
SVC_DIR="${TLS_BASE_DIR}/service"
mkdir -p ${SVC_DIR}
# keep internal only becuase of proxy in front
cp -af "${GEN_DIR}/immuta-ca.crt" "${SVC_DIR}/immuta-ca.crt"
cp -af "${GEN_DIR}/immuta.crt" "${SVC_DIR}/immuta.crt"
cp -af "${GEN_DIR}/immuta.key" "${SVC_DIR}/immuta.key"
chown 1000:1000 ${SVC_DIR}/*
chmod 640 ${SVC_DIR}/*.crt
chmod 600 ${SVC_DIR}/*.key

## database cert (external)
SVC_DIR="${TLS_BASE_DIR}/db"
mkdir -p ${SVC_DIR}
# keep our internal CA cert for internal comms
cp -af "${GEN_DIR}/immuta-ca.crt" "${SVC_DIR}/immuta-ca.crt"
# use external certs (if available) for external access to query engine
cp -af "${EXT_DIR}/immuta.crt" "${SVC_DIR}/immuta.crt"
cp -af "${EXT_DIR}/immuta.key" "${SVC_DIR}/immuta.key"
chown 1000:1000 ${SVC_DIR}/*
chmod 640 ${SVC_DIR}/*.crt
chmod 600 ${SVC_DIR}/*.key

## proxy cert (external)
SVC_DIR="${TLS_BASE_DIR}/proxy"
mkdir -p ${SVC_DIR}
# use external certs (if available) for external access to the web UI
cp -af "${EXT_DIR}/immuta.crt" "${SVC_DIR}/immuta.crt"
cp -af "${EXT_DIR}/immuta.key" "${SVC_DIR}/immuta.key"
chown 1000:1000 ${SVC_DIR}/*
chmod 640 ${SVC_DIR}/*.crt
chmod 600 ${SVC_DIR}/*.key

4 - Initialize Immuta Configuration

This will generate a base Immuta configuration.

mkdir -p "${IMMUTA_HOME}/volumes/config"

echo "---
server:
  host: 0.0.0.0
  port: 8443
  useSSL: true
  tls:
    key: /etc/immuta/tls/service.key
    cert: /etc/immuta/tls/service.crt
    ca: /etc/immuta/tls/ca.crt
    requestCert: false
  cache:
    engine: catbox-memcached
    host: cache.immuta
    partition: cache
databases:
  immuta:
    connections:
      immutaDb:
        host: db.immuta
        ssl: true
        password: ${IMMUTA_METADATA_PASSWORD}
      featureStoreDb:
        host: db.immuta
        ssl: true
        password: ${IMMUTA_QUERY_ENGINE_PASSWORD}
publicImmutaUrl: https://${IMMUTA_HOSTNAME}
publicPostgres:
  host: ${IMMUTA_HOSTNAME}
  port: 5432
  ssl: true
fingerprints:
  uri: https://fingerprint.immuta:5001
  ca: /etc/immuta/tls/ca.crt
  queryEngineHost: db.immuta
  queryEnginePort: 5432
" > "${IMMUTA_HOME}/volumes/config/config.yml"

chown -R 1000:1000 "${IMMUTA_HOME}/volumes/config"

5 - Initialize Fingerprint Configuration

This will generate a base Immuta Fingerprint Service configuration.

mkdir -p "${IMMUTA_HOME}/volumes/fingerprint"

echo "
address: \"0.0.0.0\"
port: 5001
tls:
  enabled: true
  key: /etc/fingerprint/tls/tls.key
  cert: /etc/fingerprint/tls/tls.crt
" > "${IMMUTA_HOME}/volumes/fingerprint/config.yml"
chown -R 15102:15102 "${IMMUTA_HOME}/volumes/fingerprint"

6 - Initialize Nginx Proxy Configuration

This config will be used by the proxy (nginx) service.

mkdir -p "${IMMUTA_HOME}/volumes/proxy"

echo "
user  nginx;
worker_processes  1;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;
events {
  worker_connections  1024;
}
http {
  include       /etc/nginx/mime.types;
  default_type  application/octet-stream;
  log_format  main  '\$remote_addr - \$remote_user [\$time_local] \"\$request\" '
                    '\$status \$body_bytes_sent "\$http_referer" '
                    '\"\$http_user_agent\" \"\$http_x_forwarded_for\"';
  access_log  /var/log/nginx/access.log  main;
  sendfile        on;
  keepalive_timeout  65;
  resolver 127.0.0.11;

  map \$http_upgrade \$connection_upgrade {
      default upgrade;
      ''      close;
  }

  upstream service {
    server service.immuta:8443;
  }
  server {
    listen 443 ssl;
    server_name ${IMMUTA_HOSTNAME};
    ssl_certificate /etc/nginx/proxy.crt;
    ssl_certificate_key /etc/nginx/proxy.key;
    ssl on;
    ssl_protocols TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS';
    ssl_session_cache shared:SSL:10m;

    client_max_body_size 1g;

    location / {
      proxy_pass https://service;
      proxy_ssl_certificate /etc/nginx/proxy.crt;
      proxy_ssl_certificate_key /etc/nginx/proxy.key;
      proxy_ssl_trusted_certificate /etc/nginx/ca.crt;
      proxy_set_header X-Real-IP \$remote_addr;
      proxy_set_header Host \$host;
      proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Host \$host;
      proxy_set_header Upgrade \$http_upgrade;
      proxy_set_header Connection \$connection_upgrade;
    }
  }
}
" > "${IMMUTA_HOME}/volumes/proxy/nginx.conf"

7 - Initialize Docker Configuration

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 the driver option for all containers in the docker-compose.yaml file.

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

echo "
---
version: '2'
services:
  db:
    image: ${IMMUTA_DB_IMAGE}
    container_name: db
    restart: unless-stopped
$([ ! -z ${IMMUTA_MEM_LIMIT_DB} ] && \
echo "    mem_limit: ${IMMUTA_MEM_LIMIT_DB}
    memswap_limit: ${IMMUTA_MEM_LIMIT_DB}
    mem_swappiness: 0")
    ports:
    - \"5432:5432\"
    environment:
    - USER_AUTH_ENDPOINT=https://service.immuta:8443
    - IMMUTA_METADATA_PASSWORD=${IMMUTA_METADATA_PASSWORD}
    - IMMUTA_FEATURE_PASSWORD=${IMMUTA_QUERY_ENGINE_PASSWORD}
    - SUPERUSER_PASSWORD=${IMMUTA_SUPERUSER_PASSWORD}
    - CA_FILE=/etc/immuta/tls/ca.crt
    - PG_SSL=true
    - PG_SSL_CERT_FILE=/etc/immuta/tls/postgresql.crt
    - PG_SSL_KEY_FILE=/etc/immuta/tls/postgresql.key
    - SSL_PEER_VERIFICATION=${IMMUTA_SSL_PEER_VERIFICATION:-true}
    - SSL_HOST_VERIFICATION=${IMMUTA_SSL_HOST_VERIFICATION:-true}
    # Set to false to disable database backup restoration if non-empty
    - DB_RESTORE_ENABLED=true
    volumes:
    - ${IMMUTA_HOME}/tls/db/immuta-ca.crt:/etc/immuta/tls/ca.crt
    - ${IMMUTA_HOME}/tls/db/immuta.crt:/etc/immuta/tls/postgresql.crt
    - ${IMMUTA_HOME}/tls/db/immuta.key:/etc/immuta/tls/postgresql.key
    - db:/var/lib/immuta/postgresql/data:z
    - ${IMMUTA_HOME}/volumes/db/backups:/var/lib/immuta/postgresql/backups:Z
    - ${IMMUTA_HOME}/volumes/db/restore:/var/lib/immuta/postgresql/restore:Z
    networks:
      immuta:
        aliases:
        - db.immuta
    logging:
      driver: \"json-file\"
      options:
        max-size: \"100m\"
        max-file: \"1\"
  service:
    image: ${IMMUTA_SERVICE_IMAGE}
    container_name: service
    restart: unless-stopped
$([ ! -z ${IMMUTA_MEM_LIMIT_SERVICE} ] && \
echo "    mem_limit: ${IMMUTA_MEM_LIMIT_SERVICE}
    memswap_limit: ${IMMUTA_MEM_LIMIT_SERVICE}
    mem_swappiness: 0")
    environment:
    - WORKER_COUNT=4
    - IMMUTA_CACHE_MB=2048
    - CONFIG_FILE=/etc/immuta/config/config.yml
    - WAIT_FOR_POSTGRES=db.immuta:5432/bometadata,db.immuta:5432/immuta
    depends_on:
    - db
    networks:
      immuta:
        aliases:
        - service.immuta
    volumes:
    - ${IMMUTA_HOME}/tls/service/immuta.key:/etc/immuta/tls/service.key
    - ${IMMUTA_HOME}/tls/service/immuta.crt:/etc/immuta/tls/service.crt
    - ${IMMUTA_HOME}/tls/service/immuta-ca.crt:/etc/immuta/tls/ca.crt
    - ${IMMUTA_HOME}/volumes/config:/etc/immuta/config:z
    logging:
      driver: \"json-file\"
      options:
        max-size: \"100m\"
        max-file: \"1\"
  fingerprint:
    image: ${IMMUTA_FINGERPRINT_IMAGE}
    command: immuta-fingerprint --config /etc/fingerprint/config.yml
    container_name: fingerprint
    restart: unless-stopped
$([ ! -z ${IMMUTA_MEM_LIMIT_FINGERPRINT} ] && \
echo "    mem_limit: ${IMMUTA_MEM_LIMIT_FINGERPRINT}
    memswap_limit: ${IMMUTA_MEM_LIMIT_FINGERPRINT}
    mem_swappiness: 0")
    networks:
      immuta:
        aliases:
        - fingerprint.immuta
    volumes:
    - ${IMMUTA_HOME}/tls/fingerprint/immuta.key:/etc/fingerprint/tls/tls.key
    - ${IMMUTA_HOME}/tls/fingerprint/immuta.crt:/etc/fingerprint/tls/tls.crt
    - ${IMMUTA_HOME}/tls/fingerprint/immuta-ca.crt:/etc/fingerprint/tls/ca.crt
    - ${IMMUTA_HOME}/volumes/fingerprint/config.yml:/etc/fingerprint/config.yml
    logging:
      driver: \"json-file\"
      options:
        max-size: \"100m\"
        max-file: \"1\"
  proxy:
    image: ${IMMUTA_PROXY_IMAGE}
    container_name: proxy
    restart: unless-stopped
    depends_on:
    - service
    - db
$([ ! -z ${IMMUTA_MEM_LIMIT_PROXY} ] && \
echo "    mem_limit: ${IMMUTA_MEM_LIMIT_PROXY}
    memswap_limit: ${IMMUTA_MEM_LIMIT_PROXY}
    mem_swappiness: 0")
    ports:
    - \"443:443\"
    volumes:
    - ${IMMUTA_HOME}/volumes/proxy/nginx.conf:/etc/nginx/nginx.conf:ro
    - ${IMMUTA_HOME}/tls/proxy/immuta.key:/etc/nginx/proxy.key
    - ${IMMUTA_HOME}/tls/proxy/immuta.crt:/etc/nginx/proxy.crt
    networks:
      immuta:
        aliases:
        - proxy.immuta
    logging:
      driver: \"json-file\"
      options:
        max-size: \"100m\"
        max-file: \"1\"
  cache:
    image: ${IMMUTA_CACHE_IMAGE}
    container_name: immuta-memcached
    restart: unless-stopped
    command:
      - memcached
      - -m
      - \"2048\"
    networks:
      immuta:
        aliases:
          - cache.immuta
    logging:
      driver: \"json-file\"
      options:
        max-size: \"100m\"
        max-file: \"1\"
volumes:
  db:
networks:
  immuta:
    external: true
" > "${IMMUTA_HOME}/docker-compose.yml"

8 - Enable Backups/Restoration Support

8.1 - Enable Backups Support

This step will ensure your instance is staged for housing backups and restoring from a backup if desired.

First, create the appropriate backup and restore directories.

mkdir -p "${IMMUTA_HOME}/volumes/db/backups"
mkdir -p "${IMMUTA_HOME}/volumes/db/restore"
chown -R 1000:1000 "${IMMUTA_HOME}/volumes/db"

8.2 - (OPTIONAL) Enable Restoration from a Backup

If you wish to restore from a previous backup, simply copy your backup into the restore directory and ensure the file is owned by UID 1000 as shown.

cp path/to/your/backup.tar.gz "${IMMUTA_HOME}/volumes/db/restore/"
chown -R 1000:1000 "${IMMUTA_HOME}/volumes/db/restore"
Tip

Immuta's backup scripts will generate file names with associated timestamps like immuta-20200807053425.tar.gz. If multiple backups are provided in the restore directory, the restoration script will identify the most recent timestamp and restore from that backup.

9 - (Only for Non-Internet-Connected Environments) Stage Immuta Artifacts

9.1 - Download and Stage Docker Images

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. Below are two different, but equivalent, methods for doing these downloads.

The easiest method to gather all the Immuta images is to download them as a single tarball from https://archives.immuta.com/docker/. You may be prompted to login if your credentials are not cached. In that case, retrieve those from https://download.immuta.com, using your Immuta Accounts credentials to access that site. If you go through the download site, an easy way to get to the archives site is to scroll to the bottom of that page and click the here link under the "All Archives" heading. That will log you into the artifacts site in one click. Once there, the docker image tarballs can be found under "/docker/2020.3.6/".

Simply download the appropriate

immuta-2020.3.6-all.tar.gz

file and transfer it to your destination system.

Once copied to the destination, unpack the tarball using the following command:

tar xzf immuta-2020.3.6-all.tar.gz

If your Internet-connected system has Docker installed, you can use that to pull the necessary artifacts and "save" them for transport to the destination Immuta environment.

Use your Docker login credentials to access the Immuta Docker Registry:

docker login -u <registry username> -p <registry password> https://registry.immuta.com
Where are my credentials?

Visit https://download.immuta.com to view your Immuta Docker Registry credentials.

Now you can manually pull the required images to your Docker host:

docker pull registry.immuta.com/immuta/immuta-service:2020.3.6
docker pull registry.immuta.com/immuta/immuta-db:2020.3.6
docker pull registry.immuta.com/immuta/immuta-fingerprint:2020.3.6
docker pull registry.immuta.com/memcached:1.5-alpine
docker pull registry.immuta.com/nginx:1.13-alpine

The pulled images now need stored for transport as tarball files using docker save:

docker save registry.immuta.com/immuta/immuta-service:2020.3.6 -o immuta-service-2020.3.6.tar
docker save registry.immuta.com/immuta/immuta-db:2020.3.6 -o immuta-db-2020.3.6.tar
docker save registry.immuta.com/immuta/immuta-fingerprint:2020.3.6 -o immuta-fingerprint-2020.3.6.tar
docker save registry.immuta.com/memcached:1.5-alpine -o memcached-1-5-alpine.tar
docker save registry.immuta.com/nginx:1.13-alpine -o nginx-1-13-alpine.tar

Now transfer all of the .tar files to the destination system where Immuta will be deployed.

9.2 - Manually Load Pulled Images On Destination System

Regardless of the method used to acquire the images and transfer them onto the eventual Immuta host, the following docker load calls need applied to stage the images into that system's Docker environment:

docker load < immuta-service-2020.3.6.tar
docker load < immuta-db-2020.3.6.tar
docker load < immuta-fingerprint-2020.3.6.tar
docker load < memcached-1-5-alpine.tar
docker load < nginx-1-13-alpine.tar

10 - (Only for Internet-Connected Environments) Login to Immuta's Image Repository

Use your Docker login credentials to access the Immuta Docker Registry:

docker login -u <registry username> -p <registry password> https://registry.immuta.com
Where are my credentials?

Visit https://download.immuta.com to view your Immuta Docker Registry credentials.

11 - Create the Immuta Docker Network

From the IMMUTA_HOME directory, issue the following commands to create the Docker network the services will use to communicate and build the images.

cd "${IMMUTA_HOME}"
docker network create immuta

12 - Launch Containers with Docker-Compose

Finally, bring up all services with:

cd "${IMMUTA_HOME}"
docker-compose up -d

13 - Post-Install Activities

13.1 - Verify the Installation

After executing the docker-compose up -d 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 docker ps to be run every second until you press ctrl-C to stop it.

watch -n1 docker ps
Example Output
CONTAINER ID        IMAGE                                                    COMMAND                  CREATED             STATUS              PORTS                          NAMES
50c46006bc0d        registry.immuta.com/nginx:1.13-alpine                    "nginx -g 'daemon of…"   33 seconds ago      Up 32 seconds       80/tcp, 0.0.0.0:443->443/tcp   proxy
864ebddc0872        registry.immuta.com/immuta/immuta-service:2020.3.6       "/docker-entrypoint.…"   33 seconds ago      Up 32 seconds                                      service
e232d39bcda4        registry.immuta.com/memcached:1.5-alpine                 "docker-entrypoint.s…"   34 seconds ago      Up 32 seconds       11211/tcp                      immuta-memcached
e61d11d6ed5c        registry.immuta.com/immuta/immuta-fingerprint:2020.3.6   "immuta-fingerprint …"   34 seconds ago      Up 32 seconds                                      fingerprint
b61a23f7fc9d        registry.immuta.com/immuta/immuta-db:2020.3.6            "/docker-entrypoint.…"   34 seconds ago      Up 24 seconds       0.0.0.0:5432->5432/tcp         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.

13.2 - 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 commands from the $IMMUTA_HOME directory:

docker-compose down --volumes

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

13.3 - Configure Backups

See Single Node Docker Backups for more information.