Deployment from source

This guide describes the manual installation of grouprise using the sources. Filesystem paths and some commands may be Debian-specific, but should be easily adaptable to other Linux or unix-like distributions.

Download the Sources

The latest stable release is available at git.hack-hro.de. You can download it as a zip or tar file (both containing the same content).

Extract the content of the archive into /usr/local/share/grouprise.

Install System Dependencies

Dependencies mentioned in this section refer to Debian package names, which can be installed with apt. If you are installing grouprise on an operation system other than Debian or one of its many derivatives (e.g. Ubuntu), then you have to find the appropriate equivalents for your system’s package manager. A good starting point may be the Debian package search, which offers information about each package’s sources and website.

The following software is required when installing from sources:

  • make

  • nodejs

  • npm

  • pip

  • python3

  • virtualenv

  • wget

We recommend to pick a proper DBMS for running grouprise. Our recommendation is PostgreSQL, but any other option supported by Django should be fine too. Install the following packages:

  • postgresql

  • python3-psycopg2

Apart from that you will need an application server supporting the WSGI protocol and a web server. Our recommendations are uWSGI and NGINX. We ship configuration files for both, in order to minimize the required amount of customization. Install the following packages:

  • nginx

  • uwsgi

  • uwsgi-plugin-python3

Additional System Dependencies and Functionality

Even though most of the application dependencies can be handled via the virtualenv created in the section below, we recommend that you install some of these with your systems package manager. Refer to the debian/control file for a list of packages.

All packages in the Depends section, whose names start with python3- can and should be installed directly from the operating system. This approach is not strictly necessary but it is always a good idea to reduce the number of manually installed dependencies in order to increase overall security. Your operating system (“distribution“) usually does a much better job at keeping dependencies up to date than a single person ever could.

Prepare Virtualenv and Static Files

Unfortunately grouprise requires some libraries that are not available as packages in Debian (and most likely other distributions). A virtualenv is a simple way to install Python libraries without polluting directories that are usually under control of the operating system and its package manager.

grouprise uses Make to ease these tasks for you. In order to create the virtualenv and all other files necessary to run a proper grouprise instance you will need to run the default make target in the directory grouprise was installed in. If you have followed the defaults in the first step this should come down to a few commands:

cd /usr/local/share/grouprise
make virtualenv-update VIRTUALENV_CREATE_ARGUMENTS="--system-site-packages"

Database Initialization and Configuration

See database initialization for details.

Configure and Run grouprise

The what, how and why of grouprise configuration is outlined in the configuration documentation, but you will need to create a few files and symlinks to make it work.

The grouprise process is managed via uWSGI.

  1. copy grouprise.yaml.development to /etc/grouprise/conf.d/local.yaml and adapt the settings according to your needs

    • add debug: true, if you run into problems later

  2. create an uWSGI configuration (e.g. /etc/grouprise/uwsgi.ini)

  3. create a systemd service for grouprise

  4. start the grouprise service: service grouprise start

  5. create an nginx site configuration (e.g. /etc/nginx/site-available/grouprise):

    server {
    server_name YOUR_DOMAIN_NAME;
    client_max_body_size 10M;
    include /usr/local/share/grouprise/debian/nginx.conf;
}

  6. enable the site: ln -s ../sites-available/grouprise /etc/nginx/sites-enabled/

  7. restart nginx: service nginx restart

  8. visit the fresh grouprise instance: http://localhost/ (or use a suitable hostname)

You may also want to create a separate user and group for running grouprise and set the corresponding uid setting in the uWSGI configuration.