Configuration

SSVP is very versatile, and designed to run in a wide variety of environments.

Configuration file

The SSVP configuration file must be stored at srv/ssvp-config.json. A new one can be created by:

• Manually entering the options seen below

• Running python3 installer/gen_config.py

• Copying and editing srv/ssvp-config.json.example

The file options are:

• enable_host_ipv6: Determines whether to enable IPv6 support. On non-Linux OSes, having this option enabled may disable IPv4 support. (optional)

  • Allowed values: true, false

• hostname: hostname for RSS and other services (optional)

  • If specified, this should be of the form (protocol)://(hostname)[: port]

• ssl: Determines SSL support, and configuration settings.

  • Allowed values:

    • null: disables SSL

    • ["/path/to/cert.pem", "/path/to/key.pem"]: uses existing certificates/keyfiles

    • "adhoc": Uses self-signed/ad-hoc certificates

• port: Port number for the SSVP server (optional)

  • Allowed values: any integer from 1 to 65535 (note: 1-1024 require root/sudo)

• instance_name: Name put in the navbar brand for the instance

  • Allowed values: any string

• splash: Splash text for the main page (optional)

  • Allowed values: any string

• servers: List of servers, set as an object

  • Allowed values: must fit the following schema:

    "name_of_server": {
        "ip": "ip address (url for http)",
        "module": "testing module name",
        "args": "list of module arguments"
    }
    

  • The module can be one of ping, http, tcp, ssvplwc

• services: List of services, set as an object

  • Allowed values: must fit the servers schema

• database: Database information

  • Note: the only options required on sqlite3 are host, type, and prefix

  • type: database type

    • Either mysql, postgres, sqlite3

  • host: database host IP/sqlite3 file path

    • Valid IPv4 or IPv6 address

  • port: database port

    • Valid TCP port (unix sockets are not supported)

  • username: database username

  • password: database password

  • database: name of database in the DB system

  • prefix: prefix for tables

• contact: user contact information (optional)

  • name: user’s name, display name, or organization name

  • mastodon: mastodon profile (format: @username@home.server)

  • github: GitHub profile (just the username)

  • git: link to custom git server

  • email: email address

• docs: set to "local" to use local documentation instead of GitHub Pages

Systemd

If you’re using systemd, there’s four main options:

• Enabling: setting a unit to run at boot (systemctl enable unit_name)

• Disabling: removing a unit from the at-boot list (systemctl disable unit_name)

• Starting: launching a unit for the current boot (systemctl start unit_name)

• Stopping: stopping a unit for the current boot (systemctl stop unit_name)

  It should be noted that, to start a unit at the same time as enabling it, you should pass the --now flag, as in systemctl enable --now unit_name

SSVP uses three main units for operation:

• ssvp-gunicorn.service: Production web server

• ssvp-werkzeug.service: Development web server

• ssvp-interval.timer: Server uptime checking timer

Some important notes:

1. ssvp-gunicorn.service and ssvp-werkzeug.service should not be run at the same time; you only need one web server. If you try and run both at once, systemd will kill the first one.

2. For those with some experience in systemd, it is very important that ssvp-interval.timer not have its suffix left off (running as systemctl start ssvp-interval). Doing so will just run the server uptime checker just once, and not periodically.

3. Do not remove ssvp-interval.service; it gets called by ssvp-interval.timer.

So, for instance, to set up a standard configuration:

systemctl enable --now ssvp-gunicorn.service
systemctl enable --now ssvp-interval.timer