Skip to content

Latest commit

 

History

History
243 lines (148 loc) · 5.56 KB

installation.rst

File metadata and controls

243 lines (148 loc) · 5.56 KB
Raw

Installation

Requirements

  • Python 3.7 or higher
  • PostgreSQL 9.6 or higher
  • Redis 2.8 or higher
  • Git (for downloading and updating BYCEPS, but not strictly for running it)

Debian

Debian Linux is the recommended operating system to run BYCEPS on.

The following packages are available as part of the current (as of August 2019) Debian "Buster" release:

  • git
  • postgresql-11
  • python3.7
  • python3.7-dev
  • python3.7-venv
  • redis-server

Additional required packages should be suggested for installation by the package manager.

Update the package list and install the necessary packages (as the root user):

# aptitude update
# aptitude install git postgresql-11 python3.7 python3.7-dev python3.7-venv redis-server

Refer to the Debian documentation for further details.

BYCEPS

Grab a copy of BYCEPS itself. For now, the best way probably is to clone the Git repository from GitHub:

$ git clone https://github.com/byceps/byceps.git

A new directory, byceps, should have been created.

This way, it should be easy to pull in future updates to BYCEPS using Git. (And there currently are no release tarballs anyway.)

Virtual Environment

The installation should happen in an isolated Python environment just for BYCEPS so that its requirements don't clash with different versions of the same libraries somewhere else in the system.

Python already comes with the necessary tools, namely virtualenv and pip.

Change into the BYCEPS path and create a virtual environment (named "venv") there:

$ cd byceps
$ python3.7 -m venv --system-site-packages venv

Activate it (but don't change into its path):

$ . ./venv/bin/activate

Note that the first dot is the dot command, followed by a relative file name (which is written as explicitly relative to the current path, ./).

Whenever you want to activate the virtual environment, make sure to do that either in the path in which you have created it using the above command, or adjust the path to reference it relatively (e.g. ../../venv/bin/activate) or absolutely (e.g. /var/www/byceps/venv/bin/activate).

Make sure the correct version of Python is used:

(venv)$ python -V
Python 3.7.3

It's probably a good idea to update pip to the current version:

(venv)$ pip install --upgrade pip

Install the Python depdendencies via pip:

(venv)$ pip install -r requirements.txt

Install BYCEPS in editable mode to make import byceps work in scripts:

(venv)$ pip install -e .

Database

There should already be a system user, likely postgres.

Become root:

$ su
<enter root password>

Switch to the postgres user:

# su postgres

Create a database user named byceps:

postgres@host$ createuser --echo --pwprompt byceps

You should be prompted to enter a password. Do that.

Create a copy of config/development_admin.py and, in the copy, replace the example password in the value of SQLALCHEMY_DATABASE_URI with the one you just entered.

Create a schema, also named byceps:

postgres@host$ createdb --encoding=UTF8 --template=template0 --owner byceps byceps

To run the tests, a dedicated user and database have to be created:

postgres@host$ createuser --echo --pwprompt byceps_test
postgres@host$ createdb --encoding=UTF8 --template=template0 --owner byceps_test byceps_test

Connect to the database:

$ psql

Load the pgcrypto extension:

postgres=# CREATE EXTENSION pgcrypto;

Ensure that the function gen_random_uuid() is available now:

postgres=# select gen_random_uuid();

Expected result (the actual UUID hopefully is different!):

           gen_random_uuid
--------------------------------------
 b30bd643-d592-44e2-a256-0e0e167ac762
(1 row)

Database Tables

Scripts are provided to create and populate database tables. Change the path to be able to call them:

$ cd scripts

Create the necessary tables:

$ BYCEPS_CONFIG=../config/yourconfig.py ./create_database_tables.py
Creating database tables ... done.

An initial set of authorization permissions and roles is provided as a TOML file. Import it into the database:

$ BYCEPS_CONFIG=../config/yourconfig.py ./import_permissions_and_roles.py data/permissions_and_roles.toml
Importing 75 permissions ... done.
Importing 29 roles ... done.

With the authorization data in place, create the initial user (which will get all available roles assigned):

$ BYCEPS_CONFIG=../config/yourconfig.py ./create_initial_admin_user.py
Screen name: Flynn
Email address: flynn@flynns-arcade.net
Password:
Creating user "Flynn" ... done.
Enabling user "Flynn" ... done.
Assigning 29 roles to user "Flynn" ... done.

Those roles allow the user to log in to the admin backend and make all administrative functionality available.