Skip to content

Latest commit

 

History

History
734 lines (568 loc) · 18.1 KB

setup-production.adoc

File metadata and controls

734 lines (568 loc) · 18.1 KB

Setup production environment

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 (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 suffce should for small/medium production environments.

2. Before starting

This tutorial assumes that you are using a clean, recently updated, ubuntu 14.04 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.

We assume the following:

  • ip: 80.88.23.45

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

  • username: taiga

3. Backend installation

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

3.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.

sudo apt-get install -y build-essential binutils-doc autoconf flex bison libjpeg-dev
sudo apt-get install -y libfreetype6-dev zlib1g-dev libzmq3-dev libgdbm-dev libncurses5-dev
sudo apt-get install -y automake libtool libffi-dev curl git tmux

3.2. Setup a database

taiga-back also requires postgresql (>= 9.3) as a database

Install postgresql:

sudo apt-get install -y postgresql-9.3 postgresql-contrib-9.3
sudo apt-get install -y postgresql-doc-9.3 postgresql-server-dev-9.3

And setup the initial user and database:

sudo -u postgres createuser taiga
sudo -u postgres createdb taiga -O taiga

3.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:

sudo apt-get install -y python3 python3-pip python-dev python3-dev python-pip virtualenvwrapper
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
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.4 taiga
Install dependencies
pip install -r requirements.txt
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 loaddata initial_role
python manage.py collectstatic --noinput

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:

python 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"]["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_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"

3.4. Verification

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

workon taiga
python 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. Frontend installation

This section helps you install the frontend application

4.1. Install dependencies

The Frontend application runs entirelly on a browser, and it should be written using javascript, css and html. In case of taiga-front we have used other languages. Because of this, you should install some additional dependencies that compile taiga-front code intro something the browser can understand.

4.1.1. Ruby and Gems

Ruby is used mainly for compiling sass (css preprocessor). It is also used for sass linting but that is only on development environments.

Install ruby
sudo apt-get install -y ruby
Install required gems
gem install --user-install sass scss-lint
Make gems scripts available in path putting this on ~/.bashrc
export PATH=~/.gem/ruby/1.9.1/bin:$PATH

Restart the shell or run bash to make the path changes available.

4.1.2. NodeJS and friends

NodeJS is used to execute gulp and bower:

  • gulp: task execution tool. Used mainly for executing deploying and compiling tasks.

  • bower: javascript dependencies management tool. Used mainly for downloading third party libraries used by taiga-front.

Install nodejs
sudo apt-get install -y nodejs npm
Make sure your bash responds to node command to have a smooth installation of gulp and bower
node

If you get a "Command not found" error, then run

sudo ln -s /usr/bin/nodejs /usr/bin/node
Install gulp and bower using recently installed npm
sudo npm install -g gulp bower
Download the code
cd ~
git clone https://github.com/taigaio/taiga-front.git taiga-front
cd taiga-front
git checkout stable
Install all dependencies needed for run gulp and compile taiga-front
npm install
bower install

4.2. Final steps

Having installed all dependencies, only two steps remain: creating the configuration and compiling.

Create intial configuration on ~/taiga-front/conf/main.json
{
    "api": "http://example.com/api/v1/",
    "eventsUrl": "ws://example.com/events",
    "debug": "true",
    "publicRegisterEnabled": true,
    "feedbackEnabled": true,
    "privacyPolicyUrl": null,
    "termsOfServiceUrl": null,
    "maxUploadFileSize": null,
    "gitHubClientId": null
}
Run gulp task for compile
cd ~/taiga-front
gulp deploy

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

4.3. Verification

To make sure everything is ok, you can check the dist directory and you’ll see an index.html file and fonts, images, js, partials, plugins, styles and svg directories.

5. Events installation

This step is completelly optional and can be skipped

TODO

6. Final steps

If you are here, it’s probable that you completed the installation of taiga-back and taiga-front. 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 and taiga-back should be exposed to the outside, using good proxy/static-file web server. For this purpose we’ll use nginx.

6.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
sudo pip2 install circus
Initial configuration for circus on ~/circus.ini
[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 = $PATH:/home/taiga/.virtualenvs/taiga/bin
TERM=rxvt-256color
SHELL=/bin/bash
USER=taiga
LANG=en_US.UTF-8
HOME=/home/taiga
PYTHONPATH=/home/taiga/.local/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
Setup circus for start on boot putting this on /etc/init/circus.conf
start on filesystem and net-device-up IFACE=lo
stop on runlevel [016]

respawn
exec /usr/local/bin/circusd /home/taiga/circus.ini

And finally start circus:

sudo service circus start

6.2. Nginx

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

First install it:

sudo apt-get install -y nginx

And now let us start configuring it:

Add specific configuration for taiga-front and taiga-back on /etc/nginx/sites-available/taiga.
server {
    listen 80 default_server;
    server_name _;

    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/;
        try_files $uri $uri/ /index.html;
    }

    # Backend
    location /api {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8001/api;
        proxy_redirect off;
    }

    # Django admin access (/admin/)
    location /admin {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        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;
    }
}
Disable the default nginx site (virtualhost)
sudo rm /etc/nginx/sites-enabled/default
Enable the recently created Taiga site (virtualhost)
sudo ln -s /etc/nginx/sites-available/taiga /etc/nginx/sites-enabled/taiga

And finally, restart nginx with sudo service nginx restart

Now you should have the service up and running on http://example.com/

6.2.1. Serving HTTPS

Place your SSL certificates in /etc/nginx/ssl. It is recommended to replace the original configuration for port 80 so that users are redirected to the HTTPS version automatically.

New configuration in /etc/nginx/sites-available/taiga
server {
    listen 80 default_server;
    server_name _;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl default_server;
    server_name _;

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

    index index.html;

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

    # Backend
    location /api {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8001/api;
        proxy_redirect off;
    }

    location /admin {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        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;
    }


    ssl on;
    ssl_certificate /etc/nginx/ssl/example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    ssl_session_timeout 5m;

    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES";
    ssl_prefer_server_ciphers on;

}

Before activating the HTTPS site, the configuration for the front-end and back-end have to be updated; change the scheme from http to https.

Update ~/taiga-back/settings/local.py
from .common import *

MEDIA_URL = "https://example.com/media/"
STATIC_URL = "https://example.com/static/"
ADMIN_MEDIA_PREFIX = "https://example.com/static/admin/"
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_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"
Restart circus after updating the configuration
sudo service circus restart
Update ~/taiga-front/conf/main.json
{
    "api": "https://example.com/api/v1/",
    "eventsUrl": "ws://example.com/events",
    "debug": "true",
    "publicRegisterEnabled": true,
    "feedbackEnabled": true,
    "privacyPolicyUrl": null,
    "termsOfServiceUrl": null,
    "maxUploadFileSize": null,
    "gitHubClientId": null
}
Run gulp task for compile
cd ~/taiga-front
gulp deploy

And nginx:

Reload the nginx configuration
sudo service nginx reload

7. FAQ

7.1. Are you having npm errors when executing gulp?

Delete the tmp files and install the dependencies again:

mv ~/tmp ~/tmp_old
cd ~/taiga-front/
rm -rf ~/.npm; rm -rf node_modules
npm install
bower install
gulp deploy

7.2. How can I change the domain name?

The domain name mainly affects the frontend application, because it needs to comunicate with the backend through the domain/public-ip.

To do this you should update the url value on frontend config file and rebuild frontend with gulp deploy. Also you should update the domain related configuration on the backend settings file: settings/local.py.

And finally reload the backend config with: circusctl reload taiga

7.3. How can I restart the backend application?

The Backend application is running under circus. To restart any application running with circus use the circusctl command:

circusctl restart taiga

7.4. How I can keep my app up to date with the most recent Taiga version?

The Taiga platform is developed on github. For consistences you should alway maintain the same version in time with the stable branch of git or use the last major version of each component.

No packaged version of Taiga is available at this moment.

Frontend application
cd ~/taiga-front
git checkout stable
git pull
npm install
bower install
gulp deploy
Backend application
cd ~/taiga-back
git checkout stable
workon taiga
git pull
pip install --upgrade -r requirements.txt
python manage.py migrate --noinput
python manage.py collectstatic --noinput
circusctl reload taiga