skald/skald-install.md

Skald installation instructions

Basic installation

Build the Skald binary

Say:

CGO_ENABLED=0 go build -ldflags='-s -w'

On Windows, say:

set CGO_ENABLED=0
go build -ldflags="-s -w"

If your server has a different architecture than the machine on which you are building, set the GOOS and GOARCH environment variables. For example, in order to compile for a 64-bit ARM system (a Raspberry Pi or an Olimex board, for example), you would say:

CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags='-s -w'

Deploy to your server

The following instructions assume that your server is called skald.example.org and that you have already created a dedicated user called skald.

First, make sure that the halls and data directories exist:

mkdir halls data

Now copy the skald binary, and the directories static, data and halls to the server:

rsync -a skald static data halls skald@skald.example.org:

If you don't have a TLS certificate, Skald will generate a self-signed certificate (and print a warning to the logs). If you have a certificate, install it in the files data/cert.pem and data/key.pem:

ssh skald@skald.example.org
sudo cp /etc/letsencrypt/live/skald.example.org/fullchain.pem data/cert.pem
sudo cp /etc/letsencrypt/live/skald.example.org/privkey.pem data/key.pem
sudo chown skald:skald data/*.pem
chmod go-rw data/key.pem

Since certificates are regularly rotated, this should be done in a monthly cron job or a systemd timer unit.

Run Skald on the server

Arrange to run the binary on the server. If you never reboot your server, just do:

ssh skald@skald.example.org
ulimit -n 65536
nohup ./skald &

If you are using runit, use a script like the following:

#!/bin/sh
exec 2>&1
cd ~skald
ulimit -n 65536
exec setuidgid skald ./skald

If you are using SystemD, put the following in /etc/systemd/system/skald.service (and then run systemctl daemon-reload):

[Unit]
Description=Skald
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/skald
User=skald
Group=skald
ExecStart=/home/skald/skald
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Set up skaldctl

The skaldctl utility administers a Skald instance by editing its JSON files locally. Run it on the server as a user that may write the Skald data/ and halls/ directories. It does not connect to Skald over HTTPS.

Build the skaldctl utility, and copy it somewhere on your path:

cd skaldctl
go build -ldflags='-s -w'
sudo cp skaldctl /usr/local/bin/

Create the initial server configuration file:

skaldctl initial-setup

If Skald uses directories other than ./data and ./halls, pass them before the command name. For example, packages that use /var/lib/skald can be administered with:

sudo -u skald skaldctl -data /var/lib/skald/data -halls /var/lib/skald/halls initial-setup

Hall setup

For a guided setup, create a hall interactively:

skaldctl create-hall -interactive

This asks for the hall name, common hall settings, operator accounts, and an optional shared participant password. To create a minimal hall without prompts, use:

skaldctl create-hall -hall city-watch

Create an "op", a user with hall moderation privileges:

skaldctl create-user -hall city-watch -user Username -permissions op

Set the new user's password:

skaldctl set-password -hall city-watch -user Username

You should now be able to test your Skald installation by pointing a web browser at https://skald.example.org:8443/hall/city-watch/.

Create an ordinary user:

skaldctl create-user -hall city-watch -user Participant
skaldctl set-password -hall city-watch -user Participant

Check the results:

skaldctl list-halls
skaldctl list-users -l -hall city-watch

Type skaldctl -help, skaldctl create-hall -help, etc. for more information.

Recording dependency

Skald recordings are single mixed Ogg Opus audio files. Recording requires ffmpeg on the server:

ffmpeg -version

If ffmpeg is missing or cannot be started, Skald reports a recording error to the operator instead of creating a partial recording.

Advanced configuration

Skald is designed to be exposed directly to the Internet. If your server is behind a firewall or NAT router, some extra configuration is necessary.

Running behind a firewall

If your server is behind a firewall but has a global IPv4 address (it is not behind NAT), then, at the very minimum, the firewall must allow incoming connections to:

• TCP port 8443 (or whatever is configured with the -http option); and

• TCP and UDP port 1194 (or whatever is configured with the -turn option).

For good performance, your firewall should allow incoming and outgoing traffic from the UDP ports used for media transfer. By default, these are all high-numbered (ephemeral) ports, but they can be restricted using one of the following options:

• the -udp-range port1-port2 option restricts the UDP ports to be in the range from port1 to port2 inclusive; this should be a large range, on the order of a few tens of thousands of ports;

• the -udp-range port option makes the server use just a single port, and demultiplex the traffic in userspace.

At the time of writing, this mechanism is not quite complete, and you will see Skald attempting to use other ports. Unless you see connection failures, this is nothing to worry about.

Running behind NAT

If your server is behind NAT, then currently the only option is to use a STUN, or, preferably, TURN server on a separate host, one that is not behind NAT. See Section Connectivity issues and ICE servers below.

Skald has some support for running behind NAT without a helpful server, but this has not been exhaustively tested. Please see the section "Connectivity issues and ICE servers" below.

Running behind a reverse proxy

Skald is designed to be directly exposed to the Internet. In order to run Skald behind a reverse proxy, you might need to make a number of tweaks to your configuration.

First, you might need to inform Skald of the URL at which users connect (the reverse proxy's URL) by adding an entry proxyURL to your data/config.json file:

{
    "proxyURL": "https://skald.example.org/"
}

Second, and depending on your proxy implementation, you might need to proxy normal Skald paths such as /hall/ and /skald-api/, and pass WebSocket handshakes to the URL at ws; for example, with Nginx, you will need to say something like the following:

location /hall/ {
    proxy_pass https://localhost:8443/hall/;
    proxy_set_header Host $http_host;
}

location /skald-api/ {
    proxy_pass https://localhost:8443/skald-api/;
    proxy_set_header Host $http_host;
}

location /ws {
    proxy_pass https://localhost:8443/ws;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $http_host;
}

Finally, in order to avoid TLS termination issues, you may want to run Skald over plain HTTP instead of HTTPS by using the command-line flag -insecure.

Note that even if you're using a reverse proxy, clients will attempt to establish direct UDP flows with Skald and direct TCP connections to Skald's TURN server; see the section Configuring your firewall above.

Connectivity issues and ICE servers

Most connectivity issues are due to an incorrect ICE configuration.

ICE is the NAT and firewall traversal protocol used by WebRTC. ICE can make use of two kinds of servers to help with NAT traversal: STUN servers, that help punching holes in well-behaved NATs, and TURN servers, that serve as relays for traffic. TURN is a superset of STUN: no STUN server is necessary if one or more TURN servers are available.

Skald includes an IPv4-only TURN server, which is controlled by the -turn command-line option. It has the following behaviour:

• if its value is set to the empty string "", then the built-in server is disabled; in this case, the file data/ice-servers.json configures an external TURN server;

• if its value is a colon followed with a port number, for example :1194, then the TURN server will listen on all public IPv4 addresses of the local host, over UDP and TCP; this is the recommended value if the server is not behind NAT, and the firewall allows incoming connections to the TURN port.

• if the value of this option is a socket address, such as 203.0.113.1:1194, then the TURN server will listen on all addresses of the local host but assume that the address seen by the clients is the one given in the option; this may be useful when running behind NAT with port forwarding set up.

• the default value is auto, which behaves like :1194 if there is no data/ice-servers.json file, and like "" otherwise.

If the server is not accessible from the Internet, e.g. because of NAT or because it is behind a restrictive firewall, then you should configure a TURN server that runs on a host that is accessible by both Skald and the clients. Disable the built-in TURN server (-turn "" or the default -turn auto), and provide a working ICE configuration in the file data/ice-servers.json. In the case of a single STUN server, it should look like this:

[
    {
        "urls": [
            "stun:stun.example.org"
        ]
    }
]

In the case of a single TURN server, the ice-servers.json file should look like this:

[
    {
        "urls": [
            "turn:turn.example.org:443",
            "turn:turn.example.org:443?transport=tcp"
        ],
        "username": "skald",
        "credential": "secret"
    }
]

It is more secure to use coturn's use-auth-secret option. If you do that, then the ice-servers.json file should look like this:

[
    {
        "urls": [
            "turn:turn.example.org:443",
            "turn:turn.example.org:443?transport=tcp"
        ],
        "username": "skald",
        "credential": "secret",
        "credentialType": "hmac-sha1"
    }
]

For redundancy, you may set up multiple TURN servers, and ICE will use the first one that works. If an ice-servers.json file is present and Skald's built-in TURN server is enabled, then the external server will be used in preference to the built-in server.