1.1. Install: Ubuntu 12.04 LTS with MySQL and Nginx

This guide will walk you through installing Eve W-Space on Ubuntu 12.04 LTS using a local MySQL server and serving requests with Nginx and Gunicorn. It assumes a clean install and root shell access.

1.1.1. Requirements

  • 764MB RAM with 1GB preferred for high-traffic instances. This may be flexible depending on your specific load.

  • The following packages in addition to the normal core install:

    • git-core
    • build-essential
    • python-dev
    • python-pip
    • nginx
    • bzip2
    • memcached
    • libmysqlclient-dev
    • mysql-server
    • libxml2-dev
    • libxslt-dev
    • rabbitmq-server
    • supervisor

You can install all required packages with the following. You will be prompted for a mysql root password. You may leave this blank if you wish, but it is recommended that you set a secure password and remember it for later.:

$ sudo apt-get install git-core build-essential python-dev python-pip \
  nginx bzip2 memcached libmysqlclient-dev mysql-server libxml2-dev \
  libxslt-dev rabbitmq-server supervisor

Note: if you want to use PostgreSQL, replace libmysqlclient-dev and mysql-server with libpq-dev and postgresql.

You will also be needing to edit text, so make sure to install your favorite text editor if nano or vi (not vim) aren’t your cup of tea:

Next, you will need to upgrade distribute and install virtualenv:::
$ sudo easy_install -U distribute $ sudo pip install virtualenv

Finally, you must create the MySQL database for Eve-Wspace to use::

$ mysql -u root -p
Password:

Enter the root password you set when installing MySQL before:

Then, create the database and grant access to it to a new mysql user called maptool with a password you should remember for later. If you want to simply use the root MySQL user, simply ignore the GRANT PRIVILEGES command.:

mysql> CREATE DATABASE evewspace CHARACTER SET utf8;

mysql> GRANT ALL PRIVILEGES ON evewspace.* TO 'maptool'@'localhost' IDENTIFIED BY '<insert a password>';

mysql> quit

1.1.2. Create a User

You should not run Eve W-Space as root for security. You should create a dedicated account called maptool with a home directory of /home/maptool. You can name this user whatever you want, just replace all instances of /home/maptool with your user’s home directory.:

$ sudo useradd -m -s /bin/bash maptool
$ sudo passwd maptool

1.1.3. Set Up the Home Directory

Let’s become our user for this part to ensure permissions are proper and switch to the install location::

$ sudo su maptool
$ cd /home/maptool

Now, let’s create a directory to be used for serving static files later:

$ mkdir /home/maptool/static

Next, you need to get the Eve W-Space files. You can either clone the latest revision from git or you can download a packaged release and unpack it.

To clone from Github::

$ git clone https://github.com/marbindrakon/eve-wspace.git

To use a packaged release:

You need to download eve-wspace from http://marbindrakon.github.com/eve-wspace/ to get latest zip or tarball package (0.2.2 at time of writing)::

$ wget https://github.com/marbindrakon/eve-wspace/archive/v0.2.2.tar.gz

Then you can unpack the file and rename the directory to eve-wspace to match the clone method::

$ tar xvzf v0.1.1.tar.gz && mv eve-wspace-0.1.1 eve-wspace

1.1.4. Install Eve-Wspace Environment

Next, you should create and activate a virtual Python environment for Eve W-Space so that it cannot conflict with any system Python packages::

$ virtualenv --no-site-packages /home/maptool/eve-wspace
$ source /home/maptool/eve-wspace/bin/activate

You will notice that your shell changes to include (eve-wspace) when the virtual environment is active.

Now you can install the required Python packages::

(eve-wspace)$ pip install -r /home/maptool/eve-wspace/requirements-mysql.txt

Use requirements-postgresql.txt if you are using PostgreSQL.

1.1.5. Configuring local_settings.py

Now for the fun part, copy the local_settings.py.example file to local_settings.py in the same directory, open it up, and edit it to suit your enviornment::

