Start as Docker image

If you want to limit yourself to the in-app configuration (no plug-in development for the engine), the TopLogic engine can be started in a standard configuration using a preconfigured Docker image. This allows the full potential of in-app development to be exploited. This approach is a good alternative to creating your own TopLogic module or a server installation via Debian or Cloud-Init, especially for testing and learning purposes.

The prerequisite for this is the installation of a Podman or Docker container environment, which are available for all common operating systems.

Install Docker or Podman

Windows

Prerequisites

Windows 10, version 2004 and higher (build 19041 and higher), or Windows 11

Docker for Windows is problematic to use via the command line and the native Linux application of Docker cannot be used under WSL.

We therefore recommend using Podman under Windows.

Installing Podman

However, the easiest way is probably the one described below:

1. Download and install the Podman CLI (Command Line Interface) and, if desired, additionally the Podman Desktop GUI (Graphical User Interface) from podman.io.
2. Open Windows Terminal (installable from the Microsoft Store), Powershell or CMD.
3. First a Podman instance is initialized.

   podman machine init

4. Once the init process is complete, this instance must be started.

   podman machine start

Now you can start setting up the container.

Linux

Requirements

The requirements for installing Docker on Linux can be found in the table at this link: https://docs.docker.com/engine/install/#server

Installation

• Podman: https://podman.io/docs/installation
• Docker: https://docs.docker.com/engine/install/

Docker

When using Docker under Linux, either the command sudo must be prefixed each time the docker command is called, or the current user must be added to the group docker. To add the user to the docker group, the following commands must be executed and then the PC restarted:

sudo groupadd docker
sudo usermod -aG docker $USER

Set up TopLogic Container

Logging on to the TopLogic registry

To gain access to the TopLogic images, you must first log in to the TopLogic registry. Depending on the container environment, use the appropriate command:

Podman

podman login docker.top-logic.com -u guest -p guest

Docker

docker login docker.top-logic.com -u guest -p guest

Downloading and updating an image

Downloading and updating an image is identical with the following command.

Podman

podman pull docker.top-logic.com/tl-process:latest

Docker

docker pull docker.top-logic.com/tl-process:latest

Start TopLogic container

Once the preparations have been completed, the engine can be started. Use the appropriate command depending on the container environment:

Podman

podman run -tdi --name toplogic -etl_initial_password=my-password -p 8080:8080 -v toplogic:/tl docker.top-logic.com/tl-process:latest

Docker

docker run -tdi --name toplogic -etl_initial_password=my-password -p 8080:8080 -v toplogic:/tl docker.top-logic.com/tl-process:latest

The parameters have the following meaning:

• -etl_initial_password=my-password Defines the initial password (up to version 7.6.0 this was fixed root1234). The password does not change during an update (without resetting the database), even if this parameter is specified.
• -p 8080:8080 defines the port via which the web interface of the engine can be reached. The option specifies that the port 8080, on which the application starts internally in the Docker image, is forwarded to the port 8080 of the host computer. For example, if you want to access the engine via the official HTTP port 80, you must specify the option -p 80:8080 instead.
• -v toplogic:/tl specifies that the Docker volume "toplogic" is "mounted" in the path /tl in the Docker container. This means that all files that the engine creates in the Docker container at /tl are stored in the volume toplogic. If this parameter is omitted, the engine saves the transaction data directly in the Docker container. After updating the container, all data would then be deleted.
• The latest version (latest) of tl-process is started from the TopLogic Docker registry docker.top-logic.com. Here, "tl-process" stands for the standard configuration of the engine with process support.

Reading log files

To check whether the container was started correctly, you can view the log files of the start process with the following command (use the appropriate command depending on the container environment):

Podman

podman logs -f toplogic

Docker

docker logs -f toplogic

If everything has worked, the output will contain the following content, among other things:

Module system started successfully

    Application: tl-process     7.6.0 (2022-11-02T14:31:43Z)
  Knowledgebase: Default
User management: dbSecurity
 Authentication: dbSecurity

             OS: Linux V5.15.0-79-generic (amd64)
           User: root

           Java:
        Version: 11.0.16+8 (OpenJDK 64-Bit Server VM)
        Runtime: OpenJDK Runtime Environment
         Vendor: Oracle Corporation
        Classes: V55.0
           Info: mixed mode, sharing
           Home: /usr/local/openjdk-11
       Web Path: /usr/local/tomcat/webapps/ROOT
***** up and running (12:54:28 07.09.2023) *****

Login to the TopLogic app

Once the startup process is complete, you can open the URL http://localhost:8080/ in your browser and see the TopLogic login screen. The first login is with the administrator account "root" with the initial password (see above). This password should be changed in the personal settings immediately after the first login.

At this point you can start the TopLogic tutorial.

Shutting down the application

Depending on the container environment, use the appropriate command:

Podman

podman stop toplogic

Docker

docker stop toplogic

Deleting the container

Depending on the container environment, use the appropriate command.

Podman

podman rm toplogic

Docker

docker rm toplogic

Deleting the database (volume)

Podman

podman rm volume toplogic

docker rm volume toplogic