Linux

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

Ensure Docker is running by checking its status:

docker compose version

This should return a version string similar to:

Docker Compose version {Version}

3. Download the ApliqoUX Installation Package

To install Apliqo UX, you will need the installation package.

📩 If you don’t have the download link yet, please contact our team.

4. Run the Apliqo UX installation using the CLI:

Once you have the package, run the Apliqo UX installation using the CLI:

sh ./apliqoux.sh install

⚠️ On the first start, you may encounter an error asking for a Docker Access Token. Enter your access token when prompted.
[ERROR] You don't have an access to Apliqo UX repositories. Please set your Docker Access Token.

5. Access Apliqo UX

Once installation is complete, open your browser and navigate to: http://your-ip-address
By default, Apliqo UX runs on port 80.

Useful Commands & Troubleshooting

» Check System Readiness

Run a validation check to ensure all configurations are correct:

sh ./apliqoux.sh validate

» List Available Containers

To check which containers are running:

sh ./apliqoux.sh containers

services:
  apliqo-mongo:
    container_name: apliqo-mongo
  apliqo-spa:
    container_name: apliqo-spa
  apliqo-api:
    container_name: apliqo-api
  apliqo-redis:
    container_name: apliqo-redis

» Debugging & Logs

To check logs for a specific container:

sh ./apliqoux.sh service logs {container_name}

To check overall system performance (CPU, memory, running containers, etc.):

sh ./apliqoux.sh service status

» Managing Environment Variables

Set a new environment variable:

sh ./apliqoux.sh env-manager set <VARIABLE> <VALUE>

Example (changing PORT_EXPOSE to 4003):

sh ./apliqoux.sh env-manager set PORT_EXPOSE 4003

To apply changes, restart the relevant services:

sh ./apliqoux.sh service restart apliqo-api

sh ./apliqoux.sh service restart apliqo-spa

Common Installation Errors & Fixes

...

services:
...

  apliqo-api:
    container_name: apliqo-api
    image: apliqo/api:latest
    ...
    volumes:
      - ./.env:/usr/src/app/.env
      - ./license:/usr/src/app/license

Migrating to Apliqo UX CLI

If you have an existing running environment and want to switch to Apliqo UX CLI:

1. Download Apliqo UX CLI

📩 If you don’t have the ApliqoUX CLI download link yet, please contact our team.

• unzip it in the same directory as docker-compose.yml.

2. Stop all containers:

docker compose down

3. Run a validation check:

sh ./apliqoux.sh validate

✅ You should see: [SUCCESS] Validation Complete

4. Install Apliqo UX CLI:

sh ./apliqoux.sh install 

5. Final Step

• Open http://your-ip-address in your browser.

Final Notes

Always validate your setup with:

sh ./apliqoux.sh validate 

If you run into issues, check logs using:

sh ./apliqoux.sh service logs {container_name} 

Restart services after making changes:

sh ./apliqoux.sh service restart {service_name}

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.

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

docker compose up -d --force-recreate apliqo-api

7. Go to the Login Page and verify that the Login via SSO button appears.

» CAMNamespace

To set up CAMNamespace Authentication, follow these steps:

1. Add an Instance with CAMNamespace authentication enabled.

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

3. Open the instance’s Edit Dialog.

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

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

   • Use comma-separated values for multiple namespaces.

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

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