Skip to content

Latest commit

 

History

History
597 lines (463 loc) · 15.3 KB

setup-production-centos-apache.adoc

File metadata and controls

597 lines (463 loc) · 15.3 KB
Raw

UNOFFICIAL Setup production environment on CentOS and Apache2

Table of Contents

1. Introduction

This documentation explains how to deploy a Taiga service (each module is part of the Taiga platform).

The Taiga platform consists of three main components:

  • taiga-back (backend/api)

  • taiga-front-dist (frontend)

  • taiga-events (websockets gateway) (optional)

And each one has its own dependencies, at compile time and runtime.

Each component can run on one unique machine or each can be installed in a different machine. In this tutorial we will setup everything in one single machine. This type of setup should suffice for small/medium production environments.

2. Before starting

This tutorial assumes that you are using a clean, recently updated, CentOS 6 image.

Due the nature of frontend application, you should know that this service will be used through the domain/public-ip. This is because, the frontend application will run on your browser and it should communicate with the backend/api.

Taiga installation must be done with a "normal" user, never with root.

We assume the following:

  • ip: 80.88.23.45

  • hostname: example.com (which points to 80.88.23.45)

  • username: taiga

  • system ram >=1GB (needed for compilation of lxml)

3. Create user

''''
useradd -M taiga
usermod -L taiga
''''

4. Backend installation

This section helps with the installation of the backend (api) Taiga service.

4.1. Install dependencies

The Backend is written mainly in python (3.4) but for some third party libraries we need to install a C compiller and development headers.

yum groupinstall "Development Tools" -y

yum install -y gcc autoconf flex bison libjpeg-turbo-devel
yum install -y freetype-devel zlib-devel zeromq-devel gdbm-devel ncurses-devel
yum install -y automake libtool libffi-devel curl git tmux
yum install -y bzip2-devel

4.2. Setup a database

Install postgresql:

yum localinstall http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-centos94-9.4-1.noarch.rpm
yum install -y postgresql94-contrib
yum install -y postgresql94-docs postgresql94-devel postgresql94-server

And setup the initial user and database:

service postgresql-9.4 initdb
chkconfig postgresql-9.4 on
service postgresql-9.4 start

su - postgres -c "createuser taiga"
su - postgres -c "createdb taiga -O taiga"

4.3. Setup python environment

For run taiga-back you should have python (3.4) installed with some other third party libraries. As a first step, start installing python and virtualenvwrapper:

cd /usr/src
wget https://www.python.org/ftp/python/3.4.3/Python-3.4.3.tgz
tar xzf Python-3.4.3.tgz
cd Python-3.4.3
./configure
make altinstall

pip3.4 install virtualenv
pip3.4 install circus
pip3.4 install pycrypto # Not sure if necessary? Might be installed with requiremenets.txt...
pip3.4 install jwkest # Not sure if necessary? Might be installed with requiremenets.txt...
Note
 virtualenvwrapper helps maintain the system clean of third party libraries installed with language package manager, installing them in isolated virtual environment.

Restart the shell or run bash again, to reload the bash environment with virtualenvwrapper variables and functions.

The next step is to download the code from github and install their dependencies:

Download the code
su - taiga

cd ~
git clone https://github.com/taigaio/taiga-back.git taiga-back
cd taiga-back
git checkout stable
Create new virtualenv named taiga
virtualenv-3.4 -p /usr/local/bin/python3.4 taiga
Install dependencies
exit

cd /home/taiga/taiga-back
PATH=$PATH:/usr/pgsql-9.4/bin
pip3.4 install -r requirements.txt
Populate the database with initial basic data
su - taiga
cd ~/taiga-back

python3.4 manage.py migrate --noinput
python3.4 manage.py loaddata initial_user
python3.4 manage.py loaddata initial_project_templates
python3.4 manage.py loaddata initial_role
python3.4 manage.py compilemessages
python3.4 manage.py collectstatic --noinput

exit

This creates a new user admin with password 123123.

If you want some example data, you can execute the following command, which populates the database with sample projects and random data; useful for demos:

python3.4 manage.py sample_data

And as final step for setup taiga-back, you should create the intial configuration for proper static/media files resolution and optionally, email sending support:

Put this on ~/taiga-back/settings/local.py
from .common import *

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

SECRET_KEY = "theveryultratopsecretkey"

DEBUG = False
TEMPLATE_DEBUG = False
PUBLIC_REGISTER_ENABLED = True

DEFAULT_FROM_EMAIL = "[email protected]"
SERVER_EMAIL = DEFAULT_FROM_EMAIL

# 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"

4.4. Verification

To make sure everything is working, you can run the backend in development mode with:

