TipsAndTricks/QuickStartOnMenderOTA

Mender Over-The-Air Software Update for Embedded Linux

Mender is an open source remote software updater for embedded Linux devices. It includes both a client and a management server. Mender allows you to deploy an image-based update from the server-side component to your connected devices. We have tried out on qemu for ARM and here are some BKMs to get start.

Mender Artifacts Server Setup Guide

1st Option: DIY Server Setup

Host machine requirements:

[1] OS : Ubuntu 16.04

[2] Google Chrome

[3] Docker Engine 1.11 & above

[4] Docker Compose 1.6 & above

Basic preparation setup

1. Start with cloning the Mender integration repo.

$ git clone -b 1.3.0 https://github.com/mendersoftware/integration mender-server
$ cd  mender-server
$ git checkout -b my-test-setup

2. Duplicate the deployment template to a new directory named production.

$ cp -a template production

3. Replace all template path to new production path.

$ cd production
$ ls
# Two files are included: prod.yml and run
$ sed -i -e 's#/template/#/production/#g' prod.yml

4. Run the script to pull docker image. The run script is a wrapper to help users to setup images with docker compose.

Creating certificates and keys

1. Prepare certificates using the helper script keygen (replacing mender.example.com and s3.example.com with your own DNS names)

$ CERT_API_CN=server.example.com CERT_STORAGE_CN=server.example.com ../keygen

2. The certs and keys generated in a separate directory named keys-generated:

├── keys-generated
│   ├── certs
│   │   ├── api-gateway
│   │   │   ├── cert.crt
│   │   │   └── private.key
│   │   └── server.crt
│   │   └── storage-proxy
│   │       ├── cert.crt
│   │       └── private.key
│   └── keys
│       ├── deviceauth
│       │   └── private.key
│       └── useradm
│           └── private.key
├── prod.yml
└── run

Persistent storage

Persistent storage of backend services' data is implemented using named Docker volumes. The template is configured to mount the following volumes:

mender-artifacts - artifact objects storage

mender-deployments-db - deployments service database data

mender-useradm-db - user administration service database data

mender-deviceauth-db - device authentication service database data

mender-deviceadm-db - device admission service database data

mender-inventory-db - inventory service database data

Note: There is no documentation on how server admin can access to Docker volumes for artifacts browsing or further inspection.

Each of these volumes need to be created manually:

$ docker volume create --name=mender-artifacts
$ docker volume create --name=mender-deployments-db
$ docker volume create --name=mender-useradm-db
$ docker volume create --name=mender-inventory-db
$ docker volume create --name=mender-deviceadm-db
$ docker volume create --name=mender-deviceauth-db
$ docker volume create --name=mender-elasticsearch-db
$ docker volume create --name=mender-dynomite-db

Final configurations

All configurations below were made in prod.yml:

1. Storage proxy

...
storage-proxy:
    networks:
        mender:
            aliases:
                - server.example.com
...

2. Minio

In mender-server directory, run "pwgen 16 1" command to generate the secret 16-character value. You will need the 16-character long value for settings in minio. My testing secret key: ahshagheeD1ooPaeT8lut0Shaezeipoo

...
minio:
    environment:
        # access keys
        MINIO_ACCESS_KEY: mender-deployments
        # secret
        MINIO_SECRET_KEY: ahshagheeD1ooPaeT8lut0Shaezeipoo
...

3. Deployments service

...
mender-deployments:
    ...
    environment:
        DEPLOYMENTS_AWS_AUTH_KEY: mender-deployments
        DEPLOYMENTS_AWS_AUTH_SECRET: ahshagheeD1ooPaeT8lut0Shaezeipoo
        DEPLOYMENTS_AWS_URI: https://server.example.com:9000
...

4. API gateway

...
mender-api-gateway:
    ...
    environment:
        ALLOWED_HOSTS: server.example.com
...

5. Device authentication service

...
mender-device-auth:
    ...
    environment:
        DEVICEAUTH_MAX_DEVICES_LIMIT_DEFAULT: 15
...

Bring it UP!

$ ./run up -d

To verify the services are running, you can check via 'ps' command:

$ ./run ps

                   Name                                  Command               State           Ports
-------------------------------------------------------------------------------------------------------------
menderproduction_mender-api-gateway_1         /entrypoint.sh                   Up      0.0.0.0:443->443/tcp
menderproduction_mender-deployments_1         /entrypoint.sh                   Up      8080/tcp
menderproduction_mender-device-adm_1          /usr/bin/deviceadm -config ...   Up      8080/tcp
menderproduction_mender-device-auth_1         /usr/bin/deviceauth -confi ...   Up      8080/tcp
menderproduction_mender-gui_1                 /entrypoint.sh                   Up
menderproduction_mender-inventory_1           /usr/bin/inventory -config ...   Up      8080/tcp
menderproduction_mender-mongo-deployments_1   /entrypoint.sh mongod            Up      27017/tcp
menderproduction_mender-mongo-device-adm_1    /entrypoint.sh mongod            Up      27017/tcp
menderproduction_mender-mongo-device-auth_1   /entrypoint.sh mongod            Up      27017/tcp
menderproduction_mender-mongo-inventory_1     /entrypoint.sh mongod            Up      27017/tcp
menderproduction_mender-mongo-useradm_1       /entrypoint.sh mongod            Up      27017/tcp
menderproduction_mender-useradm_1             /usr/bin/useradm -config / ...   Up      8080/tcp
menderproduction_minio_1                      minio server /export             Up      9000/tcp
menderproduction_storage-proxy_1              /usr/local/openresty/bin/o ...   Up      0.0.0.0:9000->9000/tcp

Create a user login account.

$ sudo ./run exec mender-useradm /usr/bin/useradm create-user --username=myusername@host.com --password=mysecretpassword

You can now browse the web UI via: https://server.example.com:9000

Contribution to meta-mender

[1] Fixed qemu wrapper script memory allocation for software upgrade [1]