Configuring the Server

In this section you will learn how to configuring the server to your needs. This can be done either through the command line or by creating a custom yaml configuration file.

It is assumed that the joey Python package has been successfully installed. If not, have a look at previous steps described in Install VANTAGE6.

Using the Wizard

The most straight forward way of creating a new server configuration is using the command vserver new which allows you to configure the most basic settings.

Configure a new server using the wizard

By default the configuration-file is stored at system level, which makes this configuration available for all users. In case you want to use a user directory you can add the --user flag.

To update a configuration you need to modify the created YAML file. To see where this file is located you can use thevserver files . Do not forget to specify the --system flag in the case of a system-wide configuration.

Using a custom YAML file

The configuration wizard outputs a YAML file which can be loaded into joey. It is also possible to create this YAML file yourself, to see the stucture of this file please see out github or Configuring the Server. This file can be stored (and refered to) at any location at the machine, although it is recommended to use either the joey system or user folder. This folder is different for different operating systems.

System

User

Windows

C:\ProgramData\joey\server

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

MacOS

Linux

Make sure that the uri is understood by SQLAlchemy, see here for more information.

Starting the server

Once the configuration is done, you can start the server instance by using vserver start and then selecting the configuration you want to use. Or if you already know the name of the configuration you can use the --name flag to specify it. If you have a configuration file which is in a non-default location than you can specify this by the --config flag.

Note that having Docker installed is not strictly necessary to run the server. However, it is needed if you want to run a private registry on the same machine. See [[Installation of Docker]] for details.

Importing / Creating Entities

Now that the server has been started it is time to populate the server with users, organizations, collaborations, etc. Before you can manage these through the RESTful API interface (which is the prevered way of doing this) it is required that you create at least one organization with an admin user.

It is possible to import multiple organizations, collaborations, etc. at the same time by using the command vserver import [file] . After which you will be asked to which server instance you want to add these entities (or you can use the --name option to bypass this). Another method of creating new entities is by starting an iPhyton session by using vserver shell in which you can directly use the python API.

Using Import

To see the structure of this YAML file please see our github page. Once you have created this file containing your entities, you can import these by

vserver import /path/to/your/file.yaml

Using Shell

By using the shell you can access all database models which are stored in the variable db . Start the shell by running:

vserver shell

This will first start up the server, after which you will be able to use the iPython console.

Starting the REPL will allow you to directly interact with the database models

To add an user you first we first need an organization:

organization = db.Organization(
name="test",
domain = "example.org",
address = "Somestreet 3",
zipcode = 1234,
country = "Far away"
)
organization.save()

The .save() is required to store it in the database. Then we can assign a new user to this organization by:

user = db.User(
username="unique-username",
firstname="John",
lastname="Doe",
roles=["admin"],
organization=organization
)
user.set_password("Super-secret-password!")
user.save()

Note that we can not set the password direct, as it should be encrypted first.

Server Commands

In the section above we several times made use of the vserver command. The following sub-commands are available to manage the server(s). These commands can also be found by simply calling vserver .

Command

Description

vserver files

List the file locations of the server instance

vserver import

Import server entities as a batch

vserver list

List the available server instances

vserver new

Create a new server configuration

vserver shell

Run a server instance python shell

vserver start

Start a server configuration

Configuration File Structure

Each server instance (configuration) can have multiple environments. If you do not want to specify any environment you should only specify the key application . In case you do want to use environments you can specify this in environments which allows four types: dev , test,acc and prod . It should look like this:

application:
...
environments:
test:
description: Test
type: test
ip: '127.0.0.1'
port: 5000
api_path: /api
uri: sqlite:///test.sqlite
allow_drop_all: True
logging:
level: DEBUG
file: test.log
use_console: True
backup_count: 5
max_size: 1024
format: "%(asctime)s - %(name)-14s - %(levelname)-8s - %(message)s"
datefmt: "%Y-%m-%d %H:%M:%S"
prod:
...

Logging

If logging to the console is enabled, starting the server or loading the fixtures should output some information that can be helpful in determining the cause of problems. For example, the output below shows:

  • Which environment was used

  • What configuration file was used

  • Which database was used (and its location)

################################################################################
# pytaskmanager #
################################################################################
Started application 'pytaskmanager' with environment 'test'
Current working directory is '/home/melle'
Succesfully loaded configuration from '/home/melle/.config/pytaskmanager/server/default.yaml'
Logging to '/home/melle/.cache/pytaskmanager/log/server/default.log'
Initializing the database
driver: sqlite
host: None
port: None
database: /home/melle/.local/share/pytaskmanager/server/default/test.sqlite
username: None
Database initialized!