How to install Maymyo

If you are installing Maymyo to evaluate, then you need to :-

If you want to run our bundled JasperReport reports, then continue with :-

If you want to develop your own JasperReport reports, then :-

If you are setting up Maymyo for production, these are the additional actions :-

Install software packages required to run Maymyo

Maymyo is a Django web application that uses a relational database to store its data. Django is a python application and Maymyo uses a few third party python packages.

We will not attempt to repeat the installation instructions of these software packages but we will give you helpful hints where applicable. You should consider yourself ready to install Maymyo only after you have managed to install and run these pre-requisite software packages :-

  • python, version >= 2.5 (2.7 preferred) but not 3 (yet) and

    install the following packages:-

    Hint

    We prefer to download the binary installer for our specific Operating System and Architecture, eg on Windows 64 bit, we would download the Windows Python 2.7 x86-64 Installer. For Debian-based Linux, we prefer to use apt-get, eg sudo apt-get install python2.7 on Ubuntu.

    • setuptools, version >= 0.6. Download its zip or tgz (tar gzip) file, extract to a temporary directory, open a Command Prompt and change to that temporary directory and enter “python setup.py install”. On Ubuntu or other Debian-based systems, we would use sudo apt-get install python-setuptools.

    Hint

    If you are installing on Windows 32 bit, just download the installer for your python version and run it.

    Hint

    If you are installing for the Windows 64 bit, then follow the instructions here. Right-click on the ez_setup.py link and save the link in a working directory. Open a Command Prompt in that working directory and run “python ez_setup.py”. This will perform the necessary installation for you. You have to do this because the downloads provide only the 32 bit installer.

    Hint

    Use easy_install to install python modules after installing setuptools.

    You can easily install other python modules by entering:

    > easy_install module_name

    on the command line. On Windows, ensure that your PATH environment variable has python’s Scripts directory. (eg on Windows, PATH=C:\\Python27;C:\\Python27\\Scripts;....;) This is where easy_install.exe lives. On Debian-based Linux, you need to use:

    $ sudo easy_install module_name

    instead. You will be prompted for the your password.

    • pytz, for timezone handling. Use easy_install pytz
    • pyDes, encryption module. Use easy_install pydes
  • Django, version >= 1.4, because we are using its backward incompatible features. We can use easy_install django to install it. Earlier versions will not work.

    Note

    If you have an earlier version of django installed, you can remove it by deleting the django directory from your Python’s site-packages. Alternatively, you may choose to use *virtualenv*.

  • Databases, you may choose one of the following:-

    • postgresql, version 9 onwards with psycopg2, its python database interface (DBI) driver.

    • mysql, version 5.0.3 onwards with mysql python, version 1.2.3 onwards

      Hint

      On Debian-based Linux, Install postgresql and mysql above by:

      sudo apt-get install postgresql
      sudo apt-get install python-psycopg2
      sudo apt-get install mysql-server
      sudo apt-get install python-mysqldb
    • sqlite3 - as at django version 1.4, we have a “Too many SQL variables” error during syncdb. Furthermore, our JasperReport runtime cannot connect to it too. We are not supporting sqlite3 at the moment until we sort these out.

    • Please refer to Django’s documentation for other supported databases.

Download and Install Maymyo

You may download the latest Maymyo release file at Maymyo’s project home and extract it to a directory that you plan to run in. The release file will have its version number as the root directory, eg 0.3.0. You may rename it.

Note

If you do not want to pollute your environment with our required environment variables, then create a new user and extract the release file in its home directory.

on Windows, you may extract to C:\work. Then rename the version number to maymyo. In this case, your application home directory will be C:\work\maymyo. All further steps thereafter will be relative to this Application Home directory. We will refer to this as maymyo_home.

If you plan to add your own application, it will be a sibling directory to Maymyo’s applications, eg C:\work\maymyo\myapp.

Configure your database and environment

The first thing to do is to prepare your database.

  • We assume you know how to administer a database, either using their command line tool (the hard way) or their GUI tool.
  • for postgresql, create a user, database and schema, eg all named maymyo. Make the user maymyo own both the database and schema. Use pgAdmin III GUI tool for this.
  • for mysql, create a database and user, eg all named maymyo. Grant all permissions on the database to this user. Use mysql’s Administrator GUI tool for this.
  • please refer to your database manuals on how to perform the above.
  • Django will later create the required database tables automatically. But you need to provide it with a user to connect to the database (in its settings.py file).

Then edit your environment variables.

_images/env_vars_win.png

Changing environment variables on Windows. To get to the screen above, right-click on “My Computer” and select “Properties”. Then choose the “Advanced” tab and click on “Environment Variables” button somewhere near the bottom.

