[doc] Add deployment docs and update contributing and readme docs

CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 ### Backend
 
-1. Install `python>=3.7`
+1. Install `python>=3.8`
 2. Create a virtual environment with `python3 -m venv .venv`
 3. Activate your dev environment with `source .venv/bin/activate`
 4. Install with `pip install .`
@@ -13,12 +13,13 @@
    `ln -s ../../git-hooks/pre-commit .git/hooks/pre-commit`
 7. Add git-hook to check commmit message format with
    `ln -s ../../git-hooks/commit-msg .git/hooks/commit-msg`
+8. Turn off production mode: `sudo su -c 'echo "production = 0" >> /etc/kibicara.conf'`
 
-#### Build and Test Cycle
+#### Cheatsheet
 
-- Install with `pip install .`
+- Install Kibicara with `pip install .`
-- Execute with `kibicara`
+- Execute Kibicara with `kibicara` (verbose: `kibicara -vvv`)
-- Interact with Swagger REST-API Documentation: http://localhost:8000/docs
+- Interact with Swagger REST-API Documentation: `http://localhost:8000/api/docs`
 - Test and stylecheck with `tox`
 - Fix style issues with `black -S kibicara tests`
 
@@ -29,11 +30,31 @@
 2. `cd kibicara-frontend`
 3. Install the dependencies with `npm i`
 4. Install Angular with `npm i -g @angular/cli`
-5. Turn off production mode with `sudo su -c 'echo "production = 0" >> /etc/kibicara.conf'`
+5. Turn off production mode if you have not already (see above in backend).
 6. Start the backend in a different terminal
