Installation

This guide will help you to install byro on a Linux distribution, as long as the prerequisites are present.

Step 0: Prerequisites

Please set up the following systems beforehand, we’ll not explain them here (but see these links for external installation guides):

  • Python 3.5+ and pip for Python 3. You can use python -V and pip3 -V to check.
  • An SMTP server to send out mails
  • An HTTP reverse proxy, e.g. nginx or Apache to allow HTTPS connections
  • A PostgreSQL (9.4 or higher) database server.

We also recommend that you use a firewall, although this is not a byro-specific recommendation. If you’re new to Linux and firewalls, we recommend that you start with ufw.

Note

Please do not run byro without HTTPS encryption. You’ll handle sensitive data and thanks to Let’s Encrypt, SSL certificates are free these days. We also do not provide support for HTTP-exclusive installations except for evaluation purposes.

Step 1: Unix user

As we do not want to run byro as root, we first create a new unprivileged user:

# adduser byro --disabled-password --home /var/byro

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); you should run all lines prepended with a $ symbol as the unprivileged user.

Step 2: Database setup

Having the database server installed, we still need a database and a database user. As the postgres user, execute:

postgres $ createuser byro -P
Enter password for new role:
Enter it again:
postgres $ createdb byro
postgres $ psql
postgres=# GRANT ALL PRIVILEGES ON DATABASE byro to byro;

Replace the asterisks with a password of your own.

Step 3: Package dependencies

To build and run byro, you will need the following Debian packages beyond the dependencies mentioned above:

# apt-get install git build-essential libssl-dev gettext

Replace all further “pip” commands with “pip3” if your system does not have Python 3 as default Python version.

Step 4: Configuration

We now create a configuration directory and configuration file for byro:

# mkdir /etc/byro
# touch /etc/byro/byro.cfg
# chown -R byro:byro /etc/byro/
# chmod 0600 /etc/byro/byro.cfg

Fill the configuration file /etc/byro/byro.cfg with the following content (adjusted to your environment):

[filesystem]
data = /var/byro/data
media = /var/byro/data/media
logs = /var/byro/data/logs

[site]
debug = False
url = https://byro.mydomain.com

[database]
name = byro
user = byro
password = byro
host = localhost
port = 5432

[mail]
from = admin@localhost
host = localhost
port = 25
user = admin
password = something
tls = False
ssl = True

Step 5: Installation

Now we will install byro itself. Please execute the following steps as the byro user. We will install all Python packages, including byro, in the user’s Python environment, so that your global Python installation will not know of them:

$ pip install --user -U pip setuptools wheel byro gunicorn psycopg2-binary

We also need to create a data directory:

$ mkdir -p /var/byro/data/media

We compile static files and translation data and create the database structure:

$ python -m byro migrate
$ python -m byro rebuild

Now, create an administrator user by running:

$ python -m byro createsuperuser

If you just want to play around with byro, you can load test data:

$ python -m byro make_testdata

Step 6: Starting byro as a service

We recommend starting byro using systemd to make sure it starts up after a reboot. Create a file named /etc/systemd/system/byro-web.service with the following content:

[Unit]
Description=byro web service
After=network.target

[Service]
User=byro
Group=byro
WorkingDirectory=/var/byro/.local/lib/python3.5/site-packages/byro
ExecStart=/var/byro/.local/bin/gunicorn byro.wsgi \
                      --name byro --workers 4 \
                      --max-requests 1200  --max-requests-jitter 50 \
                      --log-level=info --bind=127.0.0.1:8345
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 byro-web
# systemctl start byro-web

Step 7: SSL

The following snippet is an example on how to configure a nginx proxy for byro:

server {
    listen 80 default_server;
    listen [::]:80 ipv6only=on default_server;
    server_name byro.mydomain.com;
}
server {
    listen 443 default_server;
    listen [::]:443 ipv6only=on default_server;
    server_name byro.mydomain.com;

    ssl on;
    ssl_certificate /path/to/cert.chain.pem;
    ssl_certificate_key /path/to/key.pem;

    add_header Referrer-Options same-origin;
    add_header X-Content-Type-Options nosniff;

    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/byro/data/media/;
        add_header Content-Disposition 'attachment; filename="$1"';
        expires 7d;
        access_log off;
    }

    location /static/ {
        alias /path/to/static.dist/;
        access_log off;
        expires 365d;
        add_header Cache-Control "public";
    }
}

Note

Remember to replace the python3.5 in the /static/ path in the config above with your python version.

We recommend reading about setting strong encryption settings for your web server.

You’ve made it! You should now be able to reach byro at https://byro.yourdomain.com/ and log in as the administrator you configured above. byro will take you through the remaining configuration steps.

Step 8: Check the installation

You can make sure the web interface is up and look for any issues with:

# journalctl -u byro-web

In the start-up output, byro also lists its logging directory, which is also a good place to look for the reason for issues.

Next Steps: Updates

Warning

While we try hard not to issue breaking updates, please perform a backup before every upgrade.

To upgrade byro, please first read through our changelog and if available our release blog post to check for relevant update notes. Also, make sure you have a current backup.

Next, please execute the following commands in the same environment (probably your virtualenv) to first update the byro source, then update the database if necessary, then rebuild changed static files, and then restart the byro service. Please note that you will run into an entertaining amount of errors if you forget to restart the services.

If you want to upgrade byro to a specific release, you can substitute byro with byro==1.2.3 in the first line:

$ pip3 install -U byro gunicorn
$ python -m byro migrate
# systemctl restart byro-web