Edit or Add the following User environment variables:-

  • DJANGO_SETTINGS_MODULE = maymyo.settings
  • PYTHONPATH = maymyo_home eg on Windows, set PYTHONPATH=C:\work\maymyo
  • add to PATH your Python installation directories and maymyo_home/bin eg on Windows, add C:\Python27;C:\Python27\Scripts;C:\work\maymyo\bin; to your PATH.

Note

On Ubuntu, you should create a user maymyo whose home directory is where Maymyo will reside. Edit the file ”.profile” in this home directory. For other unixes, this may be ”.bash_profile”, depending on the user’s shell. A user’s default PATH would already include /usr/bin:/usr/local/bin where python, easy_install and django-admin.py is installed. So you would just need to add your maymyo_home/bin to PATH. Edit the .profile file in Maymyo’s home directory. It would also be a good idea to add ”.” (current directory) to PATH. Saves you the hassle of typing ”./”. Your changes should look like this:

export DJANGO_SETTINGS_MODULE=maymyo.settings
export PYTHONPATH=maymyo_home
export PATH=.:maymyo_home/bin:$PATH

You should logout and login again for the new environment variables to take effect. After re-login, verify that the new environment variables are in effect by, on Windows:

> echo %PYTHONPATH%

or on Unix platforms:

$ echo $PYTHONPATH

The output should display your maymyo_home. If it is empty or wrong, please repeat the above.

Edit your Maymyo config files to reflect your installation specific values.

  1. Edit DATABASES in settings.py file in maymyo_home/maymyo for your database choice:

    DATABASES = {
        'default': {
            'NAME': 'maymyo',
            'ENGINE': 'django.db.backends.postgresql_psycopg2',
            # 'ENGINE': 'django.db.backends.mysql',
            'USER': 'maymyo',
            'PASSWORD': 'maymyo',
            'HOST': '',
            'PORT': '',
        }
    }
    
  2. Note that NAME above refers to the database name you have created.

  3. Uncomment the ENGINE you are using and comment out the one you are not using. ie in the above example, we are using postgresql and not mysql.

  4. Set PASSWORD to whatever you used when preparing your database.

  5. Leave HOST and PORT blank if you are using localhost and the database’s default port respectively.

  6. Edit RUN_HOME in settings.py. This is where Maymyo will send outputs to during runtime. You should choose a separate directory from maymyo_home:

    RUN_HOME = os.path.join(os.path.dirname(APP_HOME), 'mayrun')
    

    The above will make the run home directory mayrun a sibling of your maymyo_home. You can also specify an absolute directory path but ensure you have double back-slashes for Windows.

Prepare your Application Directories and Files

We need to ensure that directory permissions and executable modes are okay.

  • goto the maymyo_home /bin directory and:

    $ python prepare_app.py
  • the above will collect all required static files, create the run home directory you specified earler and change the executable modes of our scripts in the bin directory.

Create and Load Maymyo Database objects

  1. You should perform a check on your database connection. Open a new Terminal (or Command Prompt on Windows) window:

    > django-admin.py validate

    Note

    We prefer to use django-admin.py instead of manage.py because it is in the PATH. You can still use manage.py as long as your current directory ”.” is in the PATH. In this case, use “manage.py validate” instead while you are in maymyo_home.

  2. Create the database objects for Django and Maymyo:

    > django-admin.py syncdb
  3. You will be prompted to create the django superuser and set its password. You must use “admin” as the user name because our fixtures data use this. You will need this to login to Maymyo later.

  4. Change directory to your maymyo_home. Load Maymyo’s standard fixtures data for its applications:

    > load_fixtures.py

    You will see a lot of output messages telling you what has been created. fixtures is a Django term describing the initial setup data to be loaded into database tables.

    Note

    Do not worry if you see “Language ms is not supported”. This is because we have not found the the people to volunteer to translate Malay (national language of the authors) for Django. Besides, we have not translated Maymyo to Chinese, so when you choose it on log in, you will only see the Django translations and Maymyo will still be in English.

  5. If you want to load our test data. Skip this if you are setting up for production.:

    > load_fixtures.py testdata