python3.4 manage.py runserver

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

Note
 At this stage the backend has been installed successfully. But you’re not done yet. Because python in production environments, should run on an application server. The details for this are explained in the final section of this document.

4.5. Async tasks (Optional) - To Do

5. Frontend installation

Download the code from github:

Download the code
su - taiga

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

And now, you can configure it copying the taiga-front-dist/dist/js/conf.example.json to taiga-front-dist/dist/js/conf.json and editing it.

Copy and edit initial configuration on ~/taiga-front-dist/dist/js/conf.json
{
    "api": "http://example.com/api/v1/",
    "eventsUrl": "ws://example.com/events",
    "debug": "true",
    "publicRegisterEnabled": true,
    "feedbackEnabled": true,
    "privacyPolicyUrl": null,
    "termsOfServiceUrl": null,
    "maxUploadFileSize": null,
    "contribPlugins": []
}

Now, having taiga-front-dist downloaded and configured, the next step is to expose the code (in dist directory) under static file web server: we use apache. That process is explained in the final section of this tutorial.

6. Events installation

This step is completelly optional and can be skipped

Taiga-events is the Taiga websocket server, it allows taiga-front showing realtime changes in backlog, taskboard, kanban and issues listing.

Taiga events needs rabbitmq (the message broker) to be installed

Installing rabbitmq
sudo yum install rabbitmq-server
Creating a taiga user and virtualhost for rabbitmq
sudo rabbitmqctl add_user taiga PASSWORD
sudo rabbitmqctl add_vhost taiga
sudo rabbitmqctl set_permissions -p taiga taiga ".*" ".*" ".*"
Update your taiga-back settings to include in your local.py the lines:
EVENTS_PUSH_BACKEND = "taiga.events.backends.rabbitmq.EventsPushBackend"
EVENTS_PUSH_BACKEND_OPTIONS = {"url": "amqp://taiga:[email protected]:5672/taiga"}

The next step is downloading the code from github and installing their dependencies:

Download the code
cd ~
git clone https://github.com/taigaio/taiga-events.git taiga-events
cd taiga-events
Install all the javascript dependencies needed
sudo yum install -y nodejs nodejs-legacy npm
sudo npm install
sudo npm install -g coffee-script
Copy and edit the config.json file you should update your rabbitmq uri and the secret key.
cp config.example.json config.json
Your config.json should be like:
{
    "url": "amqp://taiga:[email protected]:5672/taiga",
    "secret": "mysecret",
    "webSocketServer": {
        "port": 8888
    }
}

Next, your secret in your config.json key should be the same as your "SECRET_KEY" in ~/taiga-back/settings/local.py

Now you have to add taiga-events to circus configuration. See Circus and gunicorn section.

Taiga taiga-events configuration block for circus on /home/taiga/circus.ini
[watcher:taiga-events]
working_dir = /home/taiga/taiga-events
cmd = /usr/bin/coffee
args = index.coffee
uid = taiga
numprocesses = 1
autostart = true
send_hup = true
stdout_stream.class = FileStream
stdout_stream.filename = /home/taiga/logs/taigaevents.stdout.log
stdout_stream.max_bytes = 10485760
stdout_stream.backup_count = 12
stderr_stream.class = FileStream
stderr_stream.filename = /home/taiga/logs/taigaevents.stderr.log
stderr_stream.max_bytes = 10485760
stderr_stream.backup_count = 12

Then you have to reload your circus configuration restart the other services and start taiga-events:

/etc/init.d/circusd-taiga restart

Apache need extra configuration too for taiga-events. Module mod_proxy_wstunnel must be installed.

Change configuration in httpd.conf.
(...)

    DocumentRoot /home/taiga/taiga-front-dist/dist/

    ProxyPass "/events/"  "ws://127.0.0.1:8888/"
    ProxyPassReverse "/events/" "ws://127.0.0.1:8888/"

    RewriteCond %{REQUEST_URI} ^/api(.*)
    RewriteRule .* http://127.0.0.1:8001/api%1 [P,QSA]

    RewriteCond %{REQUEST_URI} ^/admin(.*)
    RewriteRule .* http://127.0.0.1:8001%{REQUEST_URI} [P,QSA]

    RewriteCond %{HTTP:Upgrade} !websocket [NC]
    RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
    RewriteRule . /index.html [L]

Important parts:

ProxyPass "/events/" "ws://127.0.0.1:8888/"

ProxyPassReverse "/events/" "ws://127.0.0.1:8888/"

RewriteCond %{HTTP:Upgrade} !websocket [NC]

And finally, reload apache with sudo apachectl restart.

7. Final steps

