OnPrem Deployment (Docker)

Internal.io can be deployed as a Docker container running on your own cloud instance.

Quickstart

Directories

To ensure that your data is persisted between deployments, Internal makes use of Docker volumes.   Internal uses one storage volume mounted to the data filesystem path (/srv/internalio/data).

Environment

The on premise deployment of Internal requires several environment variables to be configured prior to running. These can be saved to an env file to be used by Docker directly or passed through as individual environment variables. In the examples below, we'll assume the use of an env file.

# License for Internal OnPrem
# Contact Internal for a trial https://internal.io/contact
INTERNALIO_LICENSE_KEY=eyJzaWduYXR1c...

# Secret Keys
# This key is used for managing sessions and encrypting audit log data.
# Set to a secure random 50 character string using the following shell command:
#
# openssl rand -base64 40 | tr -d /=+ | cut -c -50
INTERNALIO_SECRET_KEY=fj-afK...

# This key is used to encrypt datasource credentials.
# Set to a secure random 32 byte hex string using the following shell command:
#
# openssl rand -hex 32
INTERNALIO_CONNECTOR_SECRET_KEY=a5cb2185...

# Primary domain where the Internal deployment will be accessible
INTERNALIO_DOMAIN=example.com
# Base URI used for email invites, redirects, etc
INTERNALIO_BASE_URI=http://example.com:7080

# (optional) Database Settings
# Allows external databases to be used for storing metadata and credentials.
# By default, Internal OnPrem  will use an in-container PostgreSQL database
# and store the data within the data docker volume.
# Connection URIs must follow the PostgreSQL connection URI standard
# https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING

# The database where user credentials and Internal OnPrem metadata will be stored
# INTERNALIO_API_DATABASE_URI=postgres://postgres@172.17.0.1:5432/api
# The database where datasource credentials will be stored.
# INTERNALIO_CONNECTOR_DATABASE_URI=postgres://postgres@172.17.0.1:5432/connector

# SMTP settings for delivering mail
# This is the from email address for all emails to be sent by Internal
INTERNALIO_FROM_EMAIL_ADDRESS=Internal OnPrem 
# The smtp mail server host to send emails from
INTERNALIO_EMAIL_HOST=smtp.example.com
# The smtp mail server port
INTERNALIO_EMAIL_PORT=587
# The smtp mail server user to connect as
INTERNALIO_EMAIL_HOST_USER=example
# The smtp mail server password to connect with
INTERNALIO_EMAIL_HOST_PASSWORD=password
# If your mail server requires the use of TLS, uncomment and set to true.
# INTERNALIO_EMAIL_USE_TLS=true

# Enable Insecure Cookies
# Allows cookies to be sent with http requests to the server.
# This should *not* be enabled for production deployments, but is necessary
# to allow logins until SSL (HTTPS) is enabled.
INTERNALIO_INSECURE_COOKIES=true

# Google Client Secrets
# Used to enabled Google OAuth flows on Internal OnPrem
# INTERNALIO_GOOGLE_CLIENT_ID=client_id
# INTERNALIO_GOOGLE_CLIENT_SECRET=client_secret

‍

‍

Be sure to securely store and backup the INTERNALIO_SECRET_KEY and INTERNALIO_CONNECTOR_SECRET_KEY environment variables. Losing either one of these keys will result in inaccessible audit log data or data sources.

Deployment (with bundled PostgreSQL databases)

The on premise version of Internal can be deployed using Docker:

docker run \
--rm \
--detach \
--env-file /path/to/env/file \
--publish 7080:7080 \
--volume /path/to/internal/data:/srv/internalio/data \
internalio/onprem:2.52.0

‍

Deployment (with external PostgreSQL databases)

Ensure that the INTERNALIO_API_DATABASE_URI ****and ****INTERNALIO_CONNECTOR_DATABASE_URI environment variables are set with valid PostgreSQL connection URIs. Once these values are set, you may omit the data volume from the above example to run Internal:

docker run \
--rm \
--detach \
--env-file /path/to/env/file \
--publish 7080:7080 \
internalio/onprem:2.52.0

‍

Double check that you are running the latest version of the OnPrem deployment. As seen in the command above, internalio/onprem:2.52.0 is the latest version as of 02/06/2023.

After a few moments, the container should be running with the host port 7080 mapped to the container. You can verify this by running:

$ docker ps |grep internalio 

d78fc73cdfc5 internalio/onprem:2.52.0 "/usr/bin/tini -- /u…" 2 minutes ago Up 2 minutes onprem

‍

