Docker

How to use the PureLife Cloud with Docker.

It is possible to run the PureLife Cloud via Docker. For this, we distribute an image via Github Packages as well as a full environment distributed via a Github repository.

Access to the image and repository is managed via a GitHub organization. To gain access to the organization, an account (a separate user or organization) must be created at GitHub. After the name of the GitHub account is provided to us, it is added as a member to the organization. Also, a login to the GitHub Docker Registry must be done via the Docker CLI to allow Docker to pull the image.

After these steps are completed, the repository can be accessed. The repository contains a docker-compose file and several configuration files for a multi-container set-up.

The docker-compose starts the following services:

1. the database management system PostgreSQL.
2. the MQTT broker Mosquitto
3. the PureLife Cloud service

The user is responsible for adapting the individual components (Database, Mosquitto,) to his own requirements.

This manual describes the installation under a Linux system. However, it should be easy to adapt it to other systems.

Preparation#

Before you start the installation, you should make sure that the following components are present:

• A Github account
• An active Docker login at the Github Container registry
• docker ≥ 20.10

$ docker -v
Docker version 20.10.12, build e91ed5707e

• docker-compose ≥ 2.2.0

$ docker-compose -v
Docker Compose version 2.2.3

• Access to the PureSec purelife-cloud-docker repository

Installation#

First copy or clone the contents of the repository and change into the folder

git clone github.com/PureSecGmbH/purelife-cloud-docker
cd purelife-cloud-docker

Create the following folders:

• volumes/application/config - volume for configuration of PureLife Cloud instance
• volumes/application/logs - volume for the PureLife Cloud instance logs
• volumes/application/data - volume for upload and generated files of PureLife Cloud Instance
• volumes/mosquitto - Volume for the Mosquitto stored data
• volumes/postgres - volume for the data stored by PostgreSQL

mkdir -p ./volumes/{application/config,application/logs,application/data,mosquitto,nginx,postgres}

Create the following files:

• volumes/mosquitto/passwd - collection of optional users and passwords for the MQTT broker.
• volumes/mosquitto/acl - collection of permissions for users

touch ./volumes/mosquitto/{passwd,acl}

Allow UID 3000 to access the PureLife Cloud directory

sudo chown -R 3000:3000 ./volumes/application

Create an .env file by copying the env.example file and using your preferred text editor to edit the file.

cp env.example .env

Make sure to change at least the following value in the .env file. If you want to change the passwords for the Postgres user, you can also do it in the .env file.

# Public host of service
HOST=purelife-cloud.example.com

Create and save the MQTT credentials for the PureLife Cloud instance. The created credentials must be stored in the .env file under WE_MQTT_USERNAME and WE_MQTT_PASSWORD.

# .env
- # WE_MQTT_USERNAME=plcuser
+ WE_MQTT_USERNAME=your-username
- # WE_MQTT_PASSWORD=123456
+ WE_MQTT_PASSWORD=your-cleartext-password

Start docker-compose as a daemon

docker-compose up -d

Try it#

Now that the PureLife Cloud instance is up and running, you can adjust the configuration or log in. To do this, open the URL http://127.0.0.1:8080 and log in with the Username admin and password admin.

Ports used#

• Mosquitto uses port 1883 by default
• The instance starts a web server which uses port 8080 by default

Use Cloud CLI#

The PureLife Cloud has a Command Line Interface (CLI) with useful helper commands. To use the CLI under Docker, start the container and open its shell.

docker exec -it purelife-cloud /bin/sh

You can find the PureLife Cloud executable under /application

~ $ cd /application
~ $ ./purelife-cloud -h

PureLife  Cloud - The connection between your sensor and you

Usage:
  purelife-cloud [flags]
  purelife-cloud [command]

Available Commands:
  bot         Management of bot accounts
  config      Configuration management
  help        Help about any command
  job         Execute jobs
  mqtt        MQTT connection management and tools
  server      Starts the PureLife Cloud instance
  session     Sessions management
  user        User management

Flags:
  -h, --help      help for purelife-cloud
  -v, --version   version for purelife-cloud

Use "purelife-cloud [command] --help" for more information about a command.