(eve-wspace)$ cd /home/maptool/eve-wspace/evewspace/evewspace
(eve-wspace)$ cp local_settings.py.example local_settings.py
(eve-wspace)$ nano local_settings.py

While editing, you should pay particular attention to the top part of th efile, ensuring that the database statement matches the database, user, and password you created in MySQL earlier and that you add a SECRET_KEY and set the STATIC_ROOT value::

#Example:

# Set this to False for production or you'll leak memory
DEBUG = False
#DEBUG = True

# Set this to a secret value, google "django secret key" will give you
# plenty of generators to choose from

SECRET_KEY = 'sadf98709283j7r098j09a8fd7sdfj89j7f9a8sdf09a8fd'

# Set this to the directory you are service static files out of so that
# manage.py collectstatic can put them in the right place

STATIC_ROOT = "/home/maptool/static/"

DATABASES = {
        'default': {
                'ENGINE': 'django.db.backends.mysql', # Add 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
                'NAME': 'evewspace',                      # Or path to database file if using sqlite3.
                'USER': 'maptool',                      # Not used with sqlite3.
                'PASSWORD': 'really_secure_password',                  # Not used with sqlite3.
                'HOST': '',                      # Set to empty string for localhost. Not used with sqlite3.
                'PORT': '',                      # Set to empty string for default. Not used with sqlite3.
        }
}

Look at the rest of the local_settings.py file and see if there is anything you want to change. The default values for memcached and amqp work for the Ubuntu memcached and rabbitmq defaults.

1.1.6. Initializing the Database

Initializing the database falls into two parts: Loading the Eve static data and initializing the Eve W-Space instance.

1.1.6.1. Static Data

CCP releases a Static Data Export for each major patch in MS SQL format. Steve Ronuken makes MySQL conversions available shortly thereafter. These conversions can be downloaded from http://www.fuzzwork.co.uk/dump/ if you are going to be installing multiple instances, you should download the dump once and re-use it if at all possible.:

(eve-wspace)$ cd /home/maptool
(eve-wspace)$ curl -O https://www.fuzzwork.co.uk/dump/mysql55-odyssey-1.0.12-89967.tgz
(eve-wspace)$ gunzip mysql55-odyssey-1.0.12-89967.tgz
(eve-wspace)$ tar xvf mysql55-odyssey-1.0.12-89967.tgz
(eve-wspace)$ mysql -u maptool -p evewspace < odyssey-1.0.12-89967/mysql55-odyssey-1.0.12-89967.sql

The sql import will take a few minutes to run. When it completes, your MySQL database will have all of the Static Data Export tables available.

1.1.6.2. Initializing Eve W-Space

Next you will need to run several commands to set up the Eve W-Space tables and preload them with data. If you encounter errors here, they are most likely caused by bad settings in local_settings.py, not having the virtual environment activated, or permissions.:

(eve-wspace)$ cd /home/maptool/eve-wspace/evewspace
(eve-wspace)$ ./manage.py syncdb --all --noinput
(eve-wspace)$ ./manage.py migrate --fake
(eve-wspace)$ ./manage.py buildsystemdata
Note:This will take a while (~5-10min)
(eve-wspace)$ ./manage.py loaddata */fixtures/*.json
(eve-wspace)$ ./manage.py defaultsettings
(eve-wspace)$ ./manage.py resetadmin
(eve-wspace)$ ./manage.py syncrss
(eve-wspace)$ ./manage.py collectstatic --noinput

1.1.7. Using the Development Server

If you’ve made it this far, congratulations! Eve W-Space is set up. From here, you can run the console development server directly or continue with setting up the rest of a production environment (Nginx, Gunicorn, Supervisor).

To start the development server::

(eve-wspace)$ cd /home/maptool/eve-wspace/evewspace
(eve-wspace$ ./manage.py runserver 0.0.0.0:8000

Now you can navigate to your server on port 8000 and see your instance. However, you need to have celery running as well for many tasks to work properly. In another shell::

(eve-wspace)$ cd /home/maptool/eve-wspace/evewspace
(eve-wspace)$ ./manage.py celery worker -B --loglevel=info

When both are running at the same time, you should be able to use all functions. If you want things to run a bit more permanently, continue reading.

1.1.8. Setting Up a Production Stack

To serve Eve W-Space in production, you should use a dedicated http daemon to serve static files and either serve the Eve W-Space application itself either through the http daemon itself (as with Apache’s mod_wsgi setup) or through a seperate tool which the http daemon will proxy requests to. This guide follows the latter route.

1.1.8.1. Installing Gunicorn

This guide uses Gunicorn, a lightweight wsgi server written in Python to serve the Django app itself.

To install::

(eve-wspace)$ pip install gunicorn

1.1.8.2. Configuring Supervisor

Unless you want to run celery and gunicorn through the console in screen or tmux, you will want to daemonize them in some way. This guide uses supervisor, but there are many other options available.

At this point, you can log out of the maptool user and go back to your normal account::

(eve-wspace)$ deactivate
$ exit

You need to tell supervisor about the tools you want it to run, to do that, you need to create a config file in /etc/supervisor/conf.d for gunicorn and celeryd::

$ sudo nano /etc/supervisor/conf.d/celeryd.conf

[program:celeryd]
command=python manage.py celery worker -B --loglevel=info
directory=/home/maptool/eve-wspace/evewspace
environment=PATH="/home/maptool/eve-wspace/bin"
user=maptool
autostart=true
autorestart=true
redirect_stderr=True

$ sudo nano /etc/supervisor/conf.d/gunicorn.conf

[program:gunicorn]
command=/home/maptool/eve-wspace/bin/gunicorn_django --workers=4 -b 127.0.0.1:8000 settings.py
directory=/home/maptool/eve-wspace/evewspace/evewspace
environment=PATH="/home/maptool/eve-wspace/bin"
user=maptool
autostart=true
autorestart=true
redirect_stderr=True

To finish it off, you need to stop and then start supervisor to reload the config and start the services::

$ sudo service supervisor stop
$ sudo service supervisor start

And confirm that both started successfully::

$ sudo supervisorctl status

celeryd                          RUNNING    pid 4335, uptime 33 days, 19:16:02
gunicorn                         RUNNING    pid 4302, uptime 33 days, 19:16:03

If either are not in the RUNNING state, either examine the log files in /var/log/supervisor/celeryd-stdout-xxxxxxxxxx.log and /var/log/supervisor/gunicorn-stdout-xxxxxxxx.log or try running them interactively as discussed previously.

1.1.8.3. Configuring Nginx

Now that Eve W-Space itself is running, you need to get people to it. That’s where Nginx comes into play. Configuring Nginx is as simple as filling in one config file, creatng a symlink, and reloading the daemon.:

$ sudo nano /etc/nginx/sites-available/evewspace

    #Example - replace x.x.x.x with your IP or host name if doing name-based vhosts
server {
    listen 80;
    server_name x.x.x.x;
    underscores_in_headers on;

    location /static {
        alias /home/maptool/static;
    }
    location / {
        proxy_pass_header Server;
        proxy_set_header Host $http_host;
        proxy_redirect off;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_connect_timeout 10;
        proxy_read_timeout 30;
        proxy_pass http://127.0.0.1:8000;
    }
}


$ sudo rm /etc/nginx/sites-enabled/default
$ sudo ln -s /etc/nginx/sites-available/evewspace /etc/nginx/sites-enabled/evewspace
$ sudo service nginx reload

Note: if you have multiple virtual domains on your nginx server, put “underscores_in_headers on;” in nginx.conf instead.

Congratulations! Your Eve W-Space instance should now be available at whatever your ip or host name was from the Nginx config. Please see the Getting Started page for your next steps. Keep in mind that your instance will have a default administrator registration code until you change it, so do that ASAP.