hotpocket/docs/debian_11.md

NOTE: This is out of date and will need to be updated.

Debian 11 Install Guide for hotpocket

The following guide is intended for Debian or debian-like (Ubuntu) distributions. Non-debian users may follow this guide as well, but they may need to perform additional steps during setup.

Dependencies

Hotpocket requires curl, mktemp, gpg, jq, and yq to run.

mktemp should already be available on your system. You can install curl, gpg, and jq from the debian repository

$ apt install curl gpg jq

curl, gpg, and jq should now appear in your environment.

$ which curl gpg jq
/usr/bin/curl
/usr/bin/gpg
/usr/bin/jq

To install yq, the yq developers suggest you use a an ubuntu ppa. You may also install yq through pip3 by running pip3 install yq

$ apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9a2d61f6bb03ced7522b8e7d6657dbe0cc86bb64
$ echo 'http://ppa.launchpad.net/rmescandon/yq/ubuntu focal main' > /etc/apt/sources.list.d/rmescandon-ubuntu-yq-focal.list

Running apt update should now show the PPA among your sources.

$ apt update
Get:1 http://ppa.launchpad.net/rmescandon/yq/ubuntu focal InRelease [18.0 kB]
Hit:2 http://deb.debian.org/debian bullseye InRelease
Hit:3 http://security.debian.org/debian-security bullseye-security InRelease
Hit:4 http://deb.debian.org/debian bullseye-updates InRelease
Get:5 http://ppa.launchpad.net/rmescandon/yq/ubuntu focal/main amd64 Packages [488 B]
Get:6 http://ppa.launchpad.net/rmescandon/yq/ubuntu focal Translation-en [264 B]
Fetched 18.8 kB in 1s (29.1 kB/s)

You should now be able to install yq.

$ apt install yq

Once installed, yq should appear in your environment.

$ which yq
/usr/bin/yq

Installation

Create a hotpocket user, and a hotpocket-data group.

$ groupadd hotpocket-data -r
$ useradd hotpocket -g hotpocket-data -d /etc/hotpocket -s /usr/sbin/nologin -MNr

You can check /etc/passwd and /etc/shadow to make sure that the user is properly configured.

The UID of the hotpocket user will likely be different

$ cat /etc/passwd | grep hotpocket
hotpocket:x:998:998::/etc/hotpocket:/usr/sbin/nologin
$ cat /etc/shadow | grep hotpocket
hotpocket:!:19020::::::
$ groups hotpocket
hotpocket : hotpocket-data

Next, create the hotpocket directory in etc.

$ mkdir /etc/hotpocket
$ chown root:hotpocket-data /etc/hotpocket
$ chmod 750 /etc/hotpocket

Your new directory should look like this:

$ ls -l /etc | grep hotpocket
drwxr-x--- 2 root hotpocket-data  4096 Jan 28 05:50 hotpocket

Next, copy in the supplied config.yaml, secrets.yaml, and hotpocket.sh. You do not need to copy mkpolicy.sh, you may store that elsewhere.

$ cd /etc/hotpocket
$ cp /mnt/hotpocket/*.yaml /mnt/hotpocket/hotpocket.sh .
$ touch keyring.gpg
$ chown root:hotpocket-data *
$ chmod 640 *
$ chmod 650 hotpocket.sh

Your file permissions should look like this:

$ ls -l
drw-r----- 1 root hotpocket-data  218 Jan 28 05:52 config.yaml
drw-r-x--- 1 root hotpocket-data 5671 Jan 28 05:52 hotpocket.sh
drw-r----- 1 root hotpocket-data    0 Jan 28 05:52 keyring.gpg
drw-r----- 1 root hotpocket-data   55 Jan 28 05:52 secrets.yaml

Next, we're going to want to change some values in config.yaml and secrets.yaml.

You'll need to change base_url, synapse_base_url, and policy_rooms to sensible values. Ensure that the base_url and synapse_base_url do not end with /.

You will also need to create a synapse admin account for hotpocket to use, then to fill in the access_token in secrets.yaml. Do not include the "Bearer " prefix!

Once done, you can begin setting up your keyring.

Keyring setup

Hotpocket requires policies to be signed, hotpocket uses gpg to validate any policies it finds in your defined policy rooms.

As the user which owns keyring.gpg (root in this case), add Jon's public key to the keyring.

$ # The hotpocket archive should include the `jon_at_glowers_club.asc` public key.
$ gpg --no-default-keyring --keyring "$PWD/keyring.gpg" --import /mnt/hotpocket/jon_at_glowers_club.asc
gpg: key 1A4A0CC4CE53281B public key "Jonathan (@jon:glowers.club) <[email protected]>" imported
gpg: Total number processed: 1
gpg:               imported: 1
$ gpg --no-default-keyring --keyring "$PWD/keyring.gpg" --list-keys
./keyring.gpg
-------------
pub   rsa4096 2022-01-27 [SC] [expires: 2025-01-11]
      5C5E17B334E084FE822007D71A4A0CC4CE53281B
uid           [ unknown] Jonathan (@jon:glowers.club) <[email protected]>
sub   rsa5096 2022-01-27 [E] [expires: 2025-01-11]

At this stage you may also wish to import your own public key, or the public keys of other policy rooms admins.