262 lines
9.2 KiB
ReStructuredText
262 lines
9.2 KiB
ReStructuredText
.. highlight:: none
|
|
|
|
**********
|
|
Deployment
|
|
**********
|
|
|
|
There are different ways to deploy Notfellchen. We support an ansible+docker based deployment and manual installation.
|
|
|
|
Ansible deployment
|
|
==================
|
|
|
|
Notfellchen can be deployed with the `notfellchen-ansible-role <https://github.com/moan0s/ansible-role-notfellchen>`_ that is based on the
|
|
official Notfellchen docker image. This role will only install notfellchen itself. If you want a complete setup that includes a
|
|
database and a webserver with minimal configuration you can use the
|
|
`mash-playbook <https://github.com/mother-of-all-self-hosting/mash-playbook>`_ by following `it's documentation
|
|
on Notfellchen <https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/notfellchen.md>`_.
|
|
|
|
|
|
|
|
Manual Deployment
|
|
=================
|
|
|
|
|
|
This guide describes the installation of a installation of Notfellchen from source. It is inspired by this great guide from
|
|
pretix_.
|
|
|
|
.. warning:: Even though this guide tries to make it as straightforward to run Notfellchen, it still requires some Linux experience to
|
|
get it right. If you're not feeling comfortable managing a Linux server, check out a managed service_.
|
|
|
|
This guide is tested on **Ubuntu20.04** but it should work very similar on other modern systemd based distributions.
|
|
|
|
Requirements
|
|
------------
|
|
|
|
Please set up the following systems beforehand, it will not be explained here in detail (but see these links for external
|
|
installation guides):
|
|
|
|
* A SMTP server to send out mails, e.g. `Postfix`_ on your machine or some third-party server you have credentials for
|
|
* A HTTP reverse proxy, e.g. `nginx`_ or Traefik to allow HTTPS connections
|
|
* A `PostgreSQL`_ database server
|
|
|
|
Also recommended is, that you use a firewall, although this is not a Notfellchen-specific recommendation. If you're new to
|
|
Linux and firewalls, it is recommended that you start with `ufw`_.
|
|
|
|
.. note:: Please, do not run Notfellchen without HTTPS encryption. You'll handle user data and thanks to `Let's Encrypt`_
|
|
SSL certificates can be obtained for free these days.
|
|
|
|
Unix user
|
|
---------
|
|
|
|
As we do not want to run notfellchen as root, we first create a new unprivileged user::
|
|
|
|
# adduser notfellchen --disabled-password --home /var/notfellchen
|
|
|
|
In this guide, all code lines prepended with a ``#`` symbol are commands that you need to execute on your server as
|
|
``root`` user (e.g. using ``sudo``); all lines prepended with a ``$`` symbol should be run by the unprivileged user.
|
|
|
|
Database
|
|
--------
|
|
|
|
Having the database server installed, we still need a database and a database user. We can create these with any kind
|
|
of database managing tool or directly on our database's shell. Please make sure that UTF8 is used as encoding for the
|
|
best compatibility. You can check this with the following command::
|
|
|
|
# sudo -u postgres psql -c 'SHOW SERVER_ENCODING'
|
|
|
|
For PostgreSQL database creation, we would do::
|
|
|
|
# sudo -u postgres createuser notfellchen
|
|
# sudo -u postgres createdb -O notfellchen notfellchen
|
|
# su notfellchen
|
|
$ psql
|
|
> ALTER USER notfellchen PASSWORD 'strong_password';
|
|
|
|
Package dependencies
|
|
--------------------
|
|
|
|
To build and run notfellchen, you will need the following debian packages::
|
|
|
|
# apt-get install git build-essential python-dev python3-venv python3 python3-pip \
|
|
python3-dev
|
|
|
|
Config file
|
|
-----------
|
|
|
|
We now create a config directory and config file for notfellchen::
|
|
|
|
# mkdir /etc/notfellchen
|
|
# touch /etc/notfellchen/notfellchen.cfg
|
|
# chown -R notfellchen:notfellchen /etc/notfellchen/
|
|
# chmod 0600 /etc/notfellchen/notfellchen.cfg
|
|
|
|
Fill the configuration file ``/etc/notfellchen/notfellchen.cfg`` with the following content (adjusted to your environment)::
|
|
|
|
[notfellchen]
|
|
instance_name=My library
|
|
url=https://notfellchen.example.com
|
|
|
|
[database]
|
|
backend=postgresql
|
|
name=notfellchen
|
|
user=notfellchen
|
|
|
|
[locations]
|
|
static=/var/notfellchen/static
|
|
|
|
[mail]
|
|
; See config file documentation for more options
|
|
; from=notfellchen@example.com
|
|
; host=127.0.0.1
|
|
; user=notfellchen
|
|
; password=foobar
|
|
; port=587
|
|
|
|
[security]
|
|
; See https://securitytxt.org/ for reference
|
|
;Contact=
|
|
;Expires=
|
|
;Encryption=
|
|
;Preferred-Languages=
|
|
;Scope=
|
|
;Policy=
|
|
|
|
Install notfellchen as package
|
|
------------------------
|
|
|
|
Now we will install notfellchen itself. The following steps are to be executed as the ``notfellchen`` user. Before we
|
|
actually install notfellchen, we will create a virtual environment to isolate the python packages from your global
|
|
python installation::
|
|
|
|
$ python3 -m venv /var/notfellchen/venv
|
|
$ source /var/notfellchen/venv/bin/activate
|
|
(venv)$ pip3 install -U pip setuptools wheel
|
|
|
|
We now clone and install notfellchen, its direct dependencies and gunicorn::
|
|
|
|
(venv)$ git clone https://github.com/moan0s/Notfellchen2
|
|
(venv)$ cd Notfellchen2/src/
|
|
(venv)$ pip3 install -r requirements.txt
|
|
(venv)$ pip3 install -e .
|
|
|
|
Note that you need Python 3.6 or newer. You can find out your Python version using ``python -V``.
|
|
|
|
Finally, we compile static files and create the database structure::
|
|
|
|
(venv)$ ./manage.py collectstatic
|
|
(venv)$ ./manage.py migrate
|
|
(venv)$ django-admin compilemessages --ignore venv
|
|
|
|
|
|
Start notfellchen as a service
|
|
-------------------------
|
|
|
|
You should start notfellchen using systemd to automatically start it after a reboot. Create a file
|
|
named ``/etc/systemd/system/notfellchen-web.service`` with the following content::
|
|
|
|
[Unit]
|
|
Description=notfellchen web service
|
|
After=network.target
|
|
|
|
[Service]
|
|
User=notfellchen
|
|
Group=notfellchen
|
|
Environment="VIRTUAL_ENV=/var/notfellchen/venv"
|
|
Environment="PATH=/var/notfellchen/venv/bin:/usr/local/bin:/usr/bin:/bin"
|
|
ExecStart=/var/notfellchen/venv/bin/gunicorn notfellchen.wsgi \
|
|
--name notfellchen --workers 5 \
|
|
--max-requests 1200 --max-requests-jitter 50 \
|
|
--log-level=info --bind=127.0.0.1:8345
|
|
WorkingDirectory=/var/notfellchen
|
|
Restart=on-failure
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
|
|
You can now run the following commands to enable and start the services::
|
|
|
|
# systemctl daemon-reload
|
|
# systemctl enable notfellchen-web
|
|
# systemctl start notfellchen-web
|
|
|
|
|
|
SSL
|
|
---
|
|
|
|
The following snippet is an example on how to configure a nginx proxy for notfellchen::
|
|
|
|
server {
|
|
listen 80;
|
|
listen [::]:80;
|
|
|
|
if ($scheme = http) {
|
|
return 301 https://$server_name$request_uri;
|
|
}
|
|
|
|
#
|
|
listen 443 ssl;
|
|
listen [::]:443 ssl;
|
|
ssl_certificate /etc/letsencrypt/live/notfellchen.example.com/cert.pem;
|
|
ssl_certificate_key /etc/letsencrypt/live/notfellchen.example.com/privkey.pem;
|
|
ssl_protocols TLSv1.2 TLSv1.3;
|
|
ssl_ciphers HIGH:!aNULL:!MD5;
|
|
|
|
|
|
# Set header
|
|
add_header X-Clacks-Overhead "GNU Terry Pratchett";
|
|
add_header Permissions-Policy interest-cohort=(); #Anti FLoC
|
|
add_header Referrer-Policy same-origin;
|
|
add_header X-Content-Type-Options nosniff;
|
|
|
|
server_name notfellchen.example.com;
|
|
location / {
|
|
proxy_pass http://localhost:8345;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto https;
|
|
proxy_set_header Host $http_host;
|
|
}
|
|
|
|
location /static/ {
|
|
alias /var/notfellchen/static/;
|
|
access_log off;
|
|
expires 365d;
|
|
add_header Cache-Control "public";
|
|
}
|
|
}
|
|
|
|
|
|
We recommend reading about setting `strong encryption settings`_ for your web server.
|
|
|
|
Next steps
|
|
----------
|
|
|
|
Yay, you are done! You should now be able to reach notfellchen at https://notfellchen.example.com/
|
|
|
|
Updates
|
|
-------
|
|
|
|
.. warning:: While we try hard not to break things, **please perform a backup before every upgrade**.
|
|
|
|
To upgrade to a new notfellchen release, pull the latest code changes and run the following commands::
|
|
|
|
$ source /var/notfellchen/venv/bin/activate
|
|
(venv)$ git pull
|
|
(venv)$ pg_dump notfellchen > notfellchen.psql
|
|
(venv)$ python manage.py migrate
|
|
(venv)$ django-admin compilemessages --ignore venv
|
|
|
|
# systemctl restart notfellchen-web
|
|
|
|
|
|
.. _Postfix: https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-postfix-as-a-send-only-smtp-server-on-ubuntu-16-04
|
|
.. _nginx: https://botleg.com/stories/https-with-lets-encrypt-and-nginx/
|
|
.. _Let's Encrypt: https://letsencrypt.org/
|
|
.. _MySQL: https://dev.mysql.com/doc/refman/5.7/en/linux-installation-apt-repo.html
|
|
.. _PostgreSQL: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-20-04
|
|
.. _redis: https://blog.programster.org/debian-8-install-redis-server/
|
|
.. _ufw: https://en.wikipedia.org/wiki/Uncomplicated_Firewall
|
|
.. _strong encryption settings: https://mozilla.github.io/server-side-tls/ssl-config-generator/
|
|
.. _service: hyteck.de/services
|
|
.. _pretix: https://docs.pretix.eu/en/latest/admin/installation/manual_smallscale.html
|
|
|