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

* **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}"

These are the requirements to perform a mender system update

.. _artifact_upload_label:

* **Artifact Upload** :

  Upload an unsigned version

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

  Sign a Mender artifact and upload to the Mender server

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

  Check artifacts

  .. code-block:: console

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