h1. How to install EVE Corporation Management?

{{toc}}

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

h2. Dependencies

First thing is to install ECM's dependencies.

h3. Python

First you must install "Python 2.5 or later":http://www.python.org/download/releases/.

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.

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

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

h3. Optional: gevent

See [[InstallationInstructions#Deployment alternatives]]

h2. Install ECM

h3. Runtime files

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

<pre>

$ easy_install -O2 ecm

</pre>

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.

h3. 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":http://www.sqlite.org/ is great for local tests but it is *not suitable for a production usage*. I personally recommend "PostgreSQL":http://www.postgresql.org/ which is *much more reliable* than "MySQL":http://www.mysql.com/, 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":https://docs.djangoproject.com/en/1.4/ref/databases/.

*/!\ 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":http://dev.mysql.com/doc/refman/5.1/en/storage-engine-setting.html.

<pre><code>[mysqld]

default-storage-engine = InnoDB

</code></pre>

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

<pre>

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

</pre>

*/!\ listening port /!\* If you install multiple instances on the same computer and use the embedded server, 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"@

<pre>

root@localhost:~# ecm-admin init /var/www/ecm-instance

...

[ECM] done

</pre>

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@

<pre>

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.

</pre>

h3. Configure Apache httpd

*/!\ Important /!\* if you want to run ECM outside the Apache httpd process, please read [[InstallationInstructions#Deployment-alternatives|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:

<pre>

/etc/apache2

</pre>

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

<pre>

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

</pre>

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:

<pre>

~# chown -R www-data <install_dir>

</pre>

And restart Apache httpd.

h3. 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 [[InstallationInstructions#Deployment-alternatives|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.

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

<pre>

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

</pre> 

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

h1. How to upgrade an existing installation?

h2. Upgrade from a 2.x installation

Update ECM runtime with this command:

<pre>

$ easy_install -U -O2 ecm

</pre>

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

<pre>

$ ecm-admin upgrade <your instance directory>

</pre>

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

<pre>

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

</pre>

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

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

<pre>

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

</pre>

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

<pre>

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

</pre>

*/!\ 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":http://dev.mysql.com/doc/refman/5.1/en/storage-engine-setting.html.

<pre><code>[mysqld]

default-storage-engine = InnoDB

</code></pre>

If your tables are MyISAM and you want to keep your data, you will need to "convert them to InnoDB":http://dev.mysql.com/doc/refman/5.0/en/converting-tables-to-innodb.html.

h3. Do the migration

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

<pre>

# easy_install -U -O2 ecm

</pre>

Then create an instance with ecm-admin:

<pre>

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

</pre>

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

<pre>

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

</pre>

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

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

h2. WSGI servers

I found an "interesting article":http://nichol.as/benchmark-of-python-web-servers presenting a benchmark of several python WSGI servers allowing to do that. I will give some examples here:

h3. Install gevent

You can install *gevent* with @easy_install@:

<pre>

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

</pre>

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

<pre>

~# ecm-admin start <instance directory>

~# ecm-admin stop <instance directory>

~# ecm-admin status <instance directory>

</pre>

or simply run the server in the current shell:

<pre>

~# ecm-admin run <instance directory>

</pre>

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

<pre>

~# aptitude install python-dev

Reading package lists... Done

Building dependency tree

Reading state information... Done

...

</pre>

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

<pre>

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

....

</pre>

@easy_install gevent@ should work now :cuir:

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

<pre>

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

</pre>

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

h3. 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):

<pre>

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

</pre>