Admin Documentation

This part of the documentation shows how to install & maintain the Verfassungsbooks Server & Rendering Server(s).

Set up CA for mTLS

We are using mTLS to secure the connection between the main server and the rendering servers. You will have to set up your own Certificate Authority (CA) and create a certificate for each server. All servers with a certificate from the same CA will be able to communicate with each other. Do not use a certificate from an CA you don't own! 

Preparations

1. Install openssl

apt install openssl on ubuntu/debian based systems

pacman -Syu openssl on archlinux based systems

2. Create a new directory for your CA and cd into it:

mkdir my-ca && cd my-ca

3. Create CA config

Create a new file ca.conf with this content:

[ca]
default_ca = default

[default]
dir = .
certs = $dir
new_certs_dir = $dir/db.certs

database = $dir/db.index
serial = $dir/db.serial

certificate = $dir/root.crt
private_key = $dir/root.key

default_days = 365
default_crl_days = 30

default_md = sha256

preserve = no
policy = default_policy

[default_policy]
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = supplied
organizationalUnitName = supplied
commonName = supplied
emailAddress = optional

[crl_ext]
authorityKeyIdentifier=keyid:always

[ usr_cert ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth, serverAuth
authorityKeyIdentifier = keyid,issuer
subjectKeyIdentifier = hash
subjectAltName = $ENV::SAN

4. Initialize CA directories and files

mkdir -p db.certs input output
touch db.index
echo "01" > db.serial

5. Generate CA private key & cert

openssl ecparam -name prime256v1 -genkey -noout -out root.key
openssl req -new -x509 -key root.key -out root.crt -days 3650 -sha256

Important: keep all private keys secure, especially the CA private key!
If leaked, anyone can connect to your main / rendering server.

6. Generate certificate revocation list & convert to correct format

export SAN="DNS:<hostname>"
openssl ca -config ca.conf -gencrl -out crl.pem
openssl crl -in crl.pem -out crl.der -outform DER

Create & Sign certificates

You successfully set up your own CA, now you can create and sign certificates for each of your servers.

On each server: Generate the private key & certificate signing request:

openssl ecparam -name prime256v1 -genkey -noout -out client.key
openssl req -new -key client.key -out client.csr -sha256

Make sure to use a different common name for each certificate! Also make sure to supply an organizationalUnitName.

Transfer the .csr file to the system with your CA certificate. 

On the CA host:

Set the SAN & sign with your CA. Replace <hostname> with your server's hostname! Adjust the file names if needed.

export SAN="DNS:<hostname>"
openssl ca -config ca.conf -in client.csr -out client.crt -days 3650 -extensions usr_cert

Transfer the created certificate (e.g. client.crt) back to the server.

Installation

Main Server

You can either build the application from source or use a prebuilt binary (only linux x64).

Preparation

PostgreSQL Database

WIP

Getting up and running

Build from Source

At least version 1.85 of cargo is required. Try using rustup instead of your distributions packages if you're running into issues.

  1. You will need to have rustc, openssl, pkg-config, cargo and npm installed & in your path
  2. Clone the repository: git clone https://github.com/Verfassungsblog/PublishGoods .
  3. Install typescript requirements: npm install -g handlebars typescript@5.9.3 webpack webpack-cli
  4. cd into typescript & run: cd typescript && npm install
  5. Build with cargo: cd ../ && cargo build --release
  6. Run with cargo run or with target/release/PublishGoods

Use a prebuilt binary

  1. Download the latest release from GitHub
  2. extract the archive: tar -xf verfassungsbooks-bundled.tar.gz
  3. Run with ./PublishGoods (or create a systemd service)

Adjust Configuration

You can adjust the binding address & port in the Rocket.toml.

You will always need to generate a secret_key. Furthermore, you may use this one-liner:

sed -i "s|secret_key *= *\"\"|secret_key= \"$(openssl rand -base64 32)\"|" Rocket.toml

All other configuration options are located in the config folder.


Add mtls certificates

Example Systemd Service File

To register the server as a systemd service with autostart and running in the background you may use this service file (save as /etc/systemd/system/publishgoods-server.service)

[Unit]
Description=Publishgoods Server
After=network.target

[Service]
WorkingDirectory=/home/verfassungsbooks/verfassungsbooks-server
# or ExecStart=/home/verfassungsbooks/verfassungsbooks-server/target/release/Verfassungsbooks when building from source
ExecStart=/home/verfassungsbooks/verfassungsbooks-server/Verfassungsbooks
Restart=always
User=verfassungsbooks

[Install]
WantedBy=multi-user.target

You will need to create a user verfassungsbooks (or change the username in the service file) and change the WorkingDirectory to the directory your installation files lye in. Then adjust the ExecStart so it points to the executable (Verfassungsbooks or target/release/Verfassungsbooks). 

Make sure that the user running the server has write permissions in the data directory!

Now you can start the server with systemctl start publishgoods-server. Logs are redirected to your journal (use journalctl -xe).

Rendering Server

Requirements

For weasyprint you will need to install these requirements:

Ubuntu:

apt install python3-pip libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 libharfbuzz-subset0

Docker-Compose Setup (recommended)

The easiest way to spin up a Publish Goods instance and a rendering server is our docker-compose setup.

WIP