Run Maymyo

  1. We need to change the environment for the Task Queue, Output Queue and Reporting engines if you are running on unix-based platforms (because the fixtures defaults to Windows), open a Terminal and do this:

    > prepare_env.py
  2. You are now ready to run Maymyo and add your own application:

    > django-admin.py runserver
  3. Open your browser and connect to Maymyo with:

    http://localhost:8000/maymyo/

    Login with the superuser (and password) you created earlier during syncdb, ie “admin”. You should now be connected to Maymyo’s Dashboard as shown below.

    Note

    The above URL assumes that you are logging in from the same computer as the one you installed Maymyo in. If not, please change the host name (ie localhost). If your firewall is on, remember to open up port 8000 for remote connections. You can run on another port by adding the port number after “runserver” above.

    _images/dashboard.png

    Your Dashboard on FireFox.

  4. Change the Application Parameter Set used to define your installation’s Environment Variables. Click on the Menu “Maintain Infrastructure Master Files” in the “Your Menus” list on the left panel of the Dashboard. Choose the Menu Item “Maintain Application Parameter Sets” and double-click. Find the Parameter Set “WINDOWS-ENV” (or “UNIX-ENV” for posix platforms) to change. This Parameter Set is used dynamically for Task Queues, Output Queues and Reporting Engines. You should change the PATH, PYTHONPATH and JAVA_HOME parameters to your installation’s specific directories, similar to the above environment variables.

  5. If you are just evaluating or setting up a development environment, you can start Maymyo daemons manually by opening a Command Prompt:

    > start_all_daemons.py
  6. To stop the daemons.py:

    > stop_all_daemons.py
  7. You can skip the above if you want to start and stop the daemons automatically with the Operating System. This is discussed next.

  8. You can stop here if you want to evaluate Maymyo only, enjoy!

Installing Java Runtime Environment

If you want to run JasperReport reports, then you will need the Java Runtime and jaspercommand.

Download and Install jaspercommand

You need this package to be able to run JasperReport reports on the command line. This package is a fork of GT webMarque Ltd’s RunJasperReports. Download either the latest zip or tar compressed file (tgz) from jaspercommand home.

Extract the zip or tgz file to a working directory and copy the entire contents of its javalib directory to maymyo_home. That’s all. Your new directory should look like below. It contains all the jar files needed to run JasperReport on the command line (both interactively and using the Task Queue).

_images/javalib_dir.png

jaspercommand’s javalib destination

For developing JasperReport reports

iReport and apache ant are required for developing reports. If you prefer to use other reporting tools, then this is optional. You will however, need to write your own ReportingEngine to allow Maymyo to run your reports. Please refer to our infra/custom/jasper_command.py to see how we did it for JasperReport.

Java Runtime Environment and jaspercommand is a pre-requisite.

  • iReport, when you want to create or modify JasperReport reports

    Note

    Add Maymyo home directory to iReport’s classpath.

    You should specify your reports’ external resources (ie images, external styles, subreports) relative to Maymyo home.

  • Apache ant, to compile your JasperReport design files in bulk.

    Note

    Ensure that the ant bin directory is in the PATH environment variable.

    Not required if you prefer to use iReport to compile your reports.

Configure and auto-start Maymyo Daemons for Production

Maymyo Daemons are a set of programs that will run in the background to provide services like Task Queueing, Scheduler, Output Spooling and delivering external messages for your applications. This section shows you how to set them up for Production use.

Note

Skip this step if you are only evaluating or setting up a development environment.

You should edit the maymyo_home/snippets/envvars.ini file. Whether on Windows or Unix, the daemons need a user whose initial environment variables PATH and PYTHONPATH having maymyo_home/bin and maymyo_home respectively to bootstrap the program responsible for starting and stopping individual daemons. Then for the daemons themselves, the envvars.ini is used as their environment. This is where we place additional environment variables required by the daemons. This should be a superset of variables needed by the daemons.:

[windows]
# ----------------------------------------------------------
# Windows, cannot use %VAR% because not expanded in Services
# Path first, so that we run our scripts.
PATH=C:\work\maymyo\bin;C:\Python27;C:\Python27\Scripts;C:\WINDOWS\system32;
C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\Program Files\MySQL\MySQL Server 5.1\bin;
C:\Program Files\PostgreSQL\9.1\bin;C:\work\ant\bin;
# then Python path to import our python modules
PYTHONPATH=C:\work\maymyo;
# Let django know where is the settings file name
DJANGO_SETTINGS_MODULE=maymyo.settings
# To find Java
JAVA_HOME=C:\Program Files\Java\jre1.6.0_03;
# Options to pass to Java
JAVA_OPTS=-Xmx256m
# Windows only
SystemDrive=C:
# Where Windows were installed
SystemRoot=C:\Windows

The above shows an example on how we would configure the environment for Windows. We need the database bin directory in the PATH when connecting because we need to load their DLLs when running SQL scripts. Also note that you cannot use DOS variables (eg %PATH%) because they cannot be expanded when used in Windows Services.

Then optionally install the following :-

  • pywin32, if your are on the Windows platform. Use easy_install pywin32
  • skype4py, version 1.0.32 onwards, only when you want to send sms from Maymyo. One of the daemons called messenger.py does this.

