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

3.7.1. 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 example configuration file.

3.7.2. Where is my configuration file?#

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

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

You can also create and edit this file manually.

3.7.3. All configuration options#

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

You can download this file here: server_config.yaml

# Human readable description of the server instance. This is to help
# your peers to identify the server
description: Test

# Human readable name of the server instance. This can help users identify
# the server quickly. It's used for example in the TOTP issuer for 2FA.
server_name: demo

# IP adress to which the server binds. In case you specify 0.0.0.0
# the server listens on all interfaces
ip: 0.0.0.0

# Port to which the server binds
port: 5000

# API path prefix. (i.e. https://yourdomain.org/api_path/<endpoint>). In the
# case you use a referse proxy and use a subpath, make sure to include it
# here also.
api_path: /api

# Let the server know where it is hosted. This is used as a setting to
# communicate back and forth with other vantage6 components such as the
# algorithm store.
# Example for the cotopaxi server
server_url: https://cotopaxi.vantage6.ai
# Example for running the server locally with default settings:
# server_url: http://localhost:5000

# The URI to the server database. This should be a valid SQLAlchemy URI,
# e.g. for an Sqlite database: sqlite:///database-name.sqlite,
# or Postgres: postgresql://username:password@172.17.0.1/database).
uri: sqlite:///test.sqlite

# This should be set to false in production as this allows to completely
# wipe the database in a single command. Useful to set to true when
# testing/developing.
allow_drop_all: True

# Enable or disable two-factor authentication. If enabled, users will be
# presented with a QR-code to scan with their phone the first time they log in.
two_factor_auth: true

# The secret key used to generate JWT authorization tokens. This should
# be kept secret as others are able to generate access tokens if they
# know this secret. This parameter is optional. In case it is not
# provided in the configuration it is generated each time the server
# starts. Thereby invalidating all previous distributed keys.
# OPTIONAL
jwt_secret_key: super-secret-key! # recommended but optional

# Settings for the logger
logging:
  # Controls the logging output level. Could be one of the following
  # levels: CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET
  level: DEBUG

  # Filename of the log-file, used by RotatingFileHandler
  file: test.log

  # Whether the output is shown in the console or not
  use_console: True

  # The number of log files that are kept, used by RotatingFileHandler
  backup_count: 5

  # Size in kB of a single log file, used by RotatingFileHandler
  max_size: 1024

  # format: input for logging.Formatter,
  format: "%(asctime)s - %(name)-14s - %(levelname)-8s - %(message)s"
  datefmt: "%Y-%m-%d %H:%M:%S"

  # (optional) set the individual log levels per logger name, for example
  # mute some loggers that are too verbose.
  loggers:
    - name: urllib3
      level: warning
    - name: socketIO-client
      level: warning
    - name: engineio.server
      level: warning
    - name: socketio.server
      level: warning
    - name: sqlalchemy.engine
      level: warning
    - name: requests_oauthlib.oauth2_session
      level: warning

# Additional debug flags
debug:
  # Set to `true` to enable debug mode for the socketio server
  socketio: false

  # Set to `true` to enable debug mode in the Flask app
  flask: false

# Configure a smtp mail server for the server to use for administrative
# purposes. e.g. allowing users to reset their password.
# OPTIONAL
smtp:
  port: 587
  server: smtp.yourmailserver.example.com
  # credentials for authenticating with the SMTP server
  username: your-username
  password: super-secret-password
  # email address to send emails from (header)
  # (defaults to noreply@vantage6.ai)
  email_from: noreply@example.com

# Set an email address you want to direct your users to for support
# (defaults to support@vantage6.ai)
support_email: your-support@example.com

# set how long reset token provided via email are valid (default 1 hour)
email_token_validity_minutes: 60

# set how long tokens and refresh tokens are valid (default 6 and 48
# hours, respectively)
token_expires_hours: 6
refresh_token_expires_hours: 48

# If you have a server with a high workload, it is recommended to use
# multiple server instances (horizontal scaling). If you do so, you also
# need to set up a RabbitMQ message service to ensure that the communication
# between the server and the nodes is handled properly. Then, fill out the
# RabbitMQ connection URI below to connect the server to it. Also, set the
# start_with_server flag to true to start RabbitMQ when you start the server.
rabbitmq:
  uri: amqp://myuser:mypassword@myhostname:5672/myvhost
  start_with_server: false

# If algorithm containers need direct communication between each other
# the server also requires a VPN server. (!) This must be a EduVPN
# instance as vantage6 makes use of their API (!)
# OPTIONAL
vpn_server:
  # the URL of your VPN server
  url: https://your-vpn-server.ext

  # OATH2 settings, make sure these are the same as in the
  # configuration file of your EduVPN instance
  redirect_url: http://localhost
  client_id: your_VPN_client_user_name
  client_secret: your_VPN_client_user_password

  # Username and password to acccess the EduVPN portal
  portal_username: your_eduvpn_portal_user_name
  portal_userpass: your_eduvpn_portal_user_password

# specify custom Docker images to use for starting the different
# components.
# OPTIONAL
images:
  server: harbor2.vantage6.ai/infrastructure/server:cotopaxi
  ui: harbor2.vantage6.ai/infrastructure/ui:cotopaxi

# options for starting the User Interface when starting the server
ui:
  # set this to true to start the UI when starting the server with
  # `v6 server start`
  enabled: true

  # port at which the UI will be available on your local machine
  port: 3456

# set password policies for the server
password_policy:
  # maximum number of failed login attempts before the user is locked out for
  # a certain amount of time. Default is 5.
  max_failed_attempts: 5

  # number of minutes the user is locked out after the maximum number of failed
  # login attempts is reached. Default is 15.
  inactivation_minutes: 15

  # number of minutes to wait between emails sent to the user for each of the following events:
  #  - their account has been blocked (max login attempts exceeded)
  #  - a password reset request via email
  #  - a 2FA reset request via email
  # (these events have an independent timer). Default is 60.
  between_user_emails_minutes: 60

# set up with which origins the server should allow CORS requests. The default
# is to allow all origins. If you want to restrict this, you can specify a list
# of origins here. Below are examples to allow requests from the Cotopaxi UI, and
#  port 3456 on localhost
cors_allowed_origins:
  - https://portal.cotopaxi.vantage6.ai
  - http://localhost:3456

# development mode settings. Only use when running both the server and the algorithm
# store that it communicates with locally
dev:
  # Specify the URI to the host. This is used to generate the correct URIs to
  # communicate with the algorithm store. On Windows and Mac, you can use the special
  # hostname `host.docker.internal` to refer to the host machine. On Linux, you
  # should normally use http://172.17.0.1.
  host_uri: http://host.docker.internal

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

C:\ProgramData\vantage\server

C:\Users\<user>\AppData\Local\vantage\server

MacOS

/Library/Application/Support/vantage6/server

/Users/<user>/Library/Application Support/vantage6/server

Linux

/etc/xdg/vantage6/server/

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

3.7.5. Logging#

Logging is enabled by default. To configure the logger, look at the logging section in the example configuration in All configuration options.

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