Skip to content

You are viewing documentation for Immuta version 2.8.

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.

Installation 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, we provide instructions on generating a self-signed CA certificate and issuing certificates for all internal connections between Immuta services. By default these certificates 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.

Instructions are in-line below.

Step 1: Initialize Installation

Create Installation Directory

To begin the installation, create a directory then set it as your working directory. Immuta recommends the directory /opt/immuta, but this is not a requirement.

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

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.

  • 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.

General Configuration and Passwords

Create an immuta-env file using the script below. This file will create, simplify, and increase the repeatability of this installation process.

cat > immuta-env <<EOF
export IMMUTA_HOME=$(pwd)
export IMMUTA_HOSTNAME=immuta.my-company.com
export IMMUTA_VERSION=2.8.3
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)
EOF
chmod 600 immuta-env

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

Warning

You must set the IMMUTA_HOSTNAME variable or you may have issues with the installation process.

Configure Container Memory Limits

You can set a memory limit profile that corresponds to the amount of memory available on the installation node. Although not required, it is highly recommended that you set memory limits for a single node deployment. Otherwise, you may encounter performance issues. The recommended memory profile configurations are listed below.

cat >> immuta-env <<EOF
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

cat >> immuta-env <<EOF
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

cat >> immuta-env <<EOF
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

cat >> immuta-env <<EOF
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

Step 2: Load Installation Environment

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

source ./immuta-env
Tip

You may verify your environment at any time by running:

env | grep 'IMMUTA_'

Step 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.

Step 3(a): 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
)

Step 3(b): (OPTIONAL) Use Own Certificates for External Communication

Warning

Only follow the instructions below if you have valid TLS certificates for IMMUTA_HOSTNAME.

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

Step 3(c): 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}
if [ ! -f "${SVC_DIR}/immuta.crt" ]; then
    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
fi

# service cert (internal/generated only, behind proxy)
SVC_DIR="${TLS_BASE_DIR}/service"
mkdir -p ${SVC_DIR}
if [ ! -f "${SVC_DIR}/immuta.crt" ]; then
    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
fi

# database cert (external)
SVC_DIR="${TLS_BASE_DIR}/db"
mkdir -p ${SVC_DIR}
if [ ! -f "${SVC_DIR}/immuta.crt" ]; then
    cp -af "${EXT_DIR}/immuta-ca.crt" "${SVC_DIR}/immuta-ca.crt"
    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
fi

# proxy cert (external)
SVC_DIR="${TLS_BASE_DIR}/proxy"
mkdir -p ${SVC_DIR}
if [ ! -f "${SVC_DIR}/immuta.crt" ]; then
    cp -af "${EXT_DIR}/immuta-ca.crt" "${SVC_DIR}/immuta-ca.crt"
    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
fi

Step 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"

Step 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"

Step 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"

Step 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 true to enable database backup restoration
    - DB_RESTORE_ENABLED=false
    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
    # Uncomment the line below to enable database backup restoration
    # - ./volumes/db/restore:/var/lib/immuta/postgresql/restore
    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
    - ${IMMUTA_HOME}/tls/proxy/immuta-ca.crt:/etc/nginx/ca.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"

Step 8: Finalize Installation

Enable Backup Restoration

If you are restoring from a backup from a previous deployment, follow the instructions below to enable database restoration.

First, create the restore directory to store your backup.

mkdir -p "${IMMUTA_HOME}/volumes/db/restore"

Next, copy your backup into the directory and set proper backup permissions.

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

Then, modify the db service in your docker-compose file to set the environment variable DB_RESTORE_ENABLED=true and uncomment the volume declaration for the db/restore directory.

The resulting db service should be similar to the configuration below:

services:
  db:
    # ...
    environment:
    # ...
    # Set to true to enable database backup restoration
    - DB_RESTORE_ENABLED=true
    volumes:
    # ...
    # Uncomment the line below to enable database backup restoration
    - ./volumes/db/restore:/var/lib/immuta/postgresql/restore
    networks:
      immuta:
        aliases:
        - db.immuta

Step 9: Start Immuta

(OPTIONAL) Load Required Images

Pulling from Docker Registry

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

If your installation instance has external network connectivity, you can login in to the Immuta Docker Registry directly:

docker login -u <registry username> -p <registry password> https://registry.immuta.com

If you are using the registry, the images will automatically be pulled the first time that you run docker-compose up -d.

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

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

Manually Loading Images

If you are performing the installation on an air-gapped instance, you must first pull the images from a network-connected machine then install on the destination host with docker load:

docker load < immuta-db-${IMMUTA_VERSION//./-}.tar
docker load < immuta-fingerprint-${IMMUTA_VERSION//./-}.tar
docker load < immuta-service-${IMMUTA_VERSION//./-}.tar
docker load < memcached-1-5-alpine.tar
docker load < nginx-1-13-alpine.tar

Launch Containers with Docker-Compose

First make sure we are in the IMMUTA_HOME directory, create the Docker network the services will use to communicate and build the images.

cd "${IMMUTA_HOME}"
docker network create immuta

Finally, bring up all services with:

docker-compose up -d

Verifying Install

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.

Resetting Install

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.

Backups

See Single Node Docker Backups for more information.