Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
minLevel1
maxLevel2
outlinefalse
styledisc
typelist
printabletrue

Required Tools

  • Docker -
    Status
    colourRed
    titlerequired

    New server using dockerized images that allows Apliqo UX to be deployed across any platform, simplifying deployment and network management.

    Follow the installation instructions for your system:
    Windows | Linux | Mac

General Installation Instructions

1. Install Docker

  • For Mac and Windows: Install Docker Desktop and launch it.

  • For Linux: Ensure the Docker service is running. Verify by using:

Code Block
languagebash
sudo services docker status

2. Verify Docker Compose

  • Make sure Docker Compose is installed. Run:

Code Block
languagebash
docker compose version
  • This should return a version string similar to:

Code Block
languagebash
Docker Compose version {Version}

3. Log in to Docker

  • Use the provided Docker access token to log in:

Code Block
languagebash
docker login -u apliqocustomer -p {your-access-token}

4. Create a new docker network

  • Create a dedicated network for Apliqo UX:

Code Block
docker network create apliqo-core
  • Check if the network was created successfully:

Code Block
languagebash
docker network ls
  • You should see a result like:

Code Block
languagedocker
NETWORK ID     NAME                    DRIVER    SCOPE
06e4817f8b43   apliqo-core             bridge    local

5. Download and Configure Apliqo UX

  • Download the Apliqo UX installation package

  • In the root directory of the package, create a .env file (near.env.example.)

  • Copy the content from .env.example into the newly created .env file

  • Fill in all

    Status
    colourRed
    titleREQUIRED
    Environment Variables (details below)

6. Set the APLIQO_SERVER Environment Variable

  • In docker-compose.yml, set APLIQO_SERVER environment variable for apliqo-spa container.
    host.docker.internal - is a reference to your localhost inside the docker network.

  • By default APLIQO_SERVER value is http://host.docker.internal:${PORT_EXPOSE}

  • Change it only if apliqo-api is running on different machine.

7. Start the Apliqo UX Application

  • Run the following command to start the application:

Code Block
languagedocker
docker compose up -d

8. Verify That All Containers Are Running

  • Check that all containers are running properly by listing them:

Code Block
languagedocker
docker ps
  • You should see containers for:

    • apliqo-spa

    • apliqo-api

    • apliqo-mongo

    • apliqo-redis

  • To inspect logs for a specific container, run:

Code Block
languagedocker
docker logs ${docker_container_id}

9. Access Apliqo UX

  • Once the containers are running, navigate to the following URL in your browser: http://your-ip-address
    By default, the interface will be accessible from port 80.


Environment Variables

Info

The example file contains all the required variables. Please do not remove them, only update if necessary.

Variable

Description

Default Value

Required

Notes

JWT_SECRET

A secret string for encrypting access tokens. Ensure it is unique and secure.

None

Yes

There is no default value, set the arbitrary string or generate some random string.

SERVICE_USER_PASSWORD

Password for default system user which could be used on first install. After the backend service first starts, you will be able to login into the app via:

username: service-admin
password: SERVICE_USER_PASSWORD

None

Yes

Password for service user stores as a hashed string by bcryptjs. After user creation in Mongodb, you may remove this password from .env.

DB_HOST

MongoDB server's domain name or IP address.

apliqo-mongo

Yes

Inside the docker network, container names could be used as domain names to access the resource. If you are not using Docker for the MongoDB database, set the IP address or domain name as the value for this variable.

DB_USER

Username of a root user from which account would be created a connection to the MongoDB.

None

Yes

DB_PASSWORD

Password of a root user from which account would be created a connection to the MongoDB.

None

Yes

If you are using the default Apliqo UX setup. On first install DB_USER and DB_PASSWORD would be used to create a MongoDB user to access the database. This user would be stored in the admin database by default.

DB_CONNECTION_SCHEME

Description: MongoDB uses a connection variant.
There are 2 options:

mongodb - Standard Connection String Format. The standard format of the MongoDB connection URI is used to connect to a MongoDB deployment: standalone, replica set, or a sharded cluster.

mongodb+srv - DNS Seed List Connection Format. The +srv indicates to the client that the hostname that follows corresponds to a DNS SRV record.

mongodb

Yes

If you don't have your dedicated MongoDB server - use the default value.

REDIS_HOST

Hostname for the Redis database, used for caching and queues.

apliqo-redis

Yes

Inside the docker network, container names could be used as domain names to access the resource. If you are not using Docker for the Redis database, set an IP address or domain name as the value for this variable.

MONGO_DB_PORT_EXPOSE

