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.
- Docker v1.12+
- Docker Compose
- OpenSSL
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,
- Initialize Installation
- Source Installation Environment
- Generate TLS Certificates
- Initialize Immuta Configuration
- Initialize Fingerprint Configuration
- Initialize Nginx Proxy Configuration
- Initialize Docker Configuration
- Enable Backups/Restoration Support
- Start Immuta
- 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 ofrepository:tag
.IMMUTA_DB_IMAGE
: The Docker image to use for the Immuta Query Engine. Should be in the format ofrepository:tag
.IMMUTA_FINGERPRINT_IMAGE
: The Docker image to use for the Immuta Fingerprint Service. Should be in the format ofrepository:tag
.IMMUTA_CACHE_IMAGE
: The Docker image to use for the cache service. Should be in the format ofrepository:tag
.IMMUTA_PROXY_IMAGE
: The Docker image to use for the proxy service. Should be in the format ofrepository: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.