Mender Server

tutorial

Please note the code snippets in this section reuses the environment variables you set up when progressing through the tutorial, including the optional step of installing the Artifact Storage. Please make sure you correctly define them or adapt the snippet to your specific use case.

Prerequisites

Ingress Controller

You must configure an Ingress or a Load Balancer to expose the Mender Server outside the Kubernetes cluster.

Required configuration:

  • Redirection from HTTP to HTTPS on the Ingress.
  • Health check: if your load balancer requires it, the internal path is /ui
  • Either a valid certificate for the ${MENDER_SERVER_DOMAIN} must exists as a secret named mender-ingress-tls, or you already have configured the Cert-manager resource

You can refer to your Infrastructure Provider's documentation for creating an Ingress resource. Starting from the Mender Helm Chart version 5.1.0, a sample Ingress resource is included. Starting from the Mender Helm Chart version 6.0.0, the Ingress feature is enabled by default.

Following some Ingress examples. Please refer to your Infrastructure Provider's documentation for creating an Ingress resource and for the required annotations.

For example, here's an Ingress for the Traefik Provider, included in K3s:

export MENDER_SERVER_DOMAIN="mender.example.com"

cat <<-EOF > mender-values.yml
ingress:
  enabled: true
  annotations:
    cert-manager.io/issuer: "letsencrypt"
  ingressClassName: traefik
  path: /
  hosts:
    - ${MENDER_SERVER_DOMAIN}
  tls:
  # this secret must exists or it can be created from a working cert-manager instance
    - secretName: mender-ingress-tls
      hosts:
        - ${MENDER_SERVER_DOMAIN}
EOF

Other Ingress Controllers

Alternatively, you can create your own Ingress resource. Some references:

External services

The Mender Server requires the following services to operate:

  • MongoDB: to store the Mender Server data, including user and device information.
  • NATS: to handle the communication between the Mender Server components.
  • Redis: to store the temporary data and cache.
  • Object Storage: to store the Mender Artifacts. Please refert to the Storage section for more information on how to set up an object storage service.

The Mender Helm chart already provides as sub-charts the following services:

Using these packages is fine for test or PoC setups. For production setups, however, it's recommended to use external dedicated services. Keep reading for instructions on how to use production-grade services.

Please refer to the Requirements section for more information on the supported versions of the external services.

To use an external MongoDB service, create a secret with the MongoDB connection string:

kubectl create secret generic mender-mongo \
  --from-literal=MONGO="mongodb://mymongouser:mymongopassword@my-mongo-host:27017/mender" \
  --from-literal=MONGO_URL="mongodb://mymongouser:mymongopassword@my-mongo-host:27017/mender"

Then, configure the Mender Server to use the external MongoDB service:

global:
  mongodb:
    existingSecret: "mender-mongo"

# Disable the integrated MongoDB subchart:
mongodb:
  enabled: false

If you want to use the Service Provider Tenants feature, you need to create a database user with the atlasAdmin@admin role.
If you want to keep this user separate to the rest of the application, you have to provide dedicated connection to the Deployments and the Inventory services:

kubectl create secret generic mender-mongo-admin \
  --from-literal=MONGO="mongodb://mymongoadmin:mymongopassword@my-mongo-host:27017/mender" \
  --from-literal=MONGO_URL="mongodb://mymongoadmin:mymongopassword@my-mongo-host:27017/mender"

And then configure the Mender Server to use the external MongoDB service:

deployments:
  mongodbExistingSecret: "mender-mongo-admin"
inventory:
  mongodbExistingSecret: "mender-mongo-admin"

Installing the Mender Helm chart

Please note the code snippets in this section reuses the environment variables you set up when progressing through the tutorial, including the optional step of installing the Artifact Storage. Please make sure you correctly define them or adapt the snippet to your specific use case.

Before installing the Mender Server on the Kubernetes cluster using the Mender Helm chart, add the Mender Helm Chart repository:

helm repo add mender https://charts.mender.io
helm repo update

You can now install the Mender Server.

export MENDER_SERVER_DOMAIN="mender.example.com"
export MENDER_SERVER_URL="https://${MENDER_SERVER_DOMAIN}"

cat <<-EOF >> mender-values.yml
global:
  s3:
    AWS_URI: "${MENDER_SERVER_URL}"
    AWS_BUCKET: "${STORAGE_BUCKET}"
    AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID}"
    AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY}"
  url: "${MENDER_SERVER_URL}"

api_gateway:
  storage_proxy:
    enabled: true
    url: "${STORAGE_ENDPOINT}"
    customRule: "PathRegexp(\`^/${STORAGE_BUCKET}\`)"

deployments:
  customEnvs:
    - name: DEPLOYMENTS_STORAGE_PROXY_URI
      value: "${MENDER_SERVER_URL}"
EOF

Finally, install the Mender Server:

helm upgrade --install mender mender/mender -f mender-values.yml

How to select the Docker tag to use

We provide the following Docker image tags:

  • Immutable tag for a specific bugfix version: e.g., vX.Y.Z (recommended)
  • Moving tag for a specific minor version: e.g., vX.Y
  • Moving tag for a major version: e.g., vX
  • Moving tag for the latest released bugfix version: latest
  • Moving tag for the latest development version: main

Post-installation setup

Enable replication for NATS Jetstream (Recommended)

For production setup that require high availablility, we recommend enabling replication for the NATS Jetstream work queues. By default, NATS deploys 3 replicas, but the stream created by the workflows service does not have replication enabled and therefore has no fault tolerance. The following snippet increases the number of replicas to 3.

Please replace NATS_URL in the following snippet with a URL that resolves to any of the NATS pods.

NATS_URL="nats://mender-nats" # REPLACE
kubectl run --env=NATS_URL=$NATS_URL --image=natsio/nats-box:0.14.5-nonroot \
    nats-increase-replicas -- \
    nats stream edit WORKFLOWS --force --replicas=3

Create the admin user

Create the initial user using the useradm pod:

USERADM_POD=$(kubectl get pod -l 'app.kubernetes.io/component=useradm' -o name | head -1)
kubectl exec $USERADM_POD -- useradm create-user --username "demo@mender.io" --password "demodemo"

Pre-release version

To use a pre-release (master) version of the backend, please refer to the Development section of the documentation.

We welcome contributions to improve this documentation. To submit a change, use the Edit link at the top of the page or email us at .