Initial setup

The BlueRange server and additional services required for logging, updating and monitoring are installed from the setup package available at BlueRange Setup@GitHub. Following is a walk-through of the installation steps outlined in the Readme.

Clone the setup

The installation files are downloaded:

$ cd /opt
$ sudo git clone https://github.com/bluerange-io/bluerange-setup.git
Cloning into 'bluerange-setup'...
[..]
$ cd bluerange-setup

Further steps are carried out in the folder /opt/bluerange-setup.

Configuring the server

Edit the configuration file:

$ hostname
my.bluerange.io
$ pwd
/opt/bluerange-setup
$ sudo editor server.env

The server.env file consists of a number of KEY=VALUE pairs. As a minimum the hostname must be set as HOST variable. Ideally the server properly displays its name:^[1]

$ hostname --all-fqdns
my.bluerange.io localhost.localdomain
$ hostname --fqdn
my.bluerange.io

The name given as e.g. HOST=my.bluerange.io must match the server certificate.

Check if the host is reachable by its name. Ping the host, for example, 'ping my.bluerange.io'. On local machines it can sometimes happen that the shown hostname is not part of your (local) DNS. In this case use the ip address instead (for test installations only).

For some features like requesting a password reset the server requires access to an SMTP email server:

SMTP_HOST=smtp-machine.my-domain.me
SMTP_PORT=25
SMTP_USERNAME=smtp-username
SMTP_PASSWORD=XXXXXXXX

The SMTP configuration is recommended but not strictly required. When omitted features depending on it may not be available.

By default, the installation picks up the passwords defined in the .env file:

$ cat .env
COMPOSE_PROJECT_NAME=bluerange
SYSTEM_ADMIN_PASSWORD=admin123
ORGA_ADMIN_PASSWORD=iot12345
ROOT_DATABASE_PWD=root-database-pwd-change-me
BLUERANGE_DATABASE_PASSWORD=bluerange-database-pwd-change-me
MONGO_PASSWORD=bluerange-mongodb-pwd-change-me
GRAFANA_DATABASE_PASSWORD=grafana-database-pwd-change-me
MINIO_ACCESS_KEY=mender-deployments
MINIO_SECRET_KEY=minio-secret-change-me

Please keep the COMPOSE_PROJECT_NAME as is. The remaining passwords should be overwritten in the server.env. Passwords may be generated using the command:

$ pwgen -snc 48 5
a0bYPrcyE7wOSFtYzKWBh1IJJBI2XqnqvTLli02Konep6FTq
S2u5hPTJFycERRcEOf08Aiqvkz3bslXjx8R7JWgWy80uoFrs
0WDNDk8gDGDVWirpxClwMA3oRvKbjIwfZ6Oqey8REHoR6Ykw
Xx9CDrSSRuchTI9anFiLEBrihf6Jpntjh3rb1WuEEuMwPEtE
cSfn7EzlD1UWXJd9ugJYM2UaLE7tBtHzVaZzxunKjM2pNFFS

The file uses shell escaping so that special characters in passwords may need to be escaped!

The minimal server.env file should look like this:

$ sudo cat server.env
HOST=my.bluerange.io
ROOT_DATABASE_PWD=a0bYPrcyE7wOSFtYzKWBh1IJJBI2XqnqvTLli02Konep6FTq
BLUERANGE_DATABASE_PASSWORD=S2u5hPTJFycERRcEOf08Aiqvkz3bslXjx8R7JWgWy80uoFrs
MONGO_PASSWORD=0WDNDk8gDGDVWirpxClwMA3oRvKbjIwfZ6Oqey8REHoR6Ykw
GRAFANA_DATABASE_PASSWORD=Xx9CDrSSRuchTI9anFiLEBrihf6Jpntjh3rb1WuEEuMwPEtE
MINIO_SECRET_KEY=cSfn7EzlD1UWXJd9ugJYM2UaLE7tBtHzVaZzxunKjM2pNFFS

Except the organization administrator’s password these passwords do not need to be entered by a human so there is no reason to use weak passwords.

The SYSTEM_ADMIN_PASSWORD=admin123 and ORGA_ADMIN_PASSWORD=iot12345 are used for initialization only and may be changed at any time later on in the UI of the server. The MINIO_ACCESS_KEY=mender-deployments may be chosen arbitrarily and need not be changed.

Configure certificates

The installation expects to provide a HTTPS certificate. To either let traefik request it, or statically provision it, check our 'HTTPS certificate' documentation.

Start BlueRange

This compose file defines the services: traefik, bluerange, mosquitto, postgresql, mongodb

To start BlueRange you can now use bluerange-compose.sh to start all the Docker containers defined in the yaml file:

