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

```sh
$ apt install curl gpg jq
```

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

```sh
$ 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`

```sh
$ 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`.

```sh
$ apt install yq
```

Once installed, `yq` should appear in your environment.

```sh
$ which yq
/usr/bin/yq
```

## Installation

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

```sh
$ 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*

```sh
$ 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`.

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

Your new directory should look like this:

```sh
$ 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.

```sh
$ 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:

```sh
$ 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.