From 7219575b84885d80d032f636e391fd5e79f0fc12 Mon Sep 17 00:00:00 2001 From: Raphael Michel Date: Fri, 23 Nov 2018 23:12:54 -0600 Subject: [PATCH] Fix #1066 -- Change installation tutorials to PostgreSQL This is the recommended database server so this documentation should use that --- doc/admin/installation/docker_smallscale.rst | 45 ++++++++++++------ doc/admin/installation/manual_smallscale.rst | 48 ++++++++++++-------- 2 files changed, 61 insertions(+), 32 deletions(-) diff --git a/doc/admin/installation/docker_smallscale.rst b/doc/admin/installation/docker_smallscale.rst index cada3fb78..856b15399 100644 --- a/doc/admin/installation/docker_smallscale.rst +++ b/doc/admin/installation/docker_smallscale.rst @@ -58,16 +58,29 @@ Database -------- Next, we 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, e.g. for MySQL:: +our database's shell. For PostgreSQL, we would do:: - $ mysql -u root -p - mysql> CREATE DATABASE pretix DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci; - mysql> GRANT ALL PRIVILEGES ON pretix.* TO pretix@'localhost' IDENTIFIED BY '*********'; - mysql> FLUSH PRIVILEGES; + # sudo -u postgres createuser -P pretix + # sudo -u postgres createdb -O pretix pretix -Replace the asterisks with a password of your own. For MySQL, we will use a unix domain socket to connect to the -database. For PostgreSQL, be sure to configure the interface binding and your firewall so that the docker container -can reach PostgreSQL. +Make sure that your database listens on the network. If PostgreSQL on the same same host as docker, but not inside a docker container, we recommend that you just listen on the Docker interface by changing the following line in ``/etc/postgresql//main/postgresql.conf``:: + + listen_addresses = 'localhost,172.17.0.1' + +You also need to add a new line to ``/etc/postgresql//main/pg_hba.conf`` to allow network connections to this user and database:: + + host pretix pretix 172.17.0.1/16 md5 + +Restart PostgreSQL after you changed these files:: + + # systemctl restart postgresql + +If you have a firewall running, you should also make sure that port 5432 is reachable from the ``172.17.0.1/16`` subnet. + +For MySQL, you can either also use network-based connections or mount the ``/var/run/mysqld/mysqld.sock`` socket into the docker container. +When using MySQL, make sure you set the character set of the database to ``utf8mb4``, e.g. like this:: + + mysql > CREATE DATABASE pretix DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci; Redis ----- @@ -114,13 +127,16 @@ Fill the configuration file ``/etc/pretix/pretix.cfg`` with the following conten datadir=/data [database] - ; Replace mysql with postgresql_psycopg2 for PostgreSQL - backend=mysql + ; Replace postgresql with mysql for MySQL + backend=postgresql name=pretix user=pretix + ; Replace with the password you chose above password=********* - ; Replace with host IP address for PostgreSQL - host=/var/run/mysqld/mysqld.sock + ; In most docker setups, 172.17.0.1 is the address of the docker host. Adjuts + ; this to wherever your database is running, e.g. the name of a linked container + ; or of a mounted MySQL socket. + host=172.17.0.1 [mail] ; See config file documentation for more options @@ -164,14 +180,15 @@ named ``/etc/systemd/system/pretix.service`` with the following content:: -v /var/pretix-data:/data \ -v /etc/pretix:/etc/pretix \ -v /var/run/redis:/var/run/redis \ - -v /var/run/mysqld:/var/run/mysqld \ pretix/standalone:stable all ExecStop=/usr/bin/docker stop %n [Install] WantedBy=multi-user.target -You can leave the MySQL socket volume out if you're using PostgreSQL. You can now run the following commands +When using MySQL and socket mounting, you'll need the additional flag ``-v /var/run/mysqld:/var/run/mysqld`` in the command. + +You can now run the following commands to enable and start the service:: # systemctl daemon-reload diff --git a/doc/admin/installation/manual_smallscale.rst b/doc/admin/installation/manual_smallscale.rst index d70bb383a..a5110c50f 100644 --- a/doc/admin/installation/manual_smallscale.rst +++ b/doc/admin/installation/manual_smallscale.rst @@ -50,21 +50,27 @@ 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, e.g. for MySQL:: +of database managing tool or directly on our database's shell. For PostgreSQL, we would do:: - $ mysql -u root -p - mysql> CREATE DATABASE pretix DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci; - mysql> GRANT ALL PRIVILEGES ON pretix.* TO pretix@'localhost' IDENTIFIED BY '*********'; - mysql> FLUSH PRIVILEGES; + # sudo -u postgres createuser pretix + # sudo -u postgres createdb -O pretix pretix + +When using MySQL, make sure you set the character set of the database to ``utf8mb4``, e.g. like this:: + + mysql > CREATE DATABASE pretix DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci; Package dependencies -------------------- To build and run pretix, you will need the following debian packages:: - # apt-get install git build-essential python-dev python-virtualenv python3 python3-pip \ + # apt-get install git build-essential python-dev python3-venv python3 python3-pip \ python3-dev libxml2-dev libxslt1-dev libffi-dev zlib1g-dev libssl-dev \ - gettext libpq-dev libmysqlclient-dev libjpeg-dev libopenjp2-7-dev + gettext libpq-dev libmariadbclient-dev libjpeg-dev libopenjp2-7-dev + +.. note:: Python 3.7 is not yet supported, so if you run a very recent OS, make sure to get + Python 3.6 from somewhere. You can check the current state of things in our + `Python 3.7 issue`_. Config file ----------- @@ -85,13 +91,18 @@ Fill the configuration file ``/etc/pretix/pretix.cfg`` with the following conten datadir=/var/pretix/data [database] - ; Replace mysql with postgresql_psycopg2 for PostgreSQL - backend=mysql + ; For MySQL, replace with "mysql" + backend=postgresql name=pretix user=pretix - password=********* - ; Replace with host IP address for PostgreSQL - host=/var/run/mysqld/mysqld.sock + ; For MySQL, enter the user password. For PostgreSQL on the same host, + ; we don't need one because we can use peer authentification if our + ; PostgreSQL user matches our unix user. + password= + ; For MySQL, use local socket, e.g. /var/run/mysqld/mysqld.sock + ; For a remote host, supply an IP address + ; For local postgres authentication, you can leave it empty + host= [mail] ; See config file documentation for more options @@ -115,14 +126,14 @@ Now we will install pretix itself. The following steps are to be executed as the actually install pretix, we will create a virtual environment to isolate the python packages from your global python installation:: - $ virtualenv -p python3 /var/pretix/venv + $ python3 -m venv /var/pretix/venv $ source /var/pretix/venv/bin/activate (venv)$ pip3 install -U pip setuptools wheel -We now install pretix, its direct dependencies and gunicorn. Replace ``mysql`` with ``postgres`` in the following -command if you're running PostgreSQL:: +We now install pretix, its direct dependencies and gunicorn. Replace ``postgres`` with ``mysql`` in the following +command if you're running MySQL:: - (venv)$ pip3 install "pretix[mysql]" gunicorn + (venv)$ pip3 install "pretix[postgres]" gunicorn Note that you need Python 3.5 or newer. You can find out your Python version using ``python -V``. @@ -268,10 +279,10 @@ Updates .. warning:: While we try hard not to break things, **please perform a backup before every upgrade**. To upgrade to a new pretix release, pull the latest code changes and run the following commands (again, replace -``mysql`` with ``postgres`` if necessary):: +``postgres`` with ``mysql`` if necessary):: $ source /var/pretix/venv/bin/activate - (venv)$ pip3 install -U pretix[mysql] gunicorn + (venv)$ pip3 install -U pretix[postgres] gunicorn (venv)$ python -m pretix migrate (venv)$ python -m pretix rebuild (venv)$ python -m pretix updatestyles @@ -303,3 +314,4 @@ example:: .. _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/ +.. _Python 3.7 issue: https://github.com/pretix/pretix/issues/1025