History

Wiki »

« Previous - Version 32/47 (diff) - Next » - Current version
diabeteman, Apr 26, 2012 02:47 am

How to install EVE Corporation Management?

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

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

$ easy_install ecm

It will download and install all python dependencies of ECM and ECM itself.

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

Create an ECM instance

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

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

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"`.

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

Don't forget to include the /var/www/ecm-instance/examples/apache_mod_wsgi_vhost.example file to your Apache configuration (creating a symbolic link should do the trick)

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>

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.

Startup the application

  • First you have to start/restart Apache.
  • 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 you will have to wait until the crontab is triggered for ecm to pull its settings.

Setup the cron job

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

Edit your crontab with crontab -e and add this line

*/5 * * * *   /usr/bin/curl -u cron:cron http://<your url>/scheduler/cron/ >/dev/null 2>&1

Don't forget to change the password of ECM's cron user through the admin interface for security reasons :-)

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

Do the migration

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

# easy_install -U 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.

Configure Apache httpd

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 (creating a symbolic link should do the trick)

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.

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 library

First, you need to install python gevent library. 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.
....

Once you have the C hearders, you can install gevent with easy_install:

~# easy_install 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>

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:

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

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

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>

    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>