From b0d3f0926a0a9df84164ed8b300ebc7fa67d2f19 Mon Sep 17 00:00:00 2001 From: Raphael Michel Date: Sun, 31 Jul 2016 15:43:17 +0200 Subject: [PATCH] Added guide for manual installation --- Dockerfile | 2 +- doc/admin/installation/docker_smallscale.rst | 9 +- doc/admin/installation/index.rst | 1 + doc/admin/installation/manual_smallscale.rst | 279 +++++++++++++++++++ 4 files changed, 289 insertions(+), 2 deletions(-) create mode 100644 doc/admin/installation/manual_smallscale.rst diff --git a/Dockerfile b/Dockerfile index 403e18caf8..da7b5e0acf 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,7 @@ FROM debian:jessie RUN apt-get update && apt-get install -y python3 git python3-pip \ libxml2-dev libxslt1-dev python-dev python-virtualenv locales libffi-dev \ - build-essential python3-dev zlib1g-dev libssl-dev gettext git \ + build-essential python3-dev zlib1g-dev libssl-dev gettext \ libpq-dev libmysqlclient-dev libmemcached-dev libjpeg-dev \ aqbanking-tools supervisor nginx sudo \ --no-install-recommends diff --git a/doc/admin/installation/docker_smallscale.rst b/doc/admin/installation/docker_smallscale.rst index 3dc34c868a..11a23b0660 100644 --- a/doc/admin/installation/docker_smallscale.rst +++ b/doc/admin/installation/docker_smallscale.rst @@ -1,5 +1,7 @@ .. highlight:: none +.. _`dockersmallscale`: + Small-scale deployment with Docker ================================== @@ -166,7 +168,12 @@ named ``/etc/systemd/system/pretix.service`` with the following content:: [Install] WantedBy=multi-user.target -You can leave the MySQL socket volume out if you're using PostgreSQL. +You can leave the MySQL socket volume out if you're using PostgreSQL. You can now run the following comamnds +to enable and start the service:: + + # systemctl daemon-reload + # systemctl enable pretix + # systemctl start pretix Cronjob ------- diff --git a/doc/admin/installation/index.rst b/doc/admin/installation/index.rst index d3777ef2d4..17a9d34d1d 100644 --- a/doc/admin/installation/index.rst +++ b/doc/admin/installation/index.rst @@ -9,3 +9,4 @@ for your needs. general docker_smallscale + manual_smallscale diff --git a/doc/admin/installation/manual_smallscale.rst b/doc/admin/installation/manual_smallscale.rst new file mode 100644 index 0000000000..4078aaa47c --- /dev/null +++ b/doc/admin/installation/manual_smallscale.rst @@ -0,0 +1,279 @@ +.. highlight:: none + +Small-scale manual deployment +============================= + +This guide describes the installation of a small-scale installation of pretix from source. By small-scale, we mean +that everything is being run on one host and you don't expect thousands of participants trying to get a ticket within +a few minutes. In this setup, you will have to perform a number of manual steps. If you prefer using a container +solution with many things readily set-up, look at :ref:`dockersmallscale`. + +.. warning:: Even though we try to make it straightforward to run pretix, it still requires some Linux experience to + get it right. If you're not feeling comfortable managing a Linux server, check out our hosting and service + offers at `pretix.eu`_. + +We tested this guide on the Linux distribution **Debian 8.0** but it should work very similar on other +modern distributions, especially on all systemd-based ones. + +Requirements +------------ + +Please set up the following systems beforehand, we'll not explain them here in detail (but see these links for external +installation guides): + +* `Docker`_ +* 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 Apache to allow HTTPS connections +* A `MySQL`_ or `PostgreSQL`_ database server +* A `redis`_ server + +We also recommend that you use a firewall, although this is not a pretix-specific recommendation. If you're new to +Linux and firewalls, we recommend that you start with `ufw`_. + +.. note:: Please, do not run pretix without HTTPS encryption. You'll handle user data and thanks to `Let's Encrypt`_ + SSL certificates can be obtained for free these days. We also *do not* provide support for HTTP-only + installations except for evaluation purposes. + +Unix user +--------- + +As we do not want to run pretix as root, we first create a new unprivileged user:: + + # sudo adduser pretix --disabled-password --home /var/pretix + +In this guide, all code lines prepended with a ``#`` symbol are commands that you need to execute on your server as +``root`` user; 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, e.g. for MySQL:: + + $ mysql -u root -p + mysql> CREATE DATABASE pretix DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; + mysql> GRANT ALL PRIVILEGES ON pretix.* TO pretix@'localhost' IDENTIFIED BY '*********'; + mysql> FLUSH PRIVILEGES; + +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 \ + python3-dev libxml2-dev libxslt1-dev libffi-dev zlib1g-dev libssl-dev \ + gettext libpq-dev libmysqlclient-dev libjpeg-dev + +Config file +----------- + +We now create a config directory and config file for pretix:: + + # mkdir /etc/pretix + # touch /etc/pretix/pretix.cfg + # chown -R pretix:pretix/etc/pretix/ + # chmod 0600 /etc/pretix/pretix.cfg + +Fill the configuration file ``/etc/pretix/pretix.cfg`` with the following content (adjusted to your environment):: + + [pretix] + instance_name=My pretix installation + url=https://pretix.mydomain.com + currency=EUR + datadir=/var/pretix/data + + [database] + ; Replace mysql with psycopg2 for PostgreSQL + backend=mysql + name=pretix + user=pretix + password=********* + ; Replace with host IP address for PostgreSQL + host=/var/run/mysqld/mysqld.sock + + [mail] + ; See config file documentation for more options + from=tickets@yourdomain.com + ; This is the default IP address of your docker host in docker's virtual + ; network. Make sure postfix listens on this address. + host=127.0.0.1 + + [redis] + location=redis://127.0.0.1/0 + sessions=true + + [celery] + backend=redis://127.0.0.1?virtual_host=1 + broker=redis://127.0.0.1?virtual_host=2 + +See :ref:`email configuration ` to learn more about configuring mail features. + +Install pretix from source +-------------------------- + +Now we will install pretix itself. The following steps are to be executed as the ``pretix`` user. Before we +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 + $ source /var/pretix/venv/bin/activate + (venv)$ pip install -U pip setuptools wheel + +We now clone pretix and install its Python dependencies (replace ``mysql`` with ``postgres`` if you're running +PostgreSQL):: + + (venv)$ git clone https://github.com/pretix/pretix.git /var/pretix/source + (venv)$ cd /var/pretix/source/src + (venv)$ pip3 install -r requirements.txt -r requirements/mysql.txt \ + -r requirements/celery.txt -r requirements/redis.txt \ + -r requirements/py34.txt gunicorn + +We also need to create a data directory:: + + (venv)$ mkdir -p /var/pretix/data/media + +Finally, we compile static files and translation data and create the database structure:: + + (venv)$ make production + (venv)$ python manage.py migrate + + +Start pretix as a service +------------------------- + +We recommend starting pretix using systemd to make sure it runs correctly after a reboot. Create a file +named ``/etc/systemd/system/pretix-web.service`` with the following content:: + + [Unit] + Description=pretix web service + After=network.target + + [Service] + User=pretix + Group=pretix + Environment="VIRTUAL_ENV=/var/pretix/venv" + Environment="PATH=/var/pretix/venv/bin:/usr/local/bin:/usr/bin:/bin" + ExecStart=/var/pretix/venv/bin/gunicorn pretix.wsgi \ + --name pretix --workers 5 \ + --max-requests 1200 --max-requests-jitter 50 \ + --log-level=info --bind=127.0.0.1:8345 + WorkingDirectory=/var/pretix/source/src + Restart=on-failure + + [Install] + WantedBy=multi-user.target + +For background tasks we need a second service ``/etc/systemd/system/pretix-worker.service`` with the following content:: + + [Unit] + Description=pretix background worker + After=network.target + + [Service] + User=pretix + Group=pretix + Environment="VIRTUAL_ENV=/var/pretix/venv" + Environment="PATH=/var/pretix/venv/bin:/usr/local/bin:/usr/bin:/bin" + ExecStart=/var/pretix/venv/bin/celery -A pretix worker -l info + WorkingDirectory=/var/pretix/source/src + Restart=on-failure + + [Install] + WantedBy=multi-user.target + +You can now run the following comamnds to enable and start the services:: + + # systemctl daemon-reload + # systemctl enable pretix-web pretix-worker + # systemctl start pretix-web pretix-worker + + +Cronjob +------- + +You need to set up a cronjob that runs the management command ``runperiodic``. The exact interval is not important +but should be something between every minute and every hour. You could for example configure cron like this:: + + 15,45 * * * * export PATH=/var/pretix/venv/bin:$PATH && cd /var/pretix/source/src && ./manage.py runperiodic + +The cronjob should run as the ``pretix`` user (``crontab -e -u pretix``). + +SSL +--- + +The following snippet is an example on how to configure a nginx proxy for pretix:: + + server { + listen 80 default_server; + listen [::]:80 ipv6only=on default_server; + server_name pretix.mydomain.com; + } + server { + listen 443 default_server; + listen [::]:443 ipv6only=on default_server; + server_name pretix.mydomain.com; + + ssl on; + ssl_certificate /path/to/cert.chain.pem; + ssl_certificate_key /path/to/key.pem; + + 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 /media/ { + alias /var/pretix/data/media/; + expires 7d; + access_log off; + } + + location /static/ { + alias /var/pretix/source/src/pretix/static.dist/; + 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 pretix at https://pretix.yourdomain.com/control/ and log in as +*admin@localhost* with a password of *admin*. Don't forget to change that password! Create an organizer first, then +create an event and start selling tickets! + +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):: + + $ source /var/pretix/venv/bin/activate + (venv)$ cd /var/pretix/source/src + (venv)$ git pull origin master + (venv)$ pip3 install -r requirements.txt -r requirements/mysql.txt \ + -r requirements/celery.txt -r requirements/redis.txt \ + -r requirements/py34.txt gunicorn + (venv)$ python manage.py migrate + (venv)$ make production + (venv)$ python manage.py updatestyles + # systemctl restart pretix-web pretix-worker + +.. _Docker: https://docs.docker.com/engine/installation/linux/debian/ +.. _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/ +.. _pretix.eu: https://pretix.eu/ +.. _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-9-4-on-debian-8 +.. _redis: http://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/