.. _server-configure:

Configure
^^^^^^^^^

The vantage6-server requires a configuration file to run. This is a
``yaml`` file with a specific format.

The next sections describes how to configure the server. It first provides a few
quick answers on setting up your server, then explains where your vantage6
configuration files are stored, and finally shows an example of all
configuration file options.

How to create a configuration file
""""""""""""""""""""""""""""""""""

The easiest way to create an initial
configuration file is via: ``v6 server new``. This allows you to configure the
basic settings. For more advanced configuration options, which are listed below,
you can view the :ref:`example configuration file <server-config-file-structure>`.


Where is my configuration file?
"""""""""""""""""""""""""""""""

To see where your configuration file is located, you can use the following
command

.. code:: bash

    v6 server files

.. warning::
    This command will only work for if the server has been deployed using the
    ``v6`` commands.

    Also, note that on local deployments you may need to specify the
    ``--user`` flag if you put your configuration file in the
    :ref:`user folder <server-configure-location>`.

You can also create and edit this file manually.

.. _server-config-file-structure:

All configuration options
"""""""""""""""""""""""""

The following configuration file is an example that intends to list all possible
configuration options.

You can download this file here: :download:`server_config.yaml <yaml/server_config.yaml>`

.. _server-configuration-file:

.. literalinclude :: yaml/server_config.yaml
    :language: yaml

.. todo this section is close duplicate of docs/node/configure -- merge?

.. _server-configure-location:

Configuration file location
"""""""""""""""""""""""""""

The directory where to store the configuration file depends on your
operating system (OS). It is possible to store the configuration file at
**system** or at **user** level. At the user level, configuration files are only
available for your user. By default, server configuration files are stored at
**system** level.

The default directories per OS are as follows:

+---------+----------------------------+------------------------------------+
| **OS**  | **System**                 | **User**                           |
+=========+============================+====================================+
| Windows | |win_sys|                  | |win_usr|                          |
+---------+----------------------------+------------------------------------+
| MacOS   | |mac_sys|                  | |mac_usr|                          |
+---------+----------------------------+------------------------------------+
| Linux   | |lin_sys|                  | |lin_usr|                          |
+---------+----------------------------+------------------------------------+

.. |win_sys| replace:: ``C:\ProgramData\vantage\server``
.. |win_usr| replace:: ``C:\Users\<user>\AppData\Local\vantage\server``
.. |mac_sys| replace:: ``/Library/Application/Support/vantage6/server``
.. |mac_usr| replace:: ``/Users/<user>/Library/Application Support/vantage6/server``
.. |lin_sys| replace:: ``/etc/xdg/vantage6/server/``
.. |lin_usr| replace:: ``/home/<user>/.config/vantage6/server/``

.. warning::
    The command ``v6 server`` looks in certain directories by default. It is
    possible to use any directory and specify the location with the ``--config``
    flag. However, note that using a different directory requires you to specify
    the ``--config`` flag every time!

    Similarly, you can put your server configuration file in the user folder
    by using the ``--user`` flag. Note that in that case, you have to specify
    the ``--user`` flag for all ``v6 server`` commands.

.. _server-logging:

Logging
"""""""

Logging is enabled by default. To configure the logger, look at the ``logging``
section in the example configuration in :ref:`server-config-file-structure`.

Useful commands:

1. ``v6 server files``: shows you where the log file is stored
2. ``v6 server attach``: show live logs of a running server in your
   current console. This can also be achieved when starting the server
   with ``v6 server start --attach``