-7. To serve and open the application, run ng s -o. The application will open
+7. To serve and open the application, run `ng s -o`. The application will open
    under [http://127.0.0.1:4200](http://127.0.0.1:4200).
 
+### Creating an account
+
+#### Without local mailserver setup
+
+1. Start the server with `kibicara -vvv`.
+2. Got to `http://localhost:8000/api/docs`. Use the `POST /api/admin/register` endpoint to create an account (minimal password size is 8).
+3. Check the log output for a line that contains a link with the token:
+```
+<sometimestamp> kibicara.webapi.admin http://127.0.0.1:4200/confirm?token=<copythistoken>
+```
+4. Paste the token into the `POST /api/admin/confirm/{register_token}` endpoint at `http://localhost:8000/api/docs`.
+5. Done! Try to log in with the `Authorize` button on the page or use the frontend
+
+#### With local mailserver (e.g. openSMTPd)
+
+1. Install the opensmtpd package and start it.
+2. The mails should be usually delivered in `~/Maildir`. Use your unix username as
+email address and register via frontend or manually at `http://localhost:8000/api/docs`.
+
+
 ## Branches
 
 - **Master:** The master branch tracks the last stable release.

DEPLOYMENT.md

@@ -0,0 +1,109 @@
+## Setup on a server
+
+This will guide you through the whole kibicara server setup on a OpenBSD with OpenSMTPd as MTA (+ Relay at `relay.example.com`) and `https://kibicara.example.com` as domain. The kibicara server will also run on other Unix-like systems, just modify the guide to your needs.
+
+Prerequisites:
+- python>=3.8 + pip
+
+### Set up server environment
+- Create a new user: `adduser kibicara`
+- Install packages: `pkg_add git python%3.8 opensmtpd-extras`
+  - (Optional) Create a symlink to python3: `ln -s /usr/local/bin/python3.8 /usr/local/bin/python3`
+- Ensure pip is installed: `python3 -m ensurepip --default-pip`
+- Switch to kibicara user: `su -l kibicara`
+- Add pip packages to PATH by appending it to the `.profile` of user `kibicara` (remember that a new login is needed for it to work). This ensures that you can call kibicara without full path:
+```
+PIP_PACKAGES="${HOME}/.local"
+export PATH="$PATH:$PIP_PACKAGES/bin"
+```
+
+### Build backend on the server
+- Clone the repository: `git clone https://github.com/acipm/kibicara`
+- Install backend: `cd kibicara && pip install --user .`
+
+### Build frontend on your local machine
+Since Angular CLI is quite bloaty and your server may don't have enough resouces, we recommend to build the frontend locally and copying it onto the server. The same steps can be used on the server if it has enough resources.
+
+- Install npm: `pkg_add node`
+- Configure npm to use global install (`-g`) without root
+```
+mkdir "${HOME}/.npm-packages"
+npm config set prefix "${HOME}/.npm-packages"
+```
+- Add npm package path to PATH in `.profile` by appending:
+```
+NPM_PACKAGES="${HOME}/.npm-packages"
+export PATH="$PATH:$NPM_PACKAGES/bin"
+```
+- Install Angular CLI: `npm install -g @angular/cli`
+- Clone repository locally: `git clone https://github.com/acipm/kibicara`
+- Change production settings in `kibicara/kibicara-frontend/src/environments/environment.prod.ts` to use your domain:
+```
+export const environment = {
+  production: true,
+  API_BASE_PATH: 'https://kibicara.example.com',
+  EMAIL_DOMAIN: 'kibicara.example.com',
+};
+```
+- Build frontend with `cd kibicara/kibicara-frontend && ng build --prod`
+- Copy the generated frontend to your server to `/home/kibicara/kibicara-frontend`: `scp -r kibicara/kibicara-frontend/dist/kibicara-frontend <your_server>:/home/kibicara`
+
+### Configure Kibicara Core
+- Write config file to `/etc/kibicara.conf` and replace the domain with yours:
+```
+database_connection = 'sqlite:////home/kibicara/kibicara.sqlite'
+frontend_path = '/home/kibicara/kibicara-frontend'
+frontend_url = 'https://kibicara.example.com'
+```
+
+#### SSL
+You can use the SSL stuff provided by hypercorn by generating an SSL Certificate and passing its paths to the config options `certfile` and `keyfile` in `/etc/kibicara.conf`.
+
+### Configure Kibicara platforms
+
+#### Configure E-Mail (OpenSMTPd + Relay)
+To send and receive e-mails (necessary for registration confirmation and e-mail bot) you will need an MTA. We use OpenSMTPd:
+
+- Configure OpenSMTPd by writing the `/etc/mail/smtpd.conf`. Basically all lines with `kibicara` in it are relavant, if you already have a different setup just copy those.
+```
+table aliases file:/etc/mail/aliases
+table kibicara_mailaddr sqlite:/etc/mail/kibicara_mailaddr.conf
+
+listen on all
+
+action "local_mail" mbox alias <aliases>
+action "outbound" relay host "relay.example.com"
+action "kibicara" mda "/home/kibicara/.local/bin/kibicara_mda %{dest.user}" virtual { "@" => kibicara } user kibicara
+
+match from any for domain "kibicara.example.com" rcpt-to <kibicara_mailaddr> action "kibicara"
+match from any for domain "kibicara.example.com" action "local_mail"
+match from local for local action "local_mail"
+match from local for any action "outbound"
+```
+- Read accepted inbox addresses from the database by configuring `/etc/mail/kibicara_mailaddr.conf`:
+```
+dbpath /home/kibicara/kibicara.sqlite
+query_mailaddr SELECT 1 FROM email WHERE ? IN (name || '@kibicara.example.com');
+```
+- Don't forget to restart OpenSMTPd when you change your database: `rcctl stop && rcctl start`
+
+#### Configure Twitter
+
+Twitter needs you to create a Twitter App, which hood admins can permit to read and write messages.
+
+- Create Twitter account and app: https://developer.twitter.com
+- Get your customer key and customer secret and append this to `/etc/kibicara.conf`:
+```
+[twitter]
+consumer_key = '<your_consumer_key>'
+consumer_secret = '<your_consumer_secret>'
+```
+- You need to configure a Callback Url in your Twitter App:
+  - Go to: `https://developer.twitter.com/en/apps`
+  - Add `https://kibicara.example.com/dashboard/twitter-callback` as Callback Url of your Twitter App. This is needed to successfully create a twitter oauth handshake.
+
+#### Configure Telegram
+Nothing to do, because telegram has a nice API.
+
+### Start Kibicara
+Run `kibicara` with your kibicara user. To have more verbose output add `-vvv`.

README.md

@@ -17,6 +17,10 @@ contain a trigger word to be relayed, and must not contain a bad word.
 Kibicara needs to be hosted on a server by an instance maintainer. That way,
 hood admins don't need a server of their own.
 
+## Deploy Kibicara on a production server
+
+Read `DEPLOYMENT.md` to learn how to deploy Kibicara.
+
 ## Contribute!
 
 Read `CONTRIBUTING.md` to learn how to get started.