Step 1: Running Axual

Running Axual locally

By following the steps below you can run Axual locally and follow the remainder of the Getting Started.

Prerequisites

Before starting, there are a few things required to setup:

  • use any Linux distribution or OS X with Bash 4.2+ installed ( Windows systems are not supported )

  • install Docker, currently due to issues with the latest stable Docker release, the latest supported version supported is 2.1.0.5 ( MacOS, Linux )

Make sure that your docker daemon has at least 3GB of RAM and 6 CPU cores

Downloading Axual

  1. login into Axual’s docker repository with docker login docker.axual.io using the credentials provided by Axual.

  2. download the local installation of Axual using the same docker credentials.

Package contents

The example setup of Axual Deploy contains the following:

  1. Deployment scripts (scripts that start/stop the platform services)

  2. Platform configuration (cluster, instance and tenant configuration)

  3. Security folder with dummy Keystores for components in order to enable SSL communication

  4. The initial-setup.sh script

  5. The axual.sh script

Initial setup (first time only)

The following steps are only necessary the first time. After you have completed these steps, your machine is setup and prepared to run Axual multiple times

Firstly, start your terminal application. Use your favorite text editor to append the following line at the bottom of your /etc/hosts file: "192.168.99.100 platform.local".

192.168.99.100 platform.local

Next, we will unzip the previously downloaded tar file in a newly made directory.

mkdir ~/local-axual-directory
tar -xvf ~/Downloads/axual-platform-local-2020-1.tar.gz -C ~/local-axual-directory

Before running Axual for the first time, it is required to run the initial-setup.sh script to prepare your machine. You will be prompted for the sudo password for make a local modification to your hosts file.

You will also be prompted to create a password for a local (Dockerized) database. Please use the same password for all questions.
~/local-axual-directory/initial-setup.sh -run

You should see the following output (or similar):

Adding alias 192.168.99.100 to interface lo0
Writing the host file at /Users/yourname/host.sh
Creating local data directory at /Users/yourname/axual_local_data
Creating an SQL file with initial statements to be inserted in the local database...
Setup complete.
###############

Start the platform with './axual.sh [-v] start' (optional argument '-v' stands for verbose)
You will be prompted to insert the DB root password.

After the platform starts, login into the self-service portal using the following credentials:
URL: https://192.168.99.100:8095/
Username: 'demo@axualdemo.nl'
Password: 'password'

Use the following configuration for your application to connect to this Axual platform deployment:
ENDPOINT=https://192.168.99.100:29000
ENVIRONMENT=local
TENANT=demo
KEYSTORE_LOCATION=/Users/yourname/Downloads/axual-platform-local-5.1/security/application/axual-local-application.keystore.jks
TRUSTSTORE_LOCATION=/Users/yourname/Downloads/axual-platform-local-5.1/security/application/axual-local-application.keystore.jks
All keystore, truststore and key passwords are 'notsecret'
The application ID and version are chosen by the developer.

You can run './initial-setup.sh -run' again to display this screen

Customization is possible, run the script with -help instead of -run for more information.

Trusting our Certificate Authority

In the local setup of the platform, we use a lot of certificates signed by "Axual Dummy Intermediate 01". In order to prevent browser warnings, you have to import that certificate in your local keychain (MacBook) and mark it as trusted.

  1. Download the Axual Dummy Intermediate 2018 01 certificate file

  2. Double click it, "KeyChain Access" will open.

  3. Mark the certificate as "Always Trusted" as indicated in the screenshot below

    Trusting Axual Dummy Intermediate 01

Running the platform

To simply start the platform, run the following command:

~/local-axual-directory/axual.sh start

If everything went successfully, a similar output should be present in the console:

Configuring cluster services for node localhost in cluster LOCAL
Preparing exhibitor: Done
Starting exhibitor: Done
Waiting for exhibitor on 192.168.99.100
Connected to exhibitor on 192.168.99.100
Preparing broker: Done
Starting broker: Done
Waiting for broker on 192.168.99.100
Connected to broker on 192.168.99.100
Preparing cluster-api: Done
Starting cluster-api: Done
Preparing distributor: Done
Starting distributor: Done
Deploying topic _company-local-environments: Done
Deploying topic _company-local-schemas: Done
Configuring instance services for company-local in cluster LOCAL
Stopping distributors with prefix company-local-message-distributor-from-: Done
Stopping distributors with prefix company-local-offset-distributor-from-: Done
Stopping distributors with prefix company-local-schema-distributor-: Done
Preparing company-local-sr-master: Done
Starting company-local-sr-master: Done
Preparing company-local-sr-slave: Done
Starting company-local-sr-slave: Done
Running copy-config-company-local-discovery-api: Done
Preparing company-local-discovery-api: Done
Done
Starting company-local-discovery-api: Done
Preparing company-local-instance-api: Done
Cluster servers are https://platform.local:9080
Done
Starting company-local-instance-api: Done
Configuring mgmt services for node localhost in cluster LOCAL
Running clean-config-prometheus: /config/prometheus
Done
Generating prometheus targets...
Generating prometheus configuration...
Running create-config-prometheus: Done
Running copy-config-prometheus: Done
Starting prometheus: Done
Provisioning grafana dashboards...
Running copy-config-grafana: Done

After the platform starts, login into the self-service portal using the following credentials:

Please make sure to use a supported browser
URL: https://192.168.99.100:8095/login/demo
Username: 'demo@axualdemo.nl'
Password: 'password'

To stop the platform, run the following command:

~/local-axual-directory/axual.sh stop

Next step: Creating A Stream

You are now ready to move on to the next step 2. Creating a stream to make sure you can connect to the platform securely and your application(s) can be authorized to access the stream.