Installation

Required Tools

Docker - REQUIRED
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

MongoCompass - NICE TO HAVE
While not required, this GUI tool can be useful for querying and managing MongoDB data visually.

https://www.mongodb.com/docs/compass/master/install/

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:

sudo services docker status

2. Verify Docker Compose

Make sure Docker Compose is installed. Run:

docker compose version

This should return a version string similar to:

Docker Compose version {Version}

3. Log in to Docker

Use the provided Docker access token to log in:

docker login -u apliqocustomer -p {your-access-token}

4. Create a new docker network

Create a dedicated network for Apliqo UX:

docker network create apliqo-core

Check if the network was created successfully:

docker network ls

You should see a result like:

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 REQUIRED 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:

docker compose up -d

8. Verify That All Containers Are Running

Check that all containers are running properly by listing them:

docker ps

You should see containers for:
- apliqo-spa
- apliqo-api
- apliqo-mongo
- apliqo-redis
To inspect logs for a specific container, run:

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

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
`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/ - Not Valid https://apliqo-frontend-domain.com - Valid	None	No

Authentication

You may want to enable multiple authentication options to work together.

Apliqo allows authentication only when at least one of the TM1 instances designated as an authentication source successfully validates the credentials.

It is possible to configure multiple instances with various authentication methods. For example, if you want a specific instance to handle authentication for Apliqo, while other instances serve only as data models, you need to enable the authentication source setting only for the designated 'authentication' instance.

However, if certain reports rely on a TM1 instance that is not configured as an authentication source, you will not have an active TM1 session for that instance after logging in.

In such cases, the 'Login to Instance' dialog will appear, allowing you to log in to that instance. Even if you close the Apliqo tab in your browser, both sessions will remain cached. When you return, you will be able to access the reports without logging in again.

CAMPassport

To enable CAMPassport authentication you need:

Add instance with CAMPassport authentication enabled
Turn on the auth source switch button for this instance
Open instance “Edit Dialog”
Go to CAMPassport tab on a right side
Check the link to your CAM Server
By default, this link Apliqo take from WWW-Authenticate header
Add APLQIO_HOSTNAME into the .env file follow the guide
After editting .env use
docker compose up -d --force-recreate apliqo-api
This command restart the server with new environment variables changes
Go to login page and “Login via SSO“ but should appear

CAMNamespace

To enable CAMNamespace authentication you need:

Add instance with CAMNamespace authentication enabled
Open instance “Edit Dialog”
Go to CAMNamespace tab on a right side
Add your supported namespaces into text field “Client CAMNamespaces“
Use coma separation for multiple namespaces.
Turn on the auth source switch button for this instance
Go to login page, namespaces select dropdown should appear

In case, you want to have Basic and CAMNamespace authentication options available together, leave Namespace select dropdown empty (in this case, Basic authentication will be used by default)

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

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:

arch

It should return i386 or x86_64

Docker

Ensure Docker Desktop is using VirtioFS 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:

platform: linux/amd64