Core | Essentials | DAM (4.37)

# Setting up a 4ALLPORTAL

A 4ALLPORTAL on customer infrastructure is installed and run with Docker. This documentation contains a step-by-step guide on how to set up and run a basic 4ALLPORTAL.

Please read our system requirements first.

Further Documentation

  • SSL for Localhost: If you want to access a local 4ALLPORTAL at https://localhost:8443, take a look at our guide here.
  • Docker: For general information about Docker, take a look at their documentation here (opens new window).

# Installation Requirements

Before setting up a new 4ALLPORTAL, make sure you have the following:

  1. Credentials to pull a docker image from our registry. You will receive the credentials from your 4ALLPORTAL contact.
  2. A Linux server. The 4ALLPORTAL does not support Docker on Windows. Running a productive 4ALLPORTAL on WSL is also not recommended.
  3. An installed Docker Engine. Docker directly supports the most common platforms (details from Docker docs (opens new window)).
  4. An x86_64/amd64 or arm64/aarch64 CPU

If you set up the 4ALLPORTAL using Red Hat Linux with SELinux and Podman, you can find a guide here.

# Set up a 4ALLPORTAL

Following this guide step-by-step installs a minimal 4ALLPORTAL. It should only be used for local development. It will not set up any kind of persistence, encryption, etc. For persistence information, take a look here.

Each step comes with an example. In it, a new Ubuntu 22.04 instance with 4 Cores, 12 GB of RAM, and 120 GB NVMe is created.

Terminal Commands

During installation, you will need different commands to interact with Docker. Look for a helpful list of commands here.

# 1. Operating System and Docker Setup

# ssh keys

Set up ssh keys to log into the remote machine. For simplicity, we use the root user in the following example:

  ssh root@123.123.123.123

# Update Operating System

Log in to the operating system and update it:

  apt update && apt upgrade -y
  systemctl reboot
  ssh root@123.123.123.123

# Install Docker

Install the required Docker packages (opens new window). This depends on your operating system and preferred way to set it up. For our Ubuntu example, install Docker from here (opens new window).

  apt install ca-certificates curl gnupg lsb-release
  mkdir -p /etc/apt/keyrings
  curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
  echo \
    "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
    $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  apt update && apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Test Docker

If everything went fine, it should display a message from Docker.

   docker run hello-world

# 2. 4ALLPORTAL Setup

# Create a Working Directory

You need a working directory to place and start your docker compose file from. It can be anywhere. For our example, we use "/4allportal".

  mkdir /4allportal && cd /4allportal

# Registry Access

Test the registry access. Enter the username and password you were given from your 4ALLPORTAL contact. It should say "Login Succeeded".

  docker login registry.4allportal.net

# Pull Docker Image

Pull a Docker image to check if everything works.

  docker pull registry.4allportal.net/4allportal:4.0.0

Image Version:

Add the latest version of the 4App Core Engine here, e.g. 4.0.0 (use a full version string like 4.0.0). Take a look at our Release Notes for the latest release.

# 3. Create a Docker Compose File

To configure and start your 4ALLPORTAL, you need to create a new file docker-compose.yml in your working directory. Based on this file, the Docker image is created.

Default Values and Further Configuration

Note that the created docker image has several default values, even if they are not part of a docker-compose.yml. You can change and/or extend the default by adding/altering the corresponding variables in the docker-compose.yml.

  • Look for the default values here
  • Look for a configuration guide here.
  • Look for additional parameters/environment variables here.

A basic docker-compose to start (without further configurations) looks like this:

version: '3'
services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: toor <-- just an example!

  4allportal:
    image: registry.4allportal.net/4allportal:4.0.0
    environment:
      DATABASE_PASSWORD: toor
      GENERAL_ADMIN_PASSWORD: example <-- just an example!
    ports:
      - 8181:8181

General Admin Password

For security reasons, variable GENERAL_ADMIN_PASSWORD must always be set manually in the docker-compose.yml. It is not automatically set in the default image. Note that this password can not be changed via the GUI.

Security Note

Without any modifications, this MySQL server would not be accessible. It is only accessible from the network implicitly defined by the docker-compose.yml.

# 4. Launch 4ALLPORTAL

After creating file /4allportal/docker-compose.yml, you can launch your first minimal 4ALLPORTAL installation with command docker compose up. After a short while, you should be able to log in at http://123.123.123.123:8181.

Log in with the default admin username administrator and the password you defined in the docker-compose.yml (in our example it is example).

Welcome to your first minimal 4ALLPORTAL installation!

Data Persistence

Note that in a minimal installation like this, added of edited data will only persist until the next docker down command. To achieve persistence, configure your docker-compose.yml like described here.

# Troubleshooting

In case you are having issues connecting to the WebUI, try using an ssh-port-forward: ssh root@123.123.123.123 -L8181:127.0.0.1:8181. The WebUI should be accessible using http://localhost:8181.

# Default Docker Image

The Docker image which is created, comes with default environment variables. These defaults automatically apply even if they are not written to a docker-compose.yml. Note that they fill the corresponding fields in the 4ALLPORTAL GUI each time the docker environment starts:

