Required companion files for setting up BlueRange on various platforms. Detailed installation instructions can be found here.
BlueRange runs dockerized and needs the current versions of Docker and Docker-Compose.
BlueRange has been verified to work with:
- PostgreSQL 14.0 or newer
- MariaDB 10.11 LTS or a newer LTS version
- MongoDB 7
There is a convenience bluerange-compose.sh script added, as a wrapper for docker-compose that sets up the needed environment in a deterministic way.
Notice, the bluerange-compose.sh script can be used just like docker-compose:
# start all-in-one BlueRange software stack
$ ./bluerange-compose.sh up -d
# display all logs with follow
$ ./bluerange-compose.sh logs -f
# tear down all-in-one BlueRange software stack
$ ./bluerange-compose.sh downThe volumes mysql, postgresql and mongodb are set up in order not to lose data stored when the nodes are rebuilt.
The following ports are available on the host:
| Port | Service | Description | Access |
|---|---|---|---|
| 80 | HTTP | Traefik with auto redirect to HTTPS | Public |
| 443 | HTTPS | Traefik and MQTT over WebSockets | Public |
| 1883 | MQTT TCP | Mosquitto | Docker host only |
| 3306 | MySQL | Database service | Docker host only |
| 5432 | PostgreSQL | Database service | Docker host only |
| 8080 | BlueRange UI | Web interface | Docker host only |
| 8099 | Spring Actuators | BlueRange monitoring | Docker host only |
| 8883 | MQTT SSL | Mosquitto | Public |
| 27017 | MongoDB | Database service | Docker host only |
Ports not required for operation but for diagnostics only are bound to the docker host only. All port mappings may be customized by overwriting them in the server.env file. The names of those custom port mappings can be looked up in .env and are prefixed by PORT_.
The docker-compose scripts expect that the following file is provided:
server.env: environment variable file containing the host machine name as registered in DNS and mail server configuration
The server.env file should look like this:
HOST=my-machine.my-domain.me
SMTP_HOST=smtp-machine.my-domain.me
SMTP_PORT=25
SMTP_USERNAME=smtp-username
SMTP_PASSWORD=XXXXXXXXThe HTTPS certificate required may be generated using https://letsencrypt.org/. Please make sure to have a property DNS record set up for your workstation.
Certificates are obtained by the Traefik container. To enable it, choose one of the supported challenges: TLS-ALPN-01 HTTP-01 or DNS-01 and check the detailed documentation for the needed parameter.
Add the traefik static config in the CLI syntax to the docker-compose.override.yml like:
services:
traefik:
command:
- --certificatesresolvers.letsencrypt.acme.dnschallenge.provider=manual
### for testing purpose the let's encrypt stating environment can be activated
# - --certificatesresolvers.letsencrypt.acme.caServer=https://acme-staging-v02.api.letsencrypt.org/directory
### any configuration from the docker-compose.yml can be overridden
# - --log.level=DEBUGFor the SQL database, the docker-compose.yml contains both PostgreSQL (current recommendation) and MariaDB (legacy). To activate one or the other, docker-compose profiles are used, which can be configured by setting COMPOSE_PROFILES in server.env.
Please see the Migration Guide for switching from MariaDB to PostgreSQL.
Further customization should be done using the docker-compose.override.yml mechanism, see https://docs.docker.com/compose/extends/.
To customize the BlueRange server itself, use the application.yml.
By default, the environment is set up automatically creating an organization named IOT. It is expected to enroll IoT things therein. To log on, use username admin and password ${ORGA_ADMIN_PASSWORD}.
From here, we'll recommend to follow the Quick Start Guide in our documentation.
The script bluerange-backup.sh allows saving the database content and server configuration into a single file:
$ ./bluerange-backup.sh
# ...
* backup/bluerange-20210421_132111.tar.gzThe backup file can be uploaded to some permanent storage such as S3. The script is intended to run regularly using cron, for example.
The bluerange-restore.sh script allows restoring the installation given a fresh working copy:
$ ./bluerange-restore.sh backup/bluerange-20210421_132111.tar.gz
All existing BlueRange server data will be erased!
Are you sure to restore from bluerange-20210421_132111?
Type YES: YES
# ...
Backup bluerange-20210421_132111 restored.
# * ./bluerange-compose.sh to start the server...Finally start the server using bluerange-compose.sh once so that the system services are installed.