..
 # 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.

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`

* **Configure the Mender Server** :

.. code-block:: console

  export MENDER_SERVER_NAME="ms-${MACHINE}"
  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 incompatible mender capsule

  .. code-block:: console

    touch incompatible_capsule_fetch.txt
    mender-artifact write module-image \
      -T mender-capsule-fetch \
      -n incompatible-capsule-fetch \
      -o ${MENDER_SERVER_DIR}/artifacts/${MACHINE}-incompatible-capsule-fetch.mender \
      -f incompatible_capsule_fetch.txt \
      -t ${MACHINE} \
      -k ${MENDER_SERVER_DIR}/keys/private.key \
      --provides "capsule.version:1.0.0" \
      --depends "rootfs-image.version:release-x"
    mender-cli artifacts upload \
      -k --server ${MENDER_SERVER_URL_HTTPS_PORT} \
      "${MENDER_SERVER_DIR}/artifacts/${MACHINE}-incompatible-capsule-fetch.mender"

  * Upload a compatible mender capsule

  .. code-block:: console

    mender-artifact write module-image \
      -T mender-capsule-fetch \
      -n compatible-capsule-fetch  \
      -o ${MENDER_SERVER_DIR}/artifacts/${MACHINE}-compatible-capsule-fetch.mender \
      -f ${MENDER_SERVER_DIR}/artifacts/${MACHINE}.uefi.capsule \
      -t ${MACHINE} \
      -k ${MENDER_SERVER_DIR}/keys/private.key \
      --provides "capsule.version:1.0.0" \
      --depends "rootfs-image.version:release-1"
    mender-cli artifacts upload \
      -k --server ${MENDER_SERVER_URL_HTTPS_PORT} \
      "${MENDER_SERVER_DIR}/artifacts/${MACHINE}-compatible-capsule-fetch.mender"

  To check the uploaded artifacts

  .. code-block:: console

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