Skip to content

Installation on a production environment

Thomas Chopitea edited this page Sep 16, 2016 · 18 revisions

Before you start: The production environment is great for running FIR with performance and stability (eg. a real RDBMS) in mind. If you want to test FIR just to get acquainted with it or if you want a quick install, we recommend you follow the instructions in Installation on a production environment.


This will explain how to install FIR on a production environment. As an example, we will be using nginx as a reverse-proxy and MySQL as DBMS. Feel free to adapt it to you own needs (PostgreSQL, Apache, etc.)

If you just want to test FIR or set-up a development environment, check out the Setting up a development environment page.

This procedure was tested on a Ubuntu 14.04 system (minimal install) on a VM.

Install Prerequisites

Install the prerequisites for running FIR with MySQL and nginx:

$ sudo apt-get update
$ sudo apt-get install mysql-server libmysqlclient-dev gettext python-dev python-pip python-lxml git libxml2-dev libxslt1-dev libz-dev nginx

Configure MySQL database

Create users:

$ mysql -uroot -p
> CREATE DATABASE fir;
> CREATE USER 'fir'@'localhost' IDENTIFIED BY 'THIS_IS_A_PASSWORD_CHANGE_ME_PLZ';
> GRANT USAGE ON *.* TO 'fir'@'localhost';
> GRANT ALL PRIVILEGES ON `fir`.* TO 'fir'@'localhost';

Install FIR

If you want to use a virtual environment, follow these steps:

$ sudo pip install virtualenv
$ virtualenv env-FIR
$ source env-FIR/bin/activate           # Switch to virtualenv

Note: if you're using virtual environments, the next steps will have to be adjusted (i.e. do not run pip with sudo).

Clone the GitHub repo:

$ git clone https://github.com/certsocietegenerale/FIR.git

cd into the FIR directory and install Python dependencies:

$ cd FIR
$ sudo pip install -r requirements.txt       # Install dependencies
$ sudo pip install mysql-python

Create a production configuration file by copying the fir/config/production.py.sample to fir/config/production.py

$ cp fir/config/production.py.sample fir/config/production.py

Change the settings in the production.py file according to your setup. This includes the ALLOWED_HOSTS directive - change it to whatever vhost you're planning to use in your deployment. Also, remember to change the timezone in base.py

If you want to enable the plugins, copy the fir/config/installed_apps.txt.sample file to fir/config/installed_apps.txt:

$ cp fir/config/installed_apps.txt.sample fir/config/installed_apps.txt

Create the tables in the database:

$ ./manage.py migrate --settings fir.config.production

Create a superuser:

$ ./manage.py createsuperuser --settings fir.config.production

You will be asked for super-user account credentials. Enter them to continue.

Import initial data (you can change these later from the Django backend):

$ ./manage.py loaddata incidents/fixtures/seed_data.json --settings fir.config.production

Collect static files (these will be cached for better performance)

$ ./manage.py collectstatic --settings fir.config.production 

You'll need to change some permissions in order for the www-data to be able to access log files and write to the uploads directory:

$ sudo chown www-data logs/errors.log uploads
$ sudo chmod 750 logs/errors.log uploads

If you want to use internationalization:

$ cd incidents
$ django-admin.py compilemessages

This will generate a bunch of .mo files that Django will use for translating the UI. This command should also be run in the directories of plugins that support internationalization.

uWSGI

We need to install uWSGI in order to serve our application:

$ sudo pip install uwsgi

Change www-data's shell:

$ sudo chsh www-data
Changing the login shell for www-data
Enter the new value, or press ENTER for the default
	Login Shell [/usr/sbin/nologin]: /bin/sh

Create a directory for the socket:

$ mkdir run
$ sudo chown www-data run

Next, create a file in /etc/init/fir.conf with the following contents:

description "FIR - Django uWSGI"

start on runlevel [2345]
stop on runlevel [!2345]

setuid www-data
setgid www-data

respawn

