Copy of Apliqo UX - Installation Guide

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:

https://docs.docker.com/desktop/install/windows-install/ https://docs.docker.com/desktop/install/linux-install/ https://docs.docker.com/desktop/install/mac-install/

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.
For Linux it is 172.17.0.1
By default APLIQO_SERVER value is http://host.docker.internal:${PORT_EXPOSE}

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

» Application Ports

PORT
Description: port on which the backend server is running inside the docker container
Default value: 4000

PORT_EXPOSE
Description: port on which the backend server is accessible from machine IP.
Docker creates a bridge between PORT and PORT_EXPOSE.
Default value: 4000

» Security

JWT_SECRET REQUIRED
Description: A secret string that is used to encrypt the access token.
There is no default value, set the arbitrary string or generate some random string.

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

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

» Mango DB Configuration

DB_NAME
Description: Apliqo Content Store database name in MongoDB server.
Default Value: apliqo-content-store

DB_HOST
Description: domain name or IP address of mongodb server
Default Value: apliqo-mongo

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

DB_PORT
Description: MongoDB server port.
Default Value: 27017

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

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

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

If you are using 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 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.

Default Value: mongodb

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

DB_AUTHSOURCE

Description: Database inside MongoDB server which stores users and their permission in MongoDB.
Default Value: admin

» Redis Configuration

REDIS_HOST
Description: Redis database hostname. Used for caching and queues.
Default Value: apliqo-redis

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

»TM1 API

TM1_VERIFY_SSL

Description: 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 cerificate)

Default Value: 0

Troubleshooting

» MacOS with M1 chip peculiarities

The architecture of the M1 chip is not fully compatible with the architecture of containers that are used in docker. In this case, you need to install a couple of things to make everything work correctly for your environment.

Rosetta

First of all, you need to install Rosetta and turn the terminal into rosetta mode.

softwareupdate --install-rosetta --agree-to-license

It seems to be a good idea to run your entire Terminal in Rosetta:

Go to Finder > Applications and find your Terminal
Right-Click "Terminal" > Get Info > Enable Open using Rosetta
Click to Open the Terminal, type arch to verify it says i386 or x86_64 now.

Docker

For Docker Desktop in general settings make sure that you are using VirtioFS as a Virtualization framework. It brings improved I/O performance for operations on bind mounts.

For containers configuration that requires amd architecture add the following line to containers config:

platform: linux/amd64