$ sudo ./bluerange-compose.sh up -d

This will download the Docker image of each service defined in the docker-compose.yml file before starting a Docker container for each service. Images are cached on the local machine, so future starts will be faster.

The compose files force using bluerange-compose.sh as a replacement of docker-compose. Running docker-compose directly will not work and issue an error instead.

It will take some time for the services to start up once the downloads complete. To see the log output of a specific container use the following command:

$ sudo ./bluerange-compose.sh logs --follow bluerange
Attaching to bluerange_bluerange_1
bluerange_1 Certificate was added to keystore
bluerange_1 Temp directory does not exist. It will be created.
bluerange_1 Expected configuration found in './application.yml' or environment variables
bluerange_1  ________  ___       ___  ___  _______   ________  ________  ________   ________  _______           ___  ___  ___
bluerange_1 |\   __  \|\  \     |\  \|\  \|\  ___ \ |\   __  \|\   __  \|\   ___  \|\   ____\|\  ___ \         |\  \|\  \|\  \
bluerange_1 \ \  \|\ /\ \  \    \ \  \\\  \ \   __/|\ \  \|\  \ \  \|\  \ \  \\ \  \ \  \___|\ \   __/|        \ \  \ \  \ \  \
bluerange_1  \ \   __  \ \  \    \ \  \\\  \ \  \_|/_\ \   _  _\ \   __  \ \  \\ \  \ \  \  __\ \  \_|/__       \ \  \ \  \ \  \
bluerange_1   \ \  \|\  \ \  \____\ \  \\\  \ \  \_|\ \ \  \\  \\ \  \ \  \ \  \\ \  \ \  \|\  \ \  \_|\ \       \/  /\/  /\/  /|
bluerange_1    \ \_______\ \_______\ \_______\ \_______\ \__\\ _\\ \__\ \__\ \__\\ \__\ \_______\ \_______\      /  ///  ///  //
bluerange_1     \|_______|\|_______|\|_______|\|_______|\|__|\|__|\|__|\|__|\|__| \|__|\|_______|\|_______|     /_ ///_ ///_ //
bluerange_1                                                                                                    |__|/|__|/|__|/
[..]

The log output can be stopped by pressing Ctrl-C.

After first startup, please check your container is all fine by rerunning the bluerange-compose.sh command. The command will retry restarting any failed containers. If all is well no container should be restarted:

$ sudo ./bluerange-compose.sh
bluerange_bluerange_1 is up-to-date
bluerange_mongodb_1 is up-to-date
bluerange_mosquitto_1 is up-to-date
bluerange_postgresql_1 is up-to-date
bluerange_traefik_1 is up-to-date

In case of any failed container, try the log command above to find out why things went wrong. A common source of issues is in DNS and HTTPS certificates which can be checked for validity, e.g.:

$ openssl s_client -connect my.bluerange.io:443
CONNECTED(00000003)
[...]
---
SSL handshake has read ... bytes and written ... bytes
Verification: OK
---
New, TLSv1.3, Cipher is TLS_AES_128_GCM_SHA256
Server public key is 4096 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)
---
[...]

As a final check of the BlueRange server the health status can be queried:

$ curl https://my.bluerange.io/actuator/health
{"status":"UP"}

The health status endpoint is available for integration into monitoring systems.

When fetching the health status providing server administrator credentials using basic-auth or an api-key further details are made available.

As a last step in server installation rebooting the host machine is recommended ensuring a properly configured networking environment and that all the services come up automatically.

Stopping the server

For maintenance, it might become necessary to stop all the services temporarily. This can be done by shutting down the composition without destroying volumes:

$ sudo ./bluerange-compose.sh down
Stopping bluerange_traefik_1            ... done
Stopping bluerange_mosquitto_1          ... done
Stopping bluerange_bluerange_1          ... done
Stopping bluerange_mongodb_1            ... done
Stopping bluerange_postgresql_1         ... done
[...]
Removing bluerange_traefik_1            ... done
Removing bluerange_mosquitto_1          ... done
Removing bluerange_bluerange_1          ... done
Removing bluerange_mongodb_1            ... done
Removing bluerange_postgresql_1         ... done
[...]
Removing network bluerange_default

This will not remove the downloaded images and preserves database data.

When you shut down a Docker container, data inside the container is potentially lost. This means data that needs to be persisted must be stored outside the container (e.g. on a mounted volume). The default configuration maps the data directories of PostgreSQL and MongoDB to Docker volumes named postgresql and mongodb respectively.

BlueRange stores all of its data in the database, so no additional configuration should be needed. Make sure to include PostgreSQL and MongoDB in your backup strategy though.

1. In case hostname --fqdn does not display the correct hostname, chances are that DNS is not set up correctly.