exec uwsgi --socket /path/to/your/FIR/install/run/fir.sock --chdir /path/to/your/FIR/install/ --module fir.wsgi

The exec line must be adjusted if you're using a Python virtual environment.

To start the daemon, run sudo start fir. To restart it, run sudo restart fir. To stop it, sudo stop fir. You get it.

Please note that it will only work if your configuration file is fir/config/production.py. Otherwise, you will need to update the file fir/wsgi.py with the correct settings module.

Alternatively, if you're using systemd, the following script in /etc/systemd/system/fir_uwsgi.service should work:

[Unit]
Description=uWSGI instance for FIR
After=syslog.target

[Service]
User=nginx
Group=nginx
WorkingDirectory=/path/to/your/FIR/install/
ExecStart=/usr/bin/uwsgi --socket /path/to/your/FIR/install/run/fir.sock --chdir /path/to/your/FIR/install/ --module fir.wsgi
Restart=always
KillSignal=SIGQUIT
Type=Debug
StandardError=syslog
NotifyAccess=All

[Install]
WantedBy=multi-user.target

Then run:

$ sudo service fir_uwsgi start

nginx

Download uwsgi params:

$ wget https://raw.githubusercontent.com/nginx/nginx/master/conf/uwsgi_params -P run

Remove the default configuration file:

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

Create a /etc/nginx/sites-available/fir file with the following contents:

upstream fir {
	server unix:///path/to/your/FIR/install/run/fir.sock;
}

server {
	server_name FIR.DOMAIN.COM;

	location / {
		uwsgi_pass fir;
		include /path/to/your/FIR/install/run/uwsgi_params;
	}

	location /static/ {
		alias /path/to/your/FIR/install/static/;
	}
}

Make sure you replace FIR.DOMAIN.COM with the host you will be using to host your FIR install. This should match what you specified in the ALLOWED_HOSTS directive in production.py. (This solves error 400 problems as described in #46)

Enable the configuration:

$ sudo ln -s /etc/nginx/sites-available/fir /etc/nginx/sites-enabled/fir
$ sudo service nginx reload

Create initial data

Since you're not inputing any test data, you must manually populate different elements needed for FIR to work: users, incident categories, business lines / customers, and some labels. Everything can be done from the admin panel on http://localhost/admin with superuser credentials.

Creating labels

Labels are used to populate choices in some incident fields:

  • Detection source
  • Actions taken
  • Actor
  • Plan

FIR uses these "label groups" to know how where to map the labels. If you followed the steps above, labels should already be set with some defaults.

The four mandatory label groups are detection, action, actor, and plan. You can add these through the admin interface in the "Label groups" section.

You should then specify options for each of the labels. Remember that an incident has a mandatory detection field, and comments have a mandatory action field; You'll need to populate at least those two. Other fields are optional, but we strongly encourage you to use them. For a more complete list of what we recommend you to use, inspire yourself from the fixtures in incident/fixtures/seed_data.json

Creating users

Point your web browser to http://fir.domain.com/admin/ and log in with the superuser credentials you specified during install. If you imported users from the provided fixtures, the default superuser credentials are admin:admin.

Once you're logged in, click on the Add button in the Users row. Fill-in the fields and click on save. On the next screen, go to the Groups section, click on "incident handlers", and on the arrow to add it to the column "Chosen groups". Click on Save at the bottom of the screen.

Next, you need to add a profile to the user (this will be automated in future releases). Still logged in as the super-user, click on "Add" in the "Profiles" row of the admin panel. Select the created user and chose the number of incidents they will see in their view. Click "Save", and log out.

You made it! You can now log-in with the newly created user and start handling incidents like a boss by pointing your browser to http://fir.yourdomain.com/.

Keeping your FIR installation up-to-date

Pull the repo:

$ git pull

Apply migrations, if any:

$ ./manage.py migrate --settings fir.config.production

Update static files, if necessary:

$ ./manage.py collectstatic --settings fir.config.production

Restart the server:

$ sudo restart fir
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.