On Windows, perform the following:-

  1. Install the Maymyo Daemons as a Windows Service. Open a new Command Prompt:

    > winservice.py install
  2. Then run Services, on Windows XP this would be in Control Panel->Administrative Tools>Services Scroll down to find the “Maymyo Development Daemons...” Double-click this, then goto to the “Log On” tab and change to “Log On as” to your username. This is because the daemons need your environment variables to be started. You should change the “Startup type” too to “Automatic” so that the daemons will start up at boot time.

    Note

    Development above is the Instance name of Maymyo. You may have several instances of Maymyo on the same computer and we use this to tell them apart. Each instance has its own database (or schema). You can change the instance name by using “Maintain Application Registry”. Look for the Registry Key “INSTANCE-NAME”. Do this before you install the Windows Service above.

  3. You may want to tell Windows that the Maymyo Daemons depends on your database service being started first. Run regedit and add a “Multi String Value” entry named “DependOnService” for HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Maymyo_Development_Daemons The value to add is your exact Database Service name, eg “MySQL”.

On Red Hat based Linux, perform the following:-

  1. log in as root
  2. ln -s *maymyo_home*/bin/auto_daemons.sh /etc/init.d/maymyo
  3. make it auto-start by chkconfig --level 345 maymyo on
  4. Maymyo daemons will auto-start on next reboot
  5. You can start or stop manually by service maymyo start or service maymyo stop.

On Debian based Linux :-

  1. log in with your usual administrator user
  2. “sudo su -” to change to root user
  3. ln -s *maymyo_home*/bin/auto_daemons.sh /etc/init.d/maymyo
  4. make it auto-start by update-rc.d maymyo defaults
  5. Maymyo daemons will auto-start on next reboot
  6. You can start or stop manually by sudo service maymyo start or sudo service maymyo stop.

Note

Replace *maymyo_home* with your installation home directory.

For other posix platforms, the steps are similar but the directory and commands may not be exactly the same. At worse, you may run autostart.sh in /etc/rc.local.

There is a config file that controls the daemons. It is in maymyo_home/snippets/daemon.tab. The comments in this file explains what the fields are for. By default we run the daemons from 6am to 1am the next morning. This means that the daemons are sleeping from 1:01am to 5:59am. You should perform warm database backup tasks in this time window. If cold database backups are required, then you should use the Operating System’s scheduler (eg cron) to stop and restart the daemons or incorporate these actions in your backup script.

Deploying Maymyo for Production on Apache+mod_wsgi

You should read Django’s documentation on deployment on Apache plus mod_wsgi in “The Development Process->Deployment->WSGI Servers” section. Consult Django resources on production deployments on other web servers. What will work for Django will work for us. However read below for the extra static files you need to serve.

Note

Skip this step if you are only evaluating or setting up a development environment.

There are extra static files to serve :-

  • collect all the static files needed into the settings.STATIC_ROOT directory. Note that this step has been done during the prepare Application Directories above. You will need to do this again if you have added your own static files or you have changed the static directory STATIC_ROOT location in settings.py, run the following:

    $ django-admin.py collectstatic
  • You will also need to serve our dojo files, which includes a few of our own Javascript files. These are in dojango/dojo-media/release/1.6.1-dojango-optimized-with-dojo. Below is our own changes to the Apache httpd.conf file to serve Maymyo:

    # Django wsgi setup -- start
    # Using / overrides the above doc root but we can't use
    # any prefix as we will then need to change our urls.py
    WSGIScriptAlias / "/home/maymyo/maymyo024/maymyo/wsgi.py"
    WSGIPythonPath "/home/maymyo/maymyo024"
    
    <Directory "/home/maymyo/maymyo024/maymyo">
    <Files wsgi.py>
    Order deny,allow
    Allow from all
    </Files>
    </Directory>
    
    # Django wsgi setup -- end
    
    # Django static files setup -- start
    # You need to run "django-admin collectstatic" to copy all apps' static files
    # to STATIC_ROOT directory.
    # For dojango, we need to allow only the release directories to be accessed.
    # Alias /robots.txt "/home/maymyo/mayrun024/static/robots.txt"
    Alias /favicon.ico "/home/maymyo/mayrun024/static/images/custlogo.png"
    
    Alias /uploads/ "/home/maymyo/mayrun024/uploads/"
    Alias /static/ "/home/maymyo/mayrun024/static/"
    Alias /dojango/dojo-media/release/1.6.1-dojango-optimized-with-dojo/ "/home/maymyo/maymyo024/dojango/dojo-media/release/1.6.1-dojango-optimized-with-dojo/"
    
    <Directory "/home/maymyo/mayrun024/static">
    Order deny,allow
    Allow from all
    </Directory>
    
    <Directory "/home/maymyo/mayrun024/uploads">
    Order deny,allow
    Allow from all
    </Directory>
    
    <Directory "/home/maymyo/maymyo024/dojango/dojo-media/release/1.6.1-dojango-optimized-with-dojo">
    Order deny,allow
    Allow from all
    </Directory>
    
    # Django static files setup -- end
  • the example above assumes that maymyo_home is in “/home/maymyo/maymyo024”.