Configuration Options

Please note TELSTAR as an application is still under development and subject to change.

There are three different ways to configure TELSTAR;

• configuration file;
• environment variables;
• command line arguments.

Configuration File

The telstar.json configuration file is stored in the containers /opt/telstar/volume directory. This directory is the mount point for the TELSTAR volume (telstar-volume) and is persisted even if the TELSTAR container or TELSTAR image is deleted.

The file can be updated by accessing the container using the docker exec command or by copying the file from the volume, making changes and copying it back.

To copy telstar.json from the volume to the current directory for editing execute the followiing command on the Docker host (note the trailing '.').

# docker cp telstar-server:/opt/telstar/volume/telstar.json .

Update the file with the following command executed on the Docker host.

# docker cp telstar.json telstar-server:/opt/telstar/volume/

Then restart the docker image.

# docker restart telstar-server

Note that for the copy operations above to work, the telstar-server container must be running.

To access the container to edit there, the following command can be used.

docker exec -it telstar-server bash

To edit the file, nano can be used e.g.

nano /opt/telstar/volume/telstar.json

Environment Variables

The settings as defined in telstar.json can be overridden with environment variables. These would typically be defined in the docker run command, the docker-compose yaml file or the container section of a Kubernetes deployment yaml file, for example the following was present in the above docker compose file and updates the similarly names settings in telstar.json.

    environment:
      - TELSTAR_SERVER=AUSTEN

The full list of the settings and there meanings are shown in the sections below.

Command Line Arguments

Command line arguments can be specified on the docker run command for example the following command will override both the telstar.json settings file and the similarly names environment varu=iable.

docker run --rm -d --name telstar-server --network telstar-network -p 6512:6512 -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar server --port=6512 --server=AUSTEN

Details of all command line arguments are shown below.

usage: telstar.py [-h] [--port PORT] [--init] [--install-example] [--dev]
                  [--server SERVER] [--dbcon DBCON]
                  [--dbcollection DBCOLLECTION] [--start-page START_PAGE]
                  [--login-page LOGIN_PAGE]
                  [--main-index_page MAIN_INDEX_PAGE]
                  [--requires-authentication REQUIRES_AUTHENTICATION]
                  [--system-message SYSTEM_MESSAGE] [--parity PARITY]
                  [--plugin-directory PLUGIN_DIRECTORY]
                  application [option]

positional arguments:
  application           specify the application to run e.g. 'server', 'api' or
                        'cron'.
  option                specify any application specific options

optional arguments:
  -h, --help            show this help message and exit
  --port PORT           port to listen on
  --init                run all @init decorated plugin methods
  --install-example     run all @init decorated plugin methods
  --dev                 use the telstar-dev.json settings file instead of
                        telstar,json
  --server SERVER       override the server display name setting
  --dbcon DBCON         override the connection string setting
  --dbcollection DBCOLLECTION
                        override the primary/secondary database setting
  --start-page START_PAGE
                        override the start page setting
  --login-page LOGIN_PAGE
                        override the login page setting
  --main-index_page MAIN_INDEX_PAGE
                        override the main index page setting
  --requires-authentication REQUIRES_AUTHENTICATION
                        override the authenticate setting to require users to
                        be authenticated
  --system-message SYSTEM_MESSAGE
                        override the system message setting
  --parity PARITY       override the parity setting to use seven bit even
                        parity
  --volume-directory VOLUME_DIRECTORY
                        override the directory setting to use for plugins

In addition all of the telstar settings can be specified on the command line see the section Settings in Detail below.

Settings in Detail

The following is a list of settings that can be used to change the behaviour of the system. As mentioned above, all of these settings can be set in telstar.json, via an environment variable or with a command line argument.

Setting: Server Display Name

This sets the display name of the server and appears on the initial page and session page of the example Telstar content.

Configuration File

{
  "server": "ELIOT",
}

Environment Variable

environment:
    - TELSTAR_SERVER=AUSTEN

Command Line Argument

--server=AUSTEN

Setting: Database Connection

This setting holds the mongodb database connection string and will by default be set to access the official mongo Docker image as described in Getting Started.

Configuration File

{
  "dbcon": "mongodb://mongoadmin:secret@telstar-mongo:27017",
}

Environment Variable

environment:
    - TELSTAR_DBCON=mongodb://mongoadmin:secret@telstar-mongo:27017

Command Line Argument

--dbcon

Setting: Database Collection

The database is split into two distinct areas called Primary and Secondary. The dbcollection setting will point TELSTAR at one of these sections. Please not that whilst these are referred to as dbcollections, there is no connection to the mongodb concept of collections.

Configuration File

{
  "dbcollection": "primary",
}

Environment Variable

environment:
    - TELSTAR_DBCOLLECTION=SECONDARY

Setting: Start Page

This is the page number of the start page. This is the page that is loaded when a user first connects to the system.

Configuration File

{
  "start_page": 99,
}

Environment Variable

environment:
    - TELSTAR_START_PAGE=99

Command Line Argument

--start-page

Setting: Login Page

This is the page number of the login page. This is the page that is loaded when authentication is required (see setting requires-authentication). At the time of writing, authentication is experimental and should not be used.

Configuration File

{
  "login_page": 990,
}

Environment Variable

environment:
    - TELSTAR_LOGIN_PAGE=990

Command Line Argument

--login-page

Setting: Main Index Page

This is the page number of the main index page. This is the page that is loaded immediately after the start page (see setting start-page).

Configuration File

{
  "main_index_page": 0,
}

Environment Variable

environment:
    - TELSTAR_MAIN_INDEX_PAGE=0

Command Line Argument

--main-index-page

Setting: Requires Authentication

When set to true, this setting will require all users to be authenticated before accessing the system. At the time of writing, authentication is experimental and should not be used.

Configuration File

{
  "requires_authentication": false,
}

Environment Variable

environment:
    - TELSTAR_REQUIRES_AUTHENTICATION=FALSE

Command Line Argument

--requires-authentication

Setting: System Message

This setting allows for a system message to be added to the last line of all viewdata frames served by the application.

Configuration File

{
  "system_message": "[G]Online",
}

Environment Variable

environment:
    - TELSTAR_SYSTEM_MESSAGE=[Y]Online

Command Line Argument

--system-message

Setting: parity

The system when accessed over the internet would normally be configured for 8 data bits and no parity. This setting when set to true configures the system with 7 data bits and even parity.

Configuration File

{
  "parity": false,
}

Environment Variable

environment:
    - TELSTAR_PARITY=FALSE

Command Line Argument

--parity

Setting: plugin-directory

This setting holds the folder where plugins can be found, see Plugins.

Configuration File

{
  "volume_directory": "/opt/telstar/volume/",
}

Environment Variable

environment:
    - TELSTAR_PLUGIN_DIRECTORY=/opt/telstar/volume/plugins/

Command Line Argument

--volume-directory