Deployment
==========

The Dashboard server is designed to be run as a number of Docker containers using Docker Compose.

All files needed for deployment are located on our
`GitHub <https://github.com/hilstertestingsolutions/dashboard-deployment>`_.

Clone the repository with:

.. code-block:: bash

    git clone https://github.com/hilstertestingsolutions/dashboard-deployment.git

Navigate to the folder containing the ``docker-compose.yml``.
Edit ``docker-compose.yml`` according to your needs.

.. warning::

    By default the activation key for the :ref:`community license<community-license>` is used.
    If you need a commercial license for your Dashboard, please `contact us <mailto:support@hilster.io>`_
    to get one.

Running Dashboard
-----------------

Start the Dashboard server using:

.. code-block:: bash

    docker compose up

This will collect all the necessary containers from Dockerhub and start the Dashboard server.

Running a Specific Dashboard Version
------------------------------------

To run a specific Dashboard version, modify the following line in ``docker-compose.yml`` by replacing
``latest`` with your desired version.

.. code-block::

    image: hilster/dashboard:latest

For example, to run ``Dashboard-1.2.5`` use:

.. code-block::

    image: hilster/dashboard:1.2.5

Update Dashboard
----------------

To use the to the newest version of Dashboard, run

.. code-block:: bash

    docker compose pull

Authentication
--------------

On the initial run with an empty database, a user ``root`` with password ``root``
is created automatically.

You should immediately :ref:`change the password <passwd>` using the
:ref:`command line interface <cli>` by running

.. code-block:: bash

    dashboard -u root -p root https://dashboard.server passwd

Read the :ref:`command line interface documentation <cli>` to
learn how to add other users, projects and roles.

Learn :ref:`how to reset root's password <reset-root-password>`.

Projects, Users and Roles
-------------------------

You can :ref:`create projects <create-project>`  and :ref:`users <add-user>` in the
Dashboard, and  :ref:`assign roles for users in those projects <set-roles>`.
The available roles are ``user`` and ``admin``.

Users with the role ``user`` can view all data of projects the role is applied for,
but they're not allowed to upload requirements, delete reports or manage tokens.

Users with the ``admin`` role have full access to a project.

Systemd
-------

On Linux ``systemd`` is a popular daemon to start and stop services.

To run Dashboard as a systemd service, create and edit ``dashboard.service`` to fit your needs.

.. code-block:: ini

    [Unit]
    Description=Dashboard
    Requires=docker.service
    After=docker.service

    [Service]
    WorkingDirectory=/services/dashboard
    ExecStart=/usr/bin/docker compose up
    ExecStop=/usr/bin/docker compose down
    TimeoutStartSec=0
    Restart=always
    RestartSec=20s

    [Install]
    WantedBy=multi-user.target

To install the service, run

.. code-block:: bash

    cp dashboard.service /etc/systemd/system/dashboard.service
    systemctl daemon-reload
    systemctl enable dashboard.service
    service dashboard start

To view logs of Dashboard running as a service, use

.. code-block:: bash

    journalctl -u dashboard.service -f

Workers
-------

The number of workers for the front-end and back-end can be altered in ``dashboard/dashboard.yml``
by changing ``workers`` to an appropriate value.

In the back-end, a value of ``workers: 0`` means that one worker is started per cpu.
All other positive integer numbers state the actual number of processes to be started.

Proxy
-----

``nginx`` is used as a proxy server. You can change ``nginx/default.conf`` to meet your needs, e.g. add
SSL certificates, etc.

Backup
------

To create a backup of the Dashboard database, run the following command while the server is running:

.. code-block:: bash

    ./backup_database.sh

or manually

.. code-block:: bash

    docker compose exec mongodb mongodump

The database contents will be dumped to the ``data/dump`` folder.

Restore
-------

To restore the Dashboard database from a backup, run the following command while the server is running:

.. code-block:: bash

    ./restore_database.sh

or manually

.. code-block:: bash

    docker compose exec mongodb mongorestore

The database contents will be restored from the ``data/dump`` folder.