# General Settings

Variable Value Description
GENERAL_ADMIN_USER_NAME administrator general admin user name, used for initial setup and troubleshooting
GENERAL_ADMIN_EMAIL administrator@customermail.com email address of the system administrator account
GENERAL_DEFAULT_LANGUAGE en_US default language of the system
GENERAL_EXTERNAL_URL https://customer-4allportal-url.com full URL, at which the 4ALLPORTAL is accessible
DEBUG false (default)
true		 sets the JVM to debug mode with port 8001, and sets the logging level to DEBUG

External Database

Variable Value Description
DATABASE_HOST db (default)
URL		 domain or IP address to the external database
DATABASE_DATABASE_NAME 4allportal (default) name of the database
DATABASE_USER root valid user account name for the external database
DATABASE_PASSWORD toor valid user account password for the external database

# SMTP Mail Server

The 4ALLPORTAL requires a separate mail server. Its configuration is done in the environment section of your docker-compose.yml.

Variable Value Description
MAIL_ENABLED true (default)
false		 enables mail functionality
MAIL_HOST mail.customermail.cloud hostname or IP address of the mail server
MAIL_PORT 25 port of the mail server
MAIL_SYSTEM_FROM_EMAIL no-reply@customermail.cloud email address for emails from your system
MAIL_SYSTEM_FROM_NAME CUSTOMER NAME name that shows as sender of system emails
MAIL_SYSTEM_MAIL_SENDER no-reply@customermail.cloud email address which shows as sender instead of system email address
MAIL_USE_AUTHENTICATION false (default)
true		 activates the user authentication for the chosen mail server
MAIL_USE_REPLY_TO true (default)
false		 activates the reply-to email header and address

# ImageMagick

The 4ALLPORTAL uses ImageMagick to convert images and create previews. For more ImageMagick environment variables, take a look at their documentation (opens new window).

Variable Value Description
MAGICK_MEMORY_LIMIT 1GiB maximum amount of memory in bytes to allocate for the pixel cache from the heap
MAGICK_AREA_LIMIT 256MP maximum width * height of an image that can reside in the pixel cache memory
MAGICK_DISK_LIMIT 16GiB maximum amount of disk space in bytes permitted for use by the pixel cache
MAGICK_MAP_LIMIT 512MiB maximum amount of memory map in bytes to allocate for the pixel cache
MAGICK_HEIGHT_LIMIT 10MP maximum height of an image
MAGICK_WIDTH_LIMIT 10MP maximum width of an image

# Configuration

# Configure the Default Image

While the above installation is running just fine, there are some settings you might want to change or add. To do so, just add the variables you want to alter to the section services -> 4allportal -> environment in your docker-compose.yml and change their value as desired.

Reading Order

Please note the contents/variables of your docker-compose.yml

  • will always overwrite the default image with each reload/start of Docker (means you must alter the docker-compose to configure something other than our default, e.g. a mail server).
  • will always overwrite the settings made in the GUI of your 4ALLPORTAL (means you must alter the docker-compose if you want to use your GUI for configuration).

# Configure via the GUI

If you want to make configurations via your 4ALLPORTAL GUI (i.e. you wish the fields there to be empty), the corresponding variables in your docker-compose.yml must be set, but empty:

  • define the variables/fields you want to see empty in your GUI
  • find (or add) them in your docker-compose.yml environment
  • delete all entries made here
  • save your docker-compose.yml
  • start the container

Please note: All variables in your docker-compose.yml with no value will overwrite the default from the image and lead to an empty field in the GUI. If you make adjustments in your GUI now, they will not be overwritten with empty values again.

# Additional Environment Variables

If required, you may add variables that are not part of the default image. Some additional variables can be:

Variable Example/Values Description
GENERAL_ADMIN_FIRSTNAME John first name of the system administrator
GENERAL_ADMIN_LASTNAME Doe last name of the system administrator
DATABASE_TYPE mysql
mariadb
sqlserver		 type of the database
MAIL_USER no-reply@customermail.com user name of the mail server (only if MAIL_USE_AUTHENTICATION is active)
MAIL_PASSWORD t0p_s3cr3t user password of the mail server (only if MAIL_USE_AUTHENTICATION is active)
MAIL_SECURITY ssl
starttls		 encryption protocol used by the mail server
MAIL_SYSTEM_REPLY_TO_EMAIL no-reply@customermail.com email address that shows as sender instead of system email address (only if MAIL_USE_REPLY_TO is active)

# 3D Renderer Service Parameters

If you have the 3D renderer service installed, it will work with the following defaults:

  • Host: 3d-renderer
  • Port: 8190

If you deviate from these defaults (e.g. because the host is different for Kubernetes, or you have a different name for the 3D renderer service in your docker-compose.yml), you will need to adjust the parameters in the docker-compose.yml to avoid availability problems.
The configuration can be done using either JVM arguments or environment variables:

JVM arguments (highest priority) Environment Variable Default (lowest priority)
Host fourallportal.renderer.threed.host FOURALLPORTAL_RENDERER_THREED_HOST 3d-renderer
Port fourallportal.renderer.threed.port FOURALLPORTAL_RENDERER_THREED_PORT 8190

Examples:

  • -Dfourallportal.renderer.threed.host="3d-renderer-host" (JVM argument)
  • FOURALLPORTAL_RENDERER_THREED_HOST=3d-renderer-host (environment variable)

Please note: We generally support all Spring environment variables. For details, take a look here (opens new window).

# Persistence

When running the 4ALLPORTAL as in our basic configuration above, none of the data added or changed by your users would be persisted beyond a down command.
To persist files in docker, you can create volumes and map directories from inside the container to the host's file system.

# Database

version: '3'
services:
  db:
    image: mariadb
    environment:
      - MARIADB_ROOT_PASSWORD=toor <-- just an example
    volumes:
       - ./db:/var/lib/mysql

The above volume maps the directory /var/lib/mysql from inside the container to folder ./db (relative to the compose file).
If the compose file is located in /4allportal, like in our example, the MariaDB container will persist the database files on the host in /4allportal/db.

# 4ALLPORTAL

version: '3'
services:
  4allportal:
    image: registry.4allportal.net/4allportal:4.0.0
    environment:
      DATABASE_TYPE: mariadb
      GENERAL_ADMIN_PASSWORD: example
    ports:
      - 8181:8181
    volumes:
      - ./data:/4allportal/data
      - ./assets:/4allportal/assets

The above example creates persistence for the 4ALLPORTAL.

  • ./assets contains all original files of the file module
  • ./data contains installed apps, configurations, previews, and other metadata.

In this example, both directories are relative to your docker-compose.yml.

# Docker Guide

# Common Terminal Commands

There are several commands to interact with the 4ALLPORTAL Docker installation. Note that they assume your terminals’ current directory is the same as your docker-compose.yml file (in our example: .../4allportal).

Command Description
docker compose ps Inspects what is currently running.
docker compose up -d Tries to get the services online.
-d will detach the terminal and allows you to enter further commands. If you made changes after your last up, it will recreate the instances with your updated configurations.
docker compose down Stops and deletes the configured containers.
Please note: All data that is not explicitly mentioned as a volume will be deleted.
docker compose logs -f --tail=1000 4allportal Views the logs of your 4ALLPORTAL instance.
-f follows live log output
--tail limits the output to the last 1000 lines. Depending on your setup, a 4ALLPORTAL can output a lot of logs.
docker compose exec 4allportal bash Creates a shell inside the isolated 4ALLPORTAL environment.
Since the 4ALLPORTAL runs with the user 1000, who has very limited permissions, by default, it might be helpful to execute your bash with root for troubleshooting: docker compose exec -uroot 4allportal bash.
docker compose restart 4allportal Restart just the 4ALLPORTAL and not the database or other services.

More commandline details can be found in the Docker docs here (opens new window).

# Why Docker?

With version 4.0 we decided to reduce our multiple, partially high-maintenance deployment models (Linux, Windows, Docker, Cloud) to the two simplest ones. Beside our Cloud solution, Docker is the simplest and most adaptive way to install a 4ALLPORTAL on customer infrastructure. With Docker,

  • the deployment is extremely simplified, a direct installation on a system is not required
  • the 4ALLPORTAL runs in a container, isolated from a customer's infrastructure
  • all required dependencies are provided automatically, independent of a customer's package management
  • we use a known and standardized interface with a known Command Line Interface
  • an image is provided that just works, as long as the host can run Docker
  • the security enhances:

Additionally,

  • it can easily be run on any development machine using Docker-Desktop
  • the Linux distribution and version is less relevant
  • migration to a new machine is just a copy and paste
  • one Machine could run multiple versions
  • The installation folder can be anywhere and easily changed

# Red Hat Linux with SELinux and Podman

# 1. Install Podman

Install the required Podman packages. Make sure to you use the correct RHEL version.

sudo dnf install podman
sudo subscription-manager repos --enable codeready-builder-for-rhel-<release-num>-x86_64-rpms
sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-<release-num>.noarch.rpm
sudo dnf upgrade
sudo dnf install podman-compose

usermod --add-subuids 100000-150000 --add-subgids 100000-150000 johndoe
su - johndoe

# 2. Create docker-compose

Create file docker-compose.yml. Please note the following specifications:

  • Volume mounts need option :Z to allow access.
  • Filesystem UIDs are mapped to different IDs (check the Podman documentation here (opens new window)).
    • uid-1+100000
    • MariaDB uses UID 999 for files and the 4ALLPORTAL uses UID 1000, which translates to:
    • mkdir assets data && sudo chown -R 100999:100999 ./assets ./data

# 3. podman-compose

Use podman-compose instead of docker-compose. Podman's command line interface (CLI) is very similar to the docker-compose CLI:

podman-compose up -d

# 4. Allow External Access

Either add a reverse proxy-service like nginx to the compose file or install it on the host system. To allow external access, allow that port in the firewall:

sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload

← System Requirements →

Request missing documentation