Applications Setup

We run ACUITY system mostly in containerized form, and this article describes containerized ACUITY deployment. There may be differencies between images in use (depending on the configuration):

• VAHub image (required in any case)
• AdminUI image (required in any case)
• ACUITY Spring Cloud configuration server image (required in any non-development case)
• VASecurity image (required in any non-development case)
• Apache HTTP server image (required in any non-development case)
• PostgreSQL image (required if you plan to use containerized database rather than deployed externally; recommended)
• Flyway image (required if you plan to use containerized database rather than deployed externally; recommended)

Here is a scheme how all repositories fit together:

Github Actions build docker images from source code on change and store them in Github container registries. After that you use acuity-docker and acuity-deployment-scripts repository to install ACUITY either locally or in Cloud.

Deployment prerequisites

• a running host machine (OS may be Windows- or Unix-like, it only should be able to run Docker daemon; from now on, this instruction considers Linux Ubuntu distribution, but you may use another OS as well)
• an SSL certificate (if you don't have one, please see here; anyway, you need to have ca.crt and ca.key files)b
• if you plan to use some Microsoft Azure features (it may be user authentication with Azure AD, virtual machines, file storage in a storage account etc), you need an Azure account with corresponding privileges and configured items; please read this article to find out how to prepare them.

Deployment instruction

To quickly install application please refer to repository with deployment scripts .Below you are going to find some manual instructions which are already implemented in scripts

Docker and Docker Compose installation

For Windows:

• depending on your Windows installation you may need to install Hyper-V, WSL and/or WSL2 (see here for details)
• install and update some Linux distribution onto your Windows (e.g. Ubuntu 22.04.2 from Microsoft Store will be OK)
• install Docker with the sudo apt install docker.io -y command

For Ubuntu: Please use sh. script in repository

For other OS: please see Docker installation documentation.

Images import

You could create docker images using source code or pull them from ghcr.io as well. There are convenience scripts which start application for given environment by pulling images

ACUITY applications configuring

Before running ACUITY, you may want to configure it to change some details. There are several kinds of configs placed in different subdirectories of acuity-docker:

• Spring configuration files (acuity-spring-configs subdirectory); you may have an already prepared set of configs you deploy ACUITY applications onto some old-versioned ACUITY environment - if it's the case, just replace the content of acuity-spring-configs directory with these files (but pay attention to possible document structure changes). Otherwise, you may update existing config template files as you want. Full description can be found here. Most likely you'll need to update main work DB user password (see below), various Azure-related options (read this for details) and some external services links.
• Docker Compose environment variables config (env-configs subdirectory). For environments of ACUITY applications, these configs contain Java command line variables the application should run with. Default values are suitable for basic work, but in some cases you may want to raise heap size, e.g. There is also postres.env config that contains the newly created database superuser username and password, service database (non-business) name and port; you'll probably need to change at least the password.
• Flyway image config (images/flyway/flyway.conf) - here the DB superuser username and password should be updated if they were updated in postgres.env. Also, you'll probably need to update the password for main work DB user (flyway.placeholders.user.acuity.password) - that's the one that should be used in Spring configuration files.
• .env file (in the root acuity-docker directory) - it is the Docker Compose environment file. Here it contains names of Spring profiles that will be used when running ACUITY; by default, all is configured for a production environment. More details about profiles can be found inside this file comments and in Porfiles section

ACUITY installation

• copy acuity-docker project content to your user directory subdirectory acuity-docker; you need to copy following directories and files:
  • env-configs
  • images
  • acuity-spring-configs
  • .env (if you plan to use this ACUITY instance for production purposes) or .env.dev (for development, demo and similar purposes) - it's your .env file
  • docker-compose.yml (if you plan to use regular mode, e.g. take ACUITY applications Docker images from a remote registry or imported ones) or docker-compose_building-mode.yml (if you plan to use building mode, e.g. build automatically you images by yourself before use them) - it's your Docker Compose file
• get to ~/acuity-docker directory using our command line tool (from here, all paths will be relative to this directory, unless mentioned different)
• if you have a set of predefined config files for your environment (that may be Spring configs, or .env config(s), or <app>.env configs etc), place them to ~/acuity-docker directory or corresponding subdirectories; most likely, you'll be able just to copy all the content of your prepared config directory to the ~/acuity-docker dir.
• put your SSL certificate files to the ~/acuity-docker/ssl-certificates/certs/ (ca.crt file) and ~/acuity-docker/ssl-certificates/keys (ca.key file) directories.
• if you a going to use default-state configs, make sure they are suitable for your purposes, and update them if needed; in particular, pay attention to the content of the .env/.env.dev file (there are some comments inside that describe what can be changed and why).
• if you have a data dump in .sql or tar format to upload to the new database, place it to /images/postgres/data directory; otherwise, update /images/postgres/data/add_global_admin.sql file setting everywhere global admin email instead of [email protected].
• if you decided to use building mode, you need built artifacts of ACUITY applications; place them into /building-mode/builds directory under names: adminui.war, acuity-config-server.war, acuity-flyway.jar, vasecurity.war, vahub.war.
• run docker-compose -f <your_docker-compose_file>.yml --env-file <your_.env_file> --profile init_db up -d and wait acuity-flyway container to finish its work and exit (it will take a couple of minutes; to make sure it exited, run docker container ls --all; in the list of containers you should see something like acuity-flyway:8.0-lithium-SNAPSHOT in state Exited)
• run docker exec -i -t acuity-docker_postgres_1 /bin/bash
• if you want to apply a DB dump in .sql format generated by acuity-data-oracle-to-pg-transformer utility, run the following commands:

psql -d acuity_db -U dbadmin
\i /usr/root/data/<your_dump_file>.sql
\q

• if you want to apply a DB dump in .tar format, run the following commands:

psql -d acuity_db -U dbadmin
\i /usr/root/data/clear_data_tables.sql
\q
pg_restore --host=localhost --port=5432 --username=dbadmin --dbname=acuity_db --schema=acuity --data-only --disable-triggers --format=t /usr/root/data/<your_dump_file>.tar
psql -d acuity_db -U dbadmin
\i /usr/root/data/update_sequences.sql
\q

• if you want to just add the global administrator user (without it, you won't be able to operate clear ACUITY instance), run the following commands:

psql -d acuity_db -U dbadmin
\i /usr/root/data/add_global_admin.sql
\q

• run exit
• run docker-compose -f <your_docker-compose_file>.yml down
• run docker-compose -f <your_docker-compose_file>.yml --env-file <your_.env_file> --profile main up -d Wait for ACUITY applications to start (you may check it using logs in /logs directory). After that, they should be accessible through ports 80/443 (VAHub), 444 (VASecurity), 447 (AdminUI) on your environment (if you do it on your local machine, addresses will look like https://localhost:447).