User Tools

Site Tools


taiga

Taiga.io Agile Project Management Tool

Introduction

This documentation explains how to deploy a full Taiga service (each module is part of the Taiga platform). The Taiga platform consists of three main components and each one has its own dependencies both at compile time and runtime:

  • taiga-back (backend/api)
  • taiga-front-dist (frontend)
  • taiga-events (websockets gateway) (optional)

Each component can be run on one unique machine or all of them can be installed to a different machine aswell. In this tutorial we will setup everything on one single machine, installing all three Taiga components. This type of setup should suffice for small/medium production environments.

Overview

Due to the nature of the frontend, Taiga is used through a domain/public-ip, because the frontend application runs in your browser. The frontend must be able to communicate with the backend/API, therefore both the frontend and the backend must be accessible through a domain/public-ip too.

The installation of Taiga must be done with a “regular” user, never with root.

During the tutorial, We assume the following details:

  • ip: 118.179.43.233
  • hostname: rpi.tiger-park.com (which points to 118.179.43.233)
  • username: taiga
  • system ram >=1GB (needed for compilation of lxml)
  • working dir /home/taiga/ (default for user taiga)

Architecture

This is a short system architecture description to help you understand the way Taiga is built and works. Before you go any further in the installation, make sure you read this description to get a high-level overview.

Taiga consists of 2 core (mandatory) modules:

  • taiga-back is written in django, python3 and serves API endpoints for the frontend.
  • taiga-front is written mostly in angularjs and coffeescript and depends on the backend.

The python backend is exposed by gunicorn (port 9001), which is a Python WSGI HTTP server. The process manager is systemd, which runs gunicorn and taiga-back together. Technically the backend communicates with the database(postgresql) and through the frontend, it allows the user to use the features of Taiga. The communication between the front- and backend is done using APIs.

The backend is then publicly exposed by nginx which acts as a reverse-proxy for this case. The frontend is located in the dist folder and is exposed publicly by nginx which acts as a static webserver for this case.

1.0 --- Prerequisites

Install essential packages:

sudo apt-get update
sudo apt-get install build-essential binutils-doc autoconf flex bison libjpeg-dev libfreetype6-dev zlib1g-dev libzmq3-dev libgdbm-dev libncurses5-dev automake libtool libffi-dev curl git tmux gettext rabbitmq-server redis-server nginx nginx-extras postgresql-9.6 postgresql-contrib-9.6 postgresql-doc-9.6 postgresql-server-dev-9.6 python3 python3-pip python-dev python3-dev python-pip virtualenvwrapper libxml2-dev libxslt-dev libssl-dev libffi-dev python3-lxml

Restart the shell or run bash to reload the bash environment with the new virtualenvwrapper variables and functions. This step is mandatory before continuing the installation!

1.1 --- Create user

Create a user named taiga, and give it root permissions:

sudo adduser taiga
sudo adduser taiga sudo
sudo su taiga
cd ~

Do not change to root user. The installation must be done with the taiga user.

1.2 --- Dependencies

Configure postgresql with the initial user and database:

sudo -u postgres createuser taiga
sudo -u postgres createdb taiga -O taiga --encoding='utf-8' --locale=en_GB.utf8 --template=template0

Create a user named taiga, and a virtualhost for RabbitMQ (taiga-events):

sudo rabbitmqctl add_user taiga PASSWORD_FOR_EVENTS
sudo rabbitmqctl add_vhost taiga
sudo rabbitmqctl set_permissions -p taiga taiga ".*" ".*" ".*"

2.0 --- Taiga backend

Download the code:

cd ~
git clone https://github.com/taigaio/taiga-back.git taiga-back
cd taiga-back
git checkout stable

Create new virtualenv named taiga:

mkvirtualenv -p /usr/bin/python3 taiga

Install dependencies:

pip install -r requirements.txt

— (Optional) — If your are having problems installing lxml, please follow the following:

sudo apt install python3-lxml python-lxml libxml2-dev libxslt-dev python-dev

This will install lxml system-side. Now we have to symlink the file into the virtualenv project directory. To do this follow the steps below (change python version to your system python version):

ln -s /usr/lib/python3/dist-packages/lxml ~/.virtualenvs/taiga/lib/python3.7/site-packages/lxml

Now test if lxml is installed by activating the taiga project and typing pip install lxml. You may also want to remove lxml from the requirements.txt once the requirement is satisfied. — — —

Populate the database with initial basic data:

python manage.py migrate --noinput
python manage.py loaddata initial_user
python manage.py loaddata initial_project_templates
python manage.py compilemessages
python manage.py collectstatic --noinput

This creates the administrator account. The login credentials are admin with password 123123.

To finish the setup of taiga-back, create the initial configuration file for proper static/media file resolution, optionally with email sending support. Copy-paste the following config into ~/taiga-back/settings/local.py and update it with your own details:

from .common import *

MEDIA_URL = "http://example.com/media/"
STATIC_URL = "http://example.com/static/"
SITES["front"]["scheme"] = "http"
SITES["front"]["domain"] = "example.com"

SECRET_KEY = "theveryultratopsecretkey"

DEBUG = False
PUBLIC_REGISTER_ENABLED = True

DEFAULT_FROM_EMAIL = "no-reply@example.com"
SERVER_EMAIL = DEFAULT_FROM_EMAIL

#CELERY_ENABLED = True

EVENTS_PUSH_BACKEND = "taiga.events.backends.rabbitmq.EventsPushBackend"
EVENTS_PUSH_BACKEND_OPTIONS = {"url": "amqp://taiga:PASSWORD_FOR_EVENTS@localhost:5672/taiga"}

# Uncomment and populate with proper connection parameters
# for enable email sending. EMAIL_HOST_USER should end by @domain.tld
#EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
#EMAIL_USE_TLS = False
#EMAIL_HOST = "localhost"
#EMAIL_HOST_USER = ""
#EMAIL_HOST_PASSWORD = ""
#EMAIL_PORT = 25

# Uncomment and populate with proper connection parameters
# for enable github login/singin.
#GITHUB_API_CLIENT_ID = "yourgithubclientid"
#GITHUB_API_CLIENT_SECRET = "yourgithubclientsecret"

2.1 --- Verification

To make sure that everything works, issue the following command to run the backend in development mode for a test:

workon taiga
python manage.py runserver 0.0.0.0:8000

Then you must be able to see a json representing the list of endpoints at the url: http://localhost:8000/api/v1/.

3.0 --- Taiga frontend

Download the code:

cd ~
git clone https://github.com/taigaio/taiga-front-dist.git taiga-front-dist
cd taiga-front-dist
git checkout stable

Copy the example config file:

cp ~/taiga-front-dist/dist/conf.example.json ~/taiga-front-dist/dist/conf.json

Edit the example configuration following the pattern below (replace with your own details):

nano ~/taiga-front-dist/dist/conf.json
{
	"api": "http://example.com/api/v1/",
	"eventsUrl": "ws://example.com/events",
	"debug": "true",
	"publicRegisterEnabled": true,
	"feedbackEnabled": true,
	"privacyPolicyUrl": null,
	"termsOfServiceUrl": null,
	"GDPRUrl": null,
	"maxUploadFileSize": null,
	"contribPlugins": []
}

Having taiga-front-dist downloaded and configured is insufficient. The next step is to expose the code (in dist directory) under a static file web server. In this tutorial We use nginx as a static file web server and reverse-proxy. The configuration of nginx is explained later.

3.1 --- Taiga events

aiga-events is the Taiga websocket server, it allows taiga-front to show realtime changes in the backlog, taskboard, kanban and issues listing. Taiga-events use rabbitmq (the message broker).

Download taiga-events from Github and install its dependencies:

cd ~
git clone https://github.com/taigaio/taiga-events.git taiga-events
cd taiga-events

Install nodejs:

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install nodejs

Install the javascript dependencies needed:

npm install

Copy and edit the config.json file. Update with your rabbitmq uri and the secret key:

cp config.example.json config.json
nano config.json

Your config.json should be like:

{
    "url": "amqp://taiga:PASSWORD_FOR_EVENTS@localhost:5672/taiga",
    "secret": "theveryultratopsecretkey",
    "webSocketServer": {
        "port": 8888
    }
}

The 'secret' in config.json must be the same as the “SECRET_KEY” in ~/taiga-back/settings/local.py

Add taiga-events to systemd configuration. Copy-paste the code below into /etc/systemd/system/taiga_events.service:

sudo nano /etc/systemd/system/taiga_events.service
[Unit]
Description=taiga_events
After=network.target

[Service]
User=taiga
WorkingDirectory=/home/taiga/taiga-events
ExecStart=/bin/bash -c "node_modules/coffeescript/bin/coffee index.coffee"
Restart=always
RestartSec=3

[Install]
WantedBy=default.target

4.0 --- Start & Expose Taiga

Before moving further, make sure you installed taiga-back and taiga-front-dist, however, having installed them is insufficient to run Taiga.

taiga-back should run under an application server, which in turn, should be executed and monitored by a process manager. For this task we will use gunicorn and systemd respectively.

Both taiga-front-dist and taiga-back must be exposed to the outside using a proxy/static-file web server. For this purpose, Taiga uses nginx.

4.1 --- systemd and gunicorn

Systemd is the process supervisor used by Ubuntu and Taiga uses it to execute gunicorn. Systemd is not only for executing processes, but it also has utils for monitoring them, collecting logs, and restarting processes if something goes wrong, and also for starting processes on system boot.

Initial Taiga configuration for systemd in /etc/systemd/system/taiga.service:

sudo nano /etc/systemd/system/taiga.service
[Unit]
Description=taiga_back
After=network.target

[Service]
User=taiga
Environment=PYTHONUNBUFFERED=true
WorkingDirectory=/home/taiga/taiga-back
ExecStart=/home/taiga/.virtualenvs/taiga/bin/gunicorn --workers 4 --timeout 60 -b 127.0.0.1:8001 taiga.wsgi
Restart=always
RestartSec=3

[Install]
WantedBy=default.target

Final step is reloading systemd daemon and starting taiga service:

sudo systemctl daemon-reload
sudo systemctl start taiga
sudo systemctl enable taiga

4.2 --- Nginx

Nginx is used as a static file web server to serve taiga-front-dist and send proxy requests to taiga-back.

Remove the default nginx config file to avoid collision with Taiga:

sudo rm /etc/nginx/sites-enabled/default

Create the logs folder (mandatory):

mkdir -p ~/logs

To create a new nginx virtualhost for Taiga, create and edit the /etc/nginx/sites-available/taiga.conf file, as follows:

server {
    listen 80 default_server;
    server_name rpi.tiger-park.com;

    large_client_header_buffers 4 32k;
    client_max_body_size 50M;
    charset utf-8;

    access_log /home/taiga/logs/nginx.access.log;
    error_log /home/taiga/logs/nginx.error.log;

    # Frontend
    location / {
        root /home/taiga/taiga-front-dist/dist/;
        try_files $uri $uri/ /index.html;
    }

    # Backend
    location /api {
        include proxy_params;
        proxy_set_header X-Scheme $scheme;
        proxy_pass http://127.0.0.1:8001/api;
        proxy_redirect off;
    }

    # Django admin access (/admin/)
    location /admin {
        include proxy_params;
        proxy_set_header X-Scheme $scheme;
        proxy_pass http://127.0.0.1:8001$request_uri;
        proxy_redirect off;
    }

    # Static files
    location /static {
        alias /home/taiga/taiga-back/static;
    }

    # Media files
    location /media {
        alias /home/taiga/taiga-back/media;
    }

    # Taiga-events
    location /events {
        proxy_pass http://127.0.0.1:8888/events;
	proxy_http_version 1.1;
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header Connection "upgrade";
	proxy_connect_timeout 7d;
	proxy_send_timeout 7d;
	proxy_read_timeout 7d;
    }
}

Link taiga.conf to /etc/nginx/sites-enabled/ to enable the configuration:

sudo ln -s /etc/nginx/sites-available/taiga.conf /etc/nginx/sites-enabled/taiga.conf

Issue the following command to verify the nginx configuration and to track any error in the service:

sudo nginx -t

Finally, restart nginx:

sudo systemctl restart nginx

Now you should have the service up and running on: http://rpi.tiger-park.com/

4.3 --- Celery

The default behavior in Taiga is to do all tasks in a synchronous way, but some of them can be completely asynchronous (for example webhooks or import/export). To do this, you have to configure and install the celery service requirements.

There is just an exception related to exported files, if your instance works in asynchronous mode the exported project files will be automatically removed from the storage after 24 hours, if not those media files won’t be automatically removed (taiga-back doesn’t really know anything about the existence of those files).

Install rabbitmq-server and redis-server:

sudo apt-get install rabbitmq-server redis-server

To run celery with Taiga, include the following code line in the ~/taiga-back/settings/local.py file:

nano ~/taiga-back/settings/local.py
[...]
CELERY_ENABLED = True
[...]

Once you have configured celery on Taiga, you have to add celery to systemd configuration. Taiga celery configuration block for systemd on /etc/systemd/system/taiga_celery.service:

sudo nano /etc/systemd/system/taiga_celery.service
[Unit]
Description=taiga_celery
After=network.target

[Service]
User=taiga
Environment=PYTHONUNBUFFERED=true
WorkingDirectory=/home/taiga/taiga-back
ExecStart=/home/taiga/.virtualenvs/taiga/bin/celery -A taiga worker --concurrency 4 -l INFO
Restart=always
RestartSec=3
ExecStop=/bin/kill -s TERM $MAINPID

[Install]
WantedBy=default.target

Reload the systemd configuration, restart taiga, then start taiga-celery:

sudo systemctl daemon-reload
sudo systemctl start taiga_celery
sudo systemctl enable taiga_celery
sudo systemctl restart taiga

5.0 --- DB Backup

i.i --- Important Paths

  • /etc/nginx/sites-available/taiga.conf
  • /etc/systemd/system/taiga.service
  • /etc/systemd/system/taiga_celery.service
  • /etc/systemd/system/taiga_events.service
  • /home/taiga/taiga-back/settings/local.py
  • /home/taiga/taiga-front-dist/dist/conf.json
  • /home/taiga/taiga-events/config.json

x.x --- References

taiga.txt · Last modified: 2019/02/03 00:56 by pi