Port on the machine where docker is running to access the MongoDB.
Set this variable to have the ability to access MongoDB from outside the docker network and to manage the DB by GUI tools (Mongo Compass, Studio 3T)

None

No

DB_NAME

Apliqo Content Store database name in MongoDB server.

apliqo-content-store

No

DB_PORT

MongoDB server's port.

27017

No

DB_AUTHSOURCE

Database inside MongoDB server which stores users and their permission in MongoDB.

admin

No

PORT

Port on which the backend server runs inside the Docker container.

4000

No

PORT_EXPOSE

Port on which the backend server is accessible from machine IP. Docker bridges PORT and PORT_EXPOSE.

4000

No

TM1_VERIFY_SSL

Variable to control the SSL verification for all TM1 API requests. Available values: 0 or 1
Set 1 if you want to enable the TM1 API SSL verification.
Set 0 if you want to disable the TM1 API SSL verification. (Could be used for TM1 with self-signed certificate)

0

No

Anchor
APLIQO_HOSTNAME
APLIQO_HOSTNAME

APLIQO_HOSTNAME

Variable which is used to create a redirect link for CAMPassport authentication.

Please make sure that the link doesn’t have slash ('/') and the end
https://apliqo-frontend-domain.com/ -

Status
colourRed
titlenot valid

https://apliqo-frontend-domain.com -
Status
colourGreen
titlevalid

None

No


Authentication

Apliqo supports flexible authentication configurations, allowing multiple options to work together. Below, we break down how to enable and configure various authentication methods step by step.

Info

Refer to the Synchronization article for a detailed setup demonstration.

» Authentication Overview

  1. Authentication Sources:
    Apliqo authenticates users through designated TM1 instances. Authentication is successful if at least one configured TM1 instance validates the credentials.

  2. Multiple Authentication Instances:
    You can configure multiple TM1 instances with different authentication methods. For example:

    • A specific instance may handle authentication for Apliqo.

    • Other instances may function purely as data models.

  3. Limitations:

    • If a report relies on a TM1 instance not set up as an authentication source, you won’t have an active session for that instance after logging in.

    • In such cases, the ‘Login to Instance’ dialog will appear, letting you log in manually. Both sessions will remain cached, even if you close the browser tab.


» Enabling CAMPassport Authentication

To set up CAMPassport Authentication, follow these steps:

  1. Add an Instance with CAMPassport authentication enabled.

  2. Turn on the Authentication Source switch for this instance.

  3. Open the instance’s Edit Dialog.

  4. Go to the CAMPassport tab on the right side.

  5. Check the CAM Server Link:

    • By default, Apliqo retrieves this link from the WWW-Authenticate header. Adjust as necessary.

  6. Configure the Environment:

    • Add APLQIO_HOSTNAME to the .env file as specified in the Environment Variables guide.

    • Apply the changes by running the following command:

Code Block
docker compose up -d --force-recreate apliqo-api
  1. Go to the Login Page and verify that the Login via SSO button appears.

image-20241222-092325.pngImage Modified

image-20241222-092531.pngImage Modified


» CAMNamespace

To set up CAMNamespace Authentication, follow these steps:

  1. Add an Instance with CAMNamespace authentication enabled.

  2. Open the instance’s Edit Dialog.

  3. Go to the CAMNamespace tab on the right side.

  4. Add your supported namespaces to the Client CAMNamespaces field:

    • Use comma-separated values for multiple namespaces.

  5. Turn on the Authentication Source switch for this instance.

  6. Go to the Login Page and verify that the namespace selection dropdown appears.

Info

Combining CAMNamespace and Basic Authentication:

  • leave the Namespace Select Dropdown empty. Basic authentication will then be used by default.

image-20241222-092440.pngImage Modified

image-20241222-092605.pngImage Modified


Troubleshooting

» MacOS with M1 chip peculiarities

If you're using a Mac with the M1 chip, some additional steps are required to ensure compatibility:

Rosetta

1. Install Rosetta

Code Block
softwareupdate --install-rosetta --agree-to-license

2. Enable Rosetta for Terminal:

  • Go to Finder > Applications > Terminal

  • Right-click ‘Terminal’ and select Get Info

  • Check the box "Open using Rosetta."

  • Open Terminal and verify it’s running under Rosetta by typing:

Code Block
arch
  • It should return i386 or x86_64

Docker

  • Ensure Docker Desktop is usingVirtioFS as a Virtualization framework in general settings for improved I/O performance for operations on bind mounts.

  • For containers that require the AMD architecture, add the following line to the container configuration:

Code Block
platform: linux/amd64