How to install EVE Corporation Management?¶

• How to install EVE Corporation Management?
  • Supported Operating Systems
  • Dependencies
    • Python
    • Setup Tools
    • Optional: Mod WSGI
    • Optional: gevent
  • Install ECM
    • Runtime files
    • Prepare the database
    • Create an ECM instance
    • Configure Apache httpd
    • Startup the application
    • Setup the cron job
• How to upgrade an existing installation?
  • Upgrade from a 2.x installation
  • Upgrade from a 1.4.9 installation
    • First of all: BACK-YOUR-SHIT-UP!
    • Do the migration
• Deployment alternatives
  • WSGI servers
    • Install gevent
    • Compile gevent
    • On Windows
  • Setup the reverse proxy
    • Apache HTTPD
    • nginx
    • Microsoft IIS

Supported Operating Systems¶

I only tested the installation into Apache with modWSGI on linux debian 5 (I guess it works on any unix like OS, even mac OS). However, on Windows, I cannot guarantee it will work...

Dependencies¶

First thing is to install ECM's dependencies.

Python¶

First you must install Python 2.5 or later.

We don't use Python 3.0 because Django doesn't support it.

Do not forget to add the python to the path, if not already.

Setup Tools¶

Setup Tools is a python library that adds a easy_install command to your system. easy_install is a cool utility that allows you to install (almost) any python library/app with a simple command line.

To install setuptools: http://pypi.python.org/pypi/setuptools

Note: On debian, aptitude install python-setuptools will install it easily.

Check if easy_install is in your system path. If not, you will find it in the Scripts dir in your python installation folder.

Optional: Mod WSGI¶

This is a very effective Apache mod for executing Python applications.

Here is the home site http://code.google.com/p/modwsgi/

I recommend to install it through your OS's embedded package manager (e.g. apt-get or rpm) if you are on a linux distribution. Or to download the source package and compile it.

Optional: gevent¶

See InstallationInstructions

Install ECM¶

Runtime files¶

ECM is available as a package in the Python Package Index. Simply run:

$ easy_install -O2 ecm

It will download and install all python dependencies of ECM and ECM itself (the -O2 is to tell python to compile optimized byte code).

Once this is done, you will have a ecm-admin tool installed. Check if it is in your path and continue.

Prepare the database¶

You first need to create a database for the instance along with a user that has the rights to do anything in it (create tables, etc.).

Note: SQLite is great for local tests but it is not suitable for a production usage. I personally recommend PostgreSQL which is much more reliable than MySQL, especially for database schema migrations. Also, make sure you have the python database driver corresponding to your database engine. You can find more information here.

