..
 # SPDX-FileCopyrightText: Copyright (c) 2025, Linaro Limited.
 #
 # SPDX-License-Identifier: MIT

.. _setup_mender_server_label:

*******************
Setup Mender Server
*******************

The Mender server is run on a host machine OS which is formed of small container services.
Pull the Mender utility Docker image and launch the container on the host machine.

.. note::
  The Mender server currently runs exclusively on x86_64 architecture,
  and its build process has been tested and validated on Ubuntu 22.04 LTS.

These are the required environment variables, refer :ref:`here <mender-env-vars-section>` for more details.

  * `MENDER_SERVER_DIR`
  * `MACHINE`
  * `BRANCH`

.. code-block:: console

  docker pull registry.gitlab.com/linaro/cassini/meta-cassini/mender-utility-image:${BRANCH}
  docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ${MENDER_SERVER_DIR}:${MENDER_SERVER_DIR} \
    -it registry.gitlab.com/linaro/cassini/meta-cassini/mender-utility-image:${BRANCH}

This opens a shell environment and
these are the required environment variables, refer :ref:`here <mender-env-vars-section>` for more details.

  * `MENDER_SERVER_DIR`
  * `MACHINE`
  * `MENDER_SERVER_IP`
  * `MENDER_SERVER_HTTPS_PORT`
  * `MENDER_SERVER_HTTP_PORT`

Also, these are only required for full capsule update:

  * `MENDER_FW_GUID`
  * `MENDER_FW_VERSION`
  * `MENDER_CAPSULE_VERSION`

* **Configure the Mender Server** :

.. code-block:: console

  export MENDER_SERVER_NAME="ms-${MACHINE}"
  cd ${MENDER_SERVER_DIR}
  cp -r /home/mender-server/. ${MENDER_SERVER_DIR}/
  source ./mender_env_server.sh
  source ./docker-compose-override.sh

* **Start the Mender server** :

.. code-block:: console

  docker compose --project-name "${MENDER_SERVER_NAME}" up -d --quiet-pull
  docker compose --project-name "${MENDER_SERVER_NAME}" ps

.. _user_and_authentication_setup_label:

* **User Setup** :

  Create a test user for the Mender server UI/API

  .. code-block:: console

    docker compose --project-name "${MENDER_SERVER_NAME}" exec useradm \
      useradm create-user --username "${MENDER_SERVER_USERNAME}" \
    --password "${MENDER_SERVER_PASSWORD}"

  Authenticate using mender-cli

  .. code-block:: console

    mender-cli login \
      --server "${MENDER_SERVER_URL_HTTPS_PORT}" \
      --skip-verify \
      --username "${MENDER_SERVER_USERNAME}" \
      --password "${MENDER_SERVER_PASSWORD}"

.. _artifact_upload_label:

* **Artifact Upload** :

  These are the requirements to perform a **mender system update**.

  * Upload an unsigned mender artifact

  .. code-block:: console

    cp ${MENDER_SERVER_DIR}/artifacts/${MACHINE}.mender ${MENDER_SERVER_DIR}/artifacts/${MACHINE}-unsigned.mender
    mender-artifact modify -n unsigned-image ${MENDER_SERVER_DIR}/artifacts/${MACHINE}-unsigned.mender
    mender-cli artifacts upload -k --server ${MENDER_SERVER_URL_HTTPS_PORT} ${MENDER_SERVER_DIR}/artifacts/${MACHINE}-unsigned.mender

  * Upload a signed mender artifact

  .. code-block:: console

    mender-artifact modify -n release-2 -k ${MENDER_SERVER_DIR}/keys/private.key ${MENDER_SERVER_DIR}/artifacts/${MACHINE}.mender
    mender-cli artifacts upload -k --server ${MENDER_SERVER_URL_HTTPS_PORT} ${MENDER_SERVER_DIR}/artifacts/${MACHINE}.mender

  These are the requirements to perform a **mender capsule update**.

  * Upload a compatible mender capsule

  .. code-block:: console

    # Set GUID and versions
    export MENDER_FW_GUID=<guid>
    export MENDER_FW_VERSION=<old-version>
    export MENDER_CAPSULE_VERSION=<new-version>

    mender-artifact write module-image \
      -T uefi-capsule \
      -n compatible-capsule-update \
      -o ${MENDER_SERVER_DIR}/artifacts/${MACHINE}-compatible-capsule-update.mender \
      -f ${MENDER_SERVER_DIR}/artifacts/${MACHINE}.uefi.capsule \
      -t ${MACHINE} \
      -k ${MENDER_SERVER_DIR}/keys/private.key \
      --provides "uefi-firmware.${MENDER_FW_GUID}.version:${MENDER_CAPSULE_VERSION}" \
      --depends "uefi-firmware.${MENDER_FW_GUID}.version:${MENDER_FW_VERSION}"

    mender-cli artifacts upload \
      -k --server ${MENDER_SERVER_URL_HTTPS_PORT} \
      "${MENDER_SERVER_DIR}/artifacts/${MACHINE}-compatible-capsule-update.mender"

  These are the requirements to perform a **mender rollback capsule update**.

  * Use capsule-tool.py to generate a tampered capsule

  .. code-block:: console

    ${MENDER_SERVER_DIR}/systemready-scripts/capsule-tool.py --tamper \
      --output ${MENDER_SERVER_DIR}/artifacts/tampered-${MACHINE}.uefi.capsule \
      ${MENDER_SERVER_DIR}/artifacts/${MACHINE}.uefi.capsule

  * Upload a compatible rollback mender capsule

  .. code-block:: console

    # Set GUID and versions
    export MENDER_FW_GUID=<guid>
    export MENDER_FW_VERSION=<old-version>
    export MENDER_CAPSULE_VERSION=<new-version>

    mender-artifact write module-image \
      -T uefi-capsule \
      -n compatible-rollback-capsule-update \
      -o ${MENDER_SERVER_DIR}/artifacts/${MACHINE}-compatible-rollback-capsule-update.mender \
      -f ${MENDER_SERVER_DIR}/artifacts/tampered-${MACHINE}.uefi.capsule \
      -t ${MACHINE} \
      -k ${MENDER_SERVER_DIR}/keys/private.key \
      --provides "uefi-firmware.${MENDER_FW_GUID}.version:${MENDER_CAPSULE_VERSION}" \
      --depends "uefi-firmware.${MENDER_FW_GUID}.version:${MENDER_FW_VERSION}"

    mender-cli artifacts upload \
      -k --server ${MENDER_SERVER_URL_HTTPS_PORT} \
      "${MENDER_SERVER_DIR}/artifacts/${MACHINE}-compatible-rollback-capsule-update.mender"

  To check the uploaded artifacts

  .. code-block:: console

    mender-cli artifacts list -k --server ${MENDER_SERVER_URL_HTTPS_PORT}