You may now navigate to the hostname or IP address on port 7080 (e.g. http://127.0.0.1:7080). Create an account, then you'll be guided through connecting your first datasources.

Horizontal Scaling

When configuring your production deployment for Internal OnPrem, it is a good idea to run multiple containers for availability reasons.  OnPrem containers are stateless and can be scaled to run as many instances as needed.  In this setup, you will need to configure each container to run against an external PostgreSQL database.  Follow the directions in the section directly above this one (Deployment (with external PostgreSQL database)) and be sure to point each of the subsequent containers at the same external DB instance.

Deployment (on Heroku)

For Heroku deployment and container upgrade instructions, see the README.md in our heroku-example repository.

HTTPS Configuration with Custom Certificates

SSL configuration with custom certificates can be accomplished using docker compose to run a reverse proxy container that communicates with the on internalio/onprem container.  Here is an example configuration that uses nginx as the reverse proxy (other proxy services such as HAProxy will also work).

First create your docker-compose.yml file:

version: "3.9"

services:

  nginx-proxy:
    image: nginx:latest
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./nginx:/etc/nginx/conf.d
      - ./certs:/etc/nginx/certs
    links:
      - internalio

  internalio:
    image: internalio/onprem:2.52.0
    env_file: ./env
    ports:
      - '7080:7080'
    volumes:
      - ./data-2.7.1:/srv/internalio/data

Copy your certificate and key into in the ./certs directory:

cp mycert.pem ./certs
cp mykey.pem ./certs

Create an nginx config in your ./nginx directory (let's call it nginx.conf ).

server {
    listen 80;
    
    # Replace example.com with your domain.
    server_name example.com;
    
    location / {
        return 301 https://$host$request_uri;
    }
}
server {
    listen 443 ssl;
    
    # Replace example.com with your domain.
    server_name example.com;
    
    # This should be your custom cert that you placed in the ./certs directory.    				    
    ssl_certificate     /etc/nginx/certs/mycert.pem;
    
    # This should be your custom key that you placed in the ./certs directory.    				
    ssl_certificate_key /etc/nginx/certs/mykey.pem;
    
    location / {
        proxy_set_header        Host $http_host;
        proxy_set_header        X-Real-IP $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Proto $scheme;
        
        # 7080 is the default port of the internalio/onprem container.
        proxy_pass http://internalio:7080;
    }
}

‍

Run docker compose:

docker compose up

‍

You should now be able to access your on premise instance at https://example.com (replace example.com with your domain) in your browser.

Upgrading Internal

To update Internal, simply pull the latest docker image and re-deploy using the existing environment file and config/data volumes.

‍

Using Localhost Proxies to an External Address within a Container

Run the container with the following flag to allow Localhost proxies to communicate with external addresses from inside of a container which is running Internal.

“--http_proxy=false”

Exporting OnPrem Internal Postgres DB

One can export the Postgres DB that Internal uses for its application for sharing, deployment, or backups by issuing the following commands from CLI via a logged-in user on the server on which OnPrem Internal is running:

# For the main app DB:
docker exec -it CONTAINER_ID_HERE pg_dump -U postgres console > console_backup.sql

# For the data source connector DB:
docker exec -it CONTAINER_ID_HERE pg_dump -U postgres connector > connector_backup.sql

‍

Windows Server 2019 Docker for Linux containers installation

Special consideration must be paid to installing our on-prem solution to Windows Machines, in particular Windows Server. Below, you'll find the needed steps to get your solution installed and running.

NOTE: If you are using Azure virtual machines, you will need to select a virtual machine that supports running nested virtualization (Dv3 and Ev3 sizes). Additionally, the server must be able to run Hyper-V.

1. Install Hyper-V       

2. Install Docker

•  There are many guides for installing docker online, but this is the one that actually works.

          NOTE: Make sure you do linuxkit/lcow part or else you will get an error indicating that

                       "C:\Program Files\Linux Containers\kernel.exe" is missing.

3. Install the internalio docker image:

docker run --rm --env-file ./env.txt --publish 7080:7080 --volume ./data:/srv/internalio/data --name internalio-test internalio/onprem:2.52.0

4. If you get "Permission Denied" errors while initializing postgres, change the docker data-root directory by adding a key and value for dataroot in "c:\ProgramData\docker\config\daemon.json":

{
  // ...other settings
  "data-root": "c:\\data"
}

• Restart the docker service.
• Rerun the internalio docker container.

Authorization via OAuth

Internal offers custom OAuth via Okta, Google, and Auth0, and is compatible with any other identity provider which uses OAuth and OAuth2. The following are those authorization tools for which we have documentation:

• Okta documentation
• Google documentation
• Auth0 documentation

‍