/!\ IMPORTANT /!\ MySQL storage engine: ECM uses database transactions that only work with InnoDB tablespaces (see #129). You need to configure your server to enable InnoDB by default.

[mysqld]
default-storage-engine = InnoDB

Create an ECM instance¶

Once this is OK, you can go and create your instance. I would recommend to create it in a standard location (eg /var/www). Here is an example of running the ecm-admin create function:

root@localhost:~# ecm-admin create /var/www/ecm-instance
[ECM] Database engine? {oracle|sqlite|postgresql|mysql} [default=sqlite] mysql
[ECM] Database name? [default=ecm] ecm
[ECM] Database user? [default=ecm] ecm
[ECM] Database password? [default=ecm] mysecretpassword
[ECM] External host name? ecm.corpurl.com
[ECM] Email of the server administrator? (for error notifications) admin@corpurl.com
[ECM] Email used as "from" address in emails sent by the server? noreply@corpurl.com
[ECM] Embedded server listening address? [default=127.0.0.1]
[ECM] Embedded server listening port? [default=8888]
[ECM]
[ECM] New ECM instance created in "/var/www/ecm-instance".
[ECM] Please check the configuration in "/var/www/ecm-instance/settings.ini" before running `ecm-admin init "/var/www/ecm-instance"`.

/!\ listening port /!\ If you install multiple instances on the same computer and use the embedded server (see deployment alternatives), make sure you assign different ports to each one of them. If you don't, you won't be able to run them. If you run in Apache httpd with mod_wsgi you can ignore this.

after that you need to run the init function. ecm-admin init "/var/www/ecm-instance"

root@localhost:~# ecm-admin init /var/www/ecm-instance
...
[ECM] done

Note: you can pass all installation options directly on the command-line to avoid annoying prompts. All the arguments can be listed by typing: ecm-admin create -h or --help

root@localhost:~# ecm-admin help create
Usage: ecm-admin create [OPTIONS] instance_dir

Options:
  -h, --help            show this help message and exit
  -q, --quiet           Do not prompt user (use default values).

  Database options:
    --db-engine=DB_ENGINE
                        DB engine ['oracle', 'sqlite', 'postgresql', 'mysql']
    --db-name=DB_NAME   Database name
    --db-user=DB_USER   Database user
    --db-password=DB_PASS
                        Database user password

  Web & Mail options:
    --host-name=HOST_NAME
                        The public name of ECM host computer.
    --admin-email=ADMIN_EMAIL
                        Email of the server administrator (for error
                        notifications)
    --server-email=SERVER_EMAIL
                        Email used as "from" address in emails sent by the
                        server.

  Server options:
    --bind-address=BIND_ADDRESS
                        Server listening address
    --bind-port=BIND_PORT
                        Server listening address
    --run-as-user=RUN_AS_USER
                        User that will be running the server
    --pid-file=PID_FILE
                        File where to store the PID of the server process.

Configure Apache httpd¶

/!\ Important /!\ if you want to run ECM outside the Apache httpd process, please read the deployment alternatives.

Next thing you need to do is modify your apache configuration. Include the /var/www/ecm-instance/examples/apache_mod_wsgi_vhost.example file to your Apache configuration.

Explanation: ECM is developed for Django and is written in Python. Django as an application server serves the dynamic and Apache as an web server the static content(like pictures, javascript, ...). Since Apache "can't deal" with python by default, you need to make sure you have apache_mod_wsgi installed and running, to make everything work. (The fact ECM starts doesn't mean the content get's served properly or even at all).

Once mod_wsgi is running, you have to point apache to the static content of your ecm instance, so it knows what static content to serve. This is the step of creating the symbolic link refers to.

Depending on the Linux flavour you are running, you can usually find the folder to configure apache under:

/etc/apache2

So in the case of debian i would do something like this:

root@debian:/etc/apache2/sites-enabled# ln -s /var/www/<instance-folder>/examples/apache_mod_wsgi_vhost.example 001-my-ecm-instance

Note: the folder under debian is /etc/apache2/sites-enabled, in which the symbolic link is created.

"That should do the trick".

Besides slightly different ways to configure apache for most flavours of linux, it is important to note, that if you are running on a shared host, above steps might not apply at all or some directives in the vhost configuration created with your instace may not be available. In this case you will have to check with your hoster how to perform the apache configuration. In most cases you might find step-by-step guides from your hoster or on the web.

Important: you should make sure that the user that is running apache (usually www-data) has the permission to write in the installation directory (and all its sub directories). If not, ECM will crash at startup. You can do that with the following command:

~# chown -R www-data <install_dir>

And restart Apache httpd.

Startup the application¶

• First you have to start/restart/reload Apache httpd (and maybe start your instance's dedicated WSGI server if you went for deployment alternatives).
• Access the server at the URL you configured during the installation with the user admin password adminecm (change the password as soon as possible!!!)
• When you log in you will be prompted to provide a corp api key. please provide a full corp key to access all features and future features. but you can limit it if you want.
• After the api key has been entered, ecm will run all updates to pull info from the web api.

Setup the cron job¶

In order to enable ECM auto-update, you need to setup a cron job that will invoke a specific command on a regular basis.

Edit your crontab with crontab -e and add this line:

*/5 * * * *   /usr/local/bin/ecm-admin manage <full path to ecm instance> update --cron --silent

NB: You will find log files in the <instance_dir>/logs folder.

How to upgrade an existing installation?¶

Upgrade from a 2.x installation¶

Update ECM runtime with this command:

$ easy_install -U -O2 ecm

Then you will need to upgrade your instance(s) with ecm-admin upgrade:

$ ecm-admin upgrade <your instance directory>

There are some options on the upgrade subcommand that you can see with ecm-admin help upgrade:

$ ecm-admin help upgrade
Usage: ecm-admin upgrade [OPTIONS] instance_dir

Options:
  -h, --help            show this help message and exit
  --no-syncdb           Do not modify the instance's database.
  -u, --upgrade-from-1.4.9
                        Upgrade from ECM-1.4.9.
  --eve-db-url=EVE_DB_URL
                        URL where to download EVE database archive.
  --eve-db-zip-archive=EVE_ZIP_ARCHIVE
                        Local path to EVE database archive (skips download).
  --skip-eve-db-download
                        Do NOT download EVE db (use with care).
  --from-ccp-dump       Update EVE database from CCP official dump (can take a
                        long time).
  --ccp-dump-url=CCP_DUMP_URL
                        URL where to download CCP official dump.
  --ccp-dump-archive=CCP_DUMP_ARCHIVE
                        Local archive of CCP official dump (skips download).
  -s, --symlink-files   Create symbolic links instead of copying static files.

Upgrade from a 1.4.9 installation¶

Important: if you have a pre 1.4.9 installation, please upgrade it to 1.4.9 before applying this migration. It has good chances to fail if you don't.

If you are a 1.4.9 user you will need to follow these steps to upgrade your installation to 2.0:

First of all: BACK-YOUR-SHIT-UP!¶

You will be sorry if you didn't. Here's how to do it in a database agnostic way. Go in your ecm-1.4.9 installation dir and run the following commands:

$ ./manage.py dumpdata auth.User auth.Group common corp roles scheduler assets accounting > ~/ecm_dump-1.4.9.json

This json file contains all your data from 1.4.9 that can be restored (in case of problem) with

$ ./manage.py loaddata ~/ecm_dump-1.4.9.json

/!\ IMPORTANT /!\ MySQL storage engine: ECM uses database transactions that only work with InnoDB tablespaces (see #129). You need to configure your server to enable InnoDB by default.

[mysqld]
default-storage-engine = InnoDB

If your tables are MyISAM and you want to keep your data, you will need to convert them to InnoDB.

Do the migration¶

Once your data has been backuped, you can install ECM runtime files:

# easy_install -U -O2 ecm

Then create an instance with ecm-admin:

# ecm-admin create /var/www/ecm-instance
[ECM] Database engine? {oracle|sqlite|postgresql|mysql} [default=sqlite] <your database server>
[ECM] Database name? [default=ecm] <1.4.9 database name>
[ECM] Database user? [default=ecm] <1.4.9 database user>
[ECM] Database password? [default=ecm] <1.4.9 database password>
[ECM] External host name? ecm.corpurl.com
[ECM] Email of the server administrator? (for error notifications) admin@corpurl.com
[ECM] Email used as "from" address in emails sent by the server? noreply.corpurl.com
[ECM] Embedded server listening address? [default=127.0.0.1]
[ECM] Embedded server listening port? [default=8888]
[ECM]
[ECM] New ECM instance created in "/var/www/ecm-instance".
[ECM] Please check the configuration in "/var/www/ecm-instance/settings.ini" before running `ecm-admin init "/var/www/ecm-instance"`.

Ignore the message saying that you should run ecm-admin init and run:

# ecm-admin upgrade --from-1.4.9 /var/www/ecm-instance

If this runs without errors, you've successfully migrated your installation to 2.0.

Deployment alternatives¶

The idea is to run all python code into a dedicated python WSGI application container, and serve all static files with a standard HTTP server.

WSGI servers¶

I found an interesting article presenting a benchmark of several python WSGI servers allowing to do that. I will give some examples here:

Install gevent¶

You can install gevent with easy_install:

~# easy_install -U -O2 gevent
Downloading/unpacking gevent
  Running setup.py egg_info for package gevent
Downloading/unpacking greenlet (from gevent)
  Running setup.py egg_info for package greenlet
Installing collected packages: gevent, greenlet
  Running setup.py install for gevent
    building 'gevent.core' extension
    gcc -pthread -fno-strict-aliasing -DNDEBUG -g -fwrapv -O2 -Wall -Wstrict-prototypes -fPIC -I/usr/include/python2.5 -c gevent/core.c -o build/temp.linux-i686-2.5/gevent/core.o
    gcc -pthread -shared -Wl,-O1 -Wl,-Bsymbolic-functions build/temp.linux-i686-2.5/gevent/core.o -levent -o build/lib.linux-i686-2.5/gevent/core.so
    Linking /root/build/gevent/build/lib.linux-i686-2.5/gevent/core.so to /root/build/gevent/gevent/core.so
  Running setup.py install for greenlet
    building 'greenlet' extension
    gcc -pthread -fno-strict-aliasing -DNDEBUG -g -fwrapv -O2 -Wall -Wstrict-prototypes -fPIC -I/usr/include/python2.5 -c greenlet.c -o build/temp.linux-i686-2.5/greenlet.o
    gcc -pthread -shared -Wl,-O1 -Wl,-Bsymbolic-functions build/temp.linux-i686-2.5/greenlet.o -o build/lib.linux-i686-2.5/greenlet.so
    Linking /root/build/greenlet/build/lib.linux-i686-2.5/greenlet.so to /root/build/greenlet/greenlet.so
Successfully installed gevent greenlet
Cleaning up...

Once gevent is installed, you can use ecm-admin daemon with these commands:

~# ecm-admin start <instance directory>
~# ecm-admin stop <instance directory>
~# ecm-admin status <instance directory>

or simply run the server in the current shell:

~# ecm-admin run <instance directory>

Compile gevent¶

If easy_install gevent failed it means that you miss some dependencies. It needs to be compiled as it is a C extension so you will need python C headers.

Example on debian linux:

~# aptitude install python-dev
Reading package lists... Done
Building dependency tree
Reading state information... Done
...

Also, you will need libevent headers (version 1.4.2 or later is required by gevent):

~# aptitude install libevent-1.4.2 libevent-dev
Reading package lists... Done
Building dependency tree
Reading state information... Done
Reading extended state information
Initializing package states... Done
The following NEW packages will be installed:
  libevent-dev
0 packages upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
....

easy_install gevent should work now :cuir:

On Windows¶

If you don't feel like compiling all that on Windows (which could be a pain in the %$@#), just use gevent and greenlet precompiled python libraries that you'll find here:

• http://www.lfd.uci.edu/~gohlke/pythonlibs/#gevent
• http://www.lfd.uci.edu/~gohlke/pythonlibs/#greenlet

You can now run ecm with its embedded gevent WSGI server with a simple command:

C:\> ecm-admin run <path to your ecm instance>

Note that on Windows, daemonizing processes can only be done through the services system. As we are not Micro$oft experts, we didn't acutally code a windows service. Fortunately, there is a tool that allows running any application as a service (another unofficial guide here).

You can download it as part of the Windows Server 2003 Resource Kit.

Setup the reverse proxy¶

Once the WSGI application server is running, you can set-up the reverse proxy that will serve static files and relay all non-static requests to your WSGI server. This is important that the python WSGI server does not serve static files it will imply unnecessary load on it.

Apache HTTPD¶

You will find an example virtual host config in your instance directory under examples (mod_proxy and mod_proxy_http need to be enabled):

# vim: set filetype=apache:
<VirtualHost *:80>

    DocumentRoot "/var/www/ecm-instance" 
    ServerName "ecm.yourcorp.url" 

    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>

    ProxyPreserveHost On
    ProxyPass /static/ !
    ProxyPass / http://127.0.0.1:8888/

    <Directory "/var/www/ecm-instance/static">
        Order deny,allow
        Allow from all
        Options -Indexes
    </Directory>

</VirtualHost>

nginx¶

TODO

Microsoft IIS¶

In order to redirect the requests to the WSGI server (that runs in a separate process), you will need to install 2 modules:

• URL Rewrite
• Application Request Routing

Here's some more info on this: http://learn.iis.net/page.aspx/659/reverse-proxy-with-url-rewrite-v2-and-application-request-routing/

TODO: add an example