If you are here, it’s probable that you completed the installation of taiga-back and taiga-front-dist. However, having installed them is insufficient.

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 circus respectivelly.

taiga-front-dist and taiga-back should be exposed to the outside, using good proxy/static-file web server. For this purpose we’ll use apache.

7.1. Circus and gunicorn

Circus is a process manager written by Mozilla and you will use it to execute gunicorn. Circus not only serves to execute processes, it also has utils for monitoring them, collecting logs, restarting processes if something goes wrong, and starting processes on system boot.

Install circus
mkdir /var/run/taiga
chown taiga:taiga /var/run/taiga

Create file /etc/init.d/circusd-taiga with the following content:

#!/bin/sh
#chkconfig: 345 99 10
#description: Circus (Taiga) auto start-stop script.

# source function library
. /etc/rc.d/init.d/functions

PIDFILE="/var/run/taiga/circus.pid"

start() {
        echo "Starting Circus (Taiga)..."
        if [ -f "${PIDFILE}" ];
        then
                echo "Circus (Taiga) already started."
        else
                su - taiga -c '/usr/local/bin/circusd /home/taiga/circus.ini & echo $! > '"${PIDFILE}"
        fi
}

stop() {
        echo "Stopping Circus (Taiga) process..."
        if [ -f "${PIDFILE}" ];
        then
#               su - taiga -c "kill -15 $(cat ${PIDFILE})"
                su - taiga -c 'killall --user taiga'
                su - taiga -c 'rm '"${PIDFILE}"
        else
                echo "${PIDFILE} does not exist."
        fi
}

restart() {
        echo "Stopping Circus (Taiga) process..."
        if [ -f "${PIDFILE}" ];
        then
#               su - taiga -c "kill -15 $(cat ${PIDFILE})"
                su - taiga -c 'killall --user taiga'
                su - taiga -c 'rm '"${PIDFILE}"
                sleep 5
        else
                echo "Nothing to stop..."
        fi

        su - taiga -c '/usr/local/bin/circusd /home/taiga/circus.ini & echo $! > '"${PIDFILE}"
}

case "$1" in
    start)
       start
        ;;
    stop)
       stop
        ;;
    restart)
       restart
        ;;
        *)
      echo "Usage: $0 start stop restart"
        ;;
esac

Set auto start for Circus:

chkconfig circusd-taiga on
Initial configuration for circus on ~/circus.ini (owned by taiga user)
[circus]
check_delay = 5
endpoint = tcp://127.0.0.1:5555
pubsub_endpoint = tcp://127.0.0.1:5556
statsd = true

[watcher:taiga]
working_dir = /home/taiga/taiga-back
cmd = gunicorn
args = -w 3 -t 60 --pythonpath=. -b 127.0.0.1:8001 taiga.wsgi
uid = taiga
numprocesses = 1
autostart = true
send_hup = true
stdout_stream.class = FileStream
stdout_stream.filename = /home/taiga/logs/gunicorn.stdout.log
stdout_stream.max_bytes = 10485760
stdout_stream.backup_count = 4
stderr_stream.class = FileStream
stderr_stream.filename = /home/taiga/logs/gunicorn.stderr.log
stderr_stream.max_bytes = 10485760
stderr_stream.backup_count = 4

[env:taiga]
PATH = /home/taiga/.virtualenvs/taiga/bin:$PATH
TERM=rxvt-256color
SHELL=/bin/bash
USER=taiga
LANG=en_US.UTF-8
HOME=/home/taiga
PYTHONPATH=/home/taiga/.virtualenvs/taiga/lib/python3.4/site-packages
Note

Taiga stores logs on the user home, making them available and immediately accessible when you enter a machine. To make everything work, make sure you have the logs directory created.

You can create it with: mkdir -p ~/logs (owned by taiga user)

And finally start circus:

/etc/init.d/circusd-taiga start

7.2. Apache

This guide assumes that you have allready installed Apache2:

This is additional configuration you need to add to VirtualHost:

(...)

DocumentRoot /home/taiga/taiga-front-dist/dist/

RewriteCond %{REQUEST_URI} ^/api(.*)
RewriteRule .* http://127.0.0.1:8001/api%1 [P,QSA]

RewriteCond %{REQUEST_URI} ^/admin(.*)
RewriteRule .* http://127.0.0.1:8001%{REQUEST_URI} [P,QSA]

RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteRule . /index.html [L]

Also you need to create 2 symoblic links in taiga-front:

su - taiga
ln -s /home/taiga/taiga-back/media /home/taiga/taiga-front-dist/dist/media
ln -s /home/taiga/taiga-back/static /home/taiga/taiga-front-dist/dist/static

After restarting apache you should be able to enjoy using Taiga.