Overview
This chapter is an introduction into configuration. It describes how the configuration is designed, where it is stored and how it’s changed. We’ll show how to change the most important things, the rest is described throughout this documentation.
First, it’s important to mention that ALTWORX and all it’s services are running in Docker. It’s important because it directly influences some details of how the configuration works. I encourage to read up on Docker, being aware of how it works and being able to interact with it makes things easier.
TODO translate to english
Configuration of ALTWORX is done via a combination of ENV variables and configuration files. Here, it is important to be aware of the Docker layer, since it isolates programs running inside from the host computer. You have to explicitly say you want to allow Docker container to read an ENV variable or a file from the host. Anyway, don’t be too scared. We offer a standard configuration entity, that helps you with the process of configuration - deployment.
Deployment is a directory with a given structure, which contains everything that is necessary to run ALTWORX. It usually contains the following.
- place to put your configuration - with Docker services pre-configured, so you don’t have to worry about Docker too much. Every piece of configuration has its own place and is read by the relevant services.
- Docker-Compose artefacts - machine instructions on how to spin up ALTWORX including all necessary infrastructure. In case of offline installation this also contains all necessary binaries, which are usually downloaded from the internet. Also included is the Scenario artefact - binaries of all Scenarios you have access to.
- installation script - script used to install/upgrade ALTWORX and to apply configuration.
Usually, the deployment is also a GIT repository. This is not enforced at the moment, but it is very useful. First of all, it provides a changelog of the configuration. You can see who and when changed what. The upstream is the single source of truth and GIT provides powerful collaboration tools. Additionally, it allows you to build a simple CD pipeline, and allow people to change configuration without having physical access to the host. While the workflow is very much voluntary, it greatly simplifies the process. E.g. we use it ourselves in the following way.
- Deployment is located in a private hosted GIT repository (something like Github or Bitbucket). We have total control over who has read or write permissions. It should never be public, since it usually contains a lot of sensitive information.
- When somebody wants to change something, he clones the repository on his own computer, and creates a pull request.
- Pull request gets peer-reviewed by others.
- Automated tests verify the pull request doesn’t break anything. You can design many different tests for almost anything.
- When it’s ready, the pull request is merged into the main branch.
- The updated deployment is installed on the machine by an automated job (we use Jenkins) or manually.
This workflow is suited for our needs, you can cherry-pick whatever you need or design your own workflow from scratch. You can build fully automated CD pipeline or stick to doing things manually - it’s your call.
With ALTWORX you also get empty deployment - a starting point for your deployments. It contains all of the above that is necessary for online installation. You can just fork/copy it and change what’s necessary.
TODO where do they get it? should it be mentioned here?
A deployment usually corresponds to a project. Since a project can have multiple instances the deployment also carries multiple independent configurations. We call them environments, as it’s most often used for different environments of the same project. We highly advise to have multiple environments for each project, it’s best to have at least the following environments.
TODO based on cargo, is this OK?
dev- testing environment, for testing any change without the fear of breaking something somebody relies upon. It should be fine to break it at any time without any notice.qa- stable development environment. It should be relatively stable, since people outside of your team can rely on it. Usually QA is used for testing Scenarios, or other things that should be tested by other people, to make sure it’s working as expected. Some people may rely on this env, so you should be careful, but breaking it without notice shouldn’t cause any major harm.prod- production environment. Should be as stable as possible, breaking it without notice can cause serious issues for the client. This is the only environment that should be really relied upon.
Having multiple environments helps you build trust in the system, since you can test your changes multiple times before applying them to the production server. If you make a mistake you usually find it soon without causing any harm.
First part of the configuration belongs to the deployment itself - details like where the
configuration is located and what versions of ALTWORX components should be used. It is specified in
the form of ENV variables stored in the file ENV/.env, where ENV represents the respective
environment. The file would look something like this 1.
# set to the altworx version you want to use
ALTWORX_VERSION=21.5.0
# set the UI versions to be used
UI_VERSION=latest
# set paths to this deployment and to persistent data directory
IN_MACHINE_CONFIGS=/opt/altworx/deployment/current-settings
IN_MACHINE_DATA=/var/altworx
# do not change these
ENV_FILE_ALTWORX=.env-altworx
COMPOSE_PROJECT_NAME=aw
At the top you see versions of ALTWORX and the UI to be downloaded and installed. You can adjust the values to upgrade/downgrade between versions. However, always read the changelog as some upgrades may require some manual steps.
Following are two parameters - IN_MACHINE_CONFIGS and IN_MACHINE_DATA. These describe paths on
the host - where the current deployment is installed and where ALTWORX data are located.
TODO where should this be described? it concerns the initial installation that should be done by the admin but should be part of the docs. maybe another section?
The rest of the parameters shouldn’t be changed, unless you know what you are doing.
The main ALTWORX configuration is done via ENV variables specified in ENV/.env-altworx. The empty deployment
provides the following template.
# set this to the external URL to Altworx
ASSET_MAP_UI_URL=https://altworx.example.com
# mailer configuration
ASSET_MAP_MAILER=smtp
ASSET_MAP_SMTP_RELAY=smtp.server.com
ASSET_MAP_SMTP_USERNAME=smtp-username
ASSET_MAP_SMTP_PASSWORD=smtp-password
# enable specific scenarios, by default all are enabled
# RUNTIME_ENABLED_SCENARIOS=
RUNTIME_RUN_RESTART_PERIOD=30000
# set the project name and ENV of the deployment
ALTWORX_PROJECT=example
ALTWORX_PROJECT_ENV=dev
The full list of what’s configurable can be found in this documentation.
TODO should this be link or should we move it here?
Installation and applying changes are the same operation. Installation means taking deployment located somewhere on the host and installing it - making it the currently active deployment.
The deployments are usually located in the same folder in folders named by the time they were installed. So it may look something like this:
/opt/altworx/deployment/1619445089000
/opt/altworx/deployment/1618445089000
/opt/altworx/deployment/1593468910000
The install script then takes the deployment you want to install as a parameter, links it to the
IN_MACHINE_CONFIGS and restarts the necessary services to apply the configuration. So it can look
like this:
/opt/altworx/deployment/current-settings -> /opt/altworx/deployment/1619445089000
The process is described in greater detail in the next chapter.
For sites without access to the Internet we also provide offline installation. The procedure is very similar, you only need the following.
- export all the required Docker images and add them to the deployment2
- use
--offlineflag when running the install script
Install script will then use the enclosed docker images instead of downloading them from the internet.
TODO should we mention more/exact steps how to do that?
Deployments can bundle their own documentation to document important information and make it accessible to users/contributors. It is highly recommended for most projects to maintain some form of documentation, especially when multiple people are working on the project.
The deployment is located in ENV/doc, there must be a Dockerfile which builds the documentation
into an image. Check the empty deployment for details.