.. _install: ===================== How to install Maymyo ===================== If you are installing Maymyo to evaluate, then you need to :- * :ref:`Install software packages required to run Maymyo ` * :ref:`Download and Install Maymyo ` * :ref:`Configure your database and environment ` * :ref:`Create and Load Maymyo Database objects ` * :ref:`Run Maymyo ` If you want to run our bundled JasperReport reports, then continue with :- * :ref:`Download and Install Java Runtime Environment ` * :ref:`Download and Install jaspercommand ` If you want to develop your own JasperReport reports, then :- * :ref:`Download and Install iReport plus Apache Ant ` If you are setting up Maymyo for production, these are the additional actions :- * :ref:`Configure and auto-start Maymyo Daemons ` * :ref:`Configure Maymyo for Apache mod_wsgi ` .. _prereq: 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. .. _inst_maymyo: 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``. .. _config_maymyo: 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). .. _env_vars: Then edit your environment variables. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: _static/install/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. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. 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': '', } } #. Note that NAME above refers to the database name you have created. #. 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. #. Set PASSWORD to whatever you used when preparing your database. #. Leave HOST and PORT blank if you are using *localhost* and the database's default port respectively. #. 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. .. _db_maymyo: Create and Load Maymyo Database objects --------------------------------------- #. 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*. #. Create the database objects for Django and Maymyo:: > django-admin.py syncdb #. 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. #. 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. #. If you want to load our test data. Skip this if you are setting up for production.:: > load_fixtures.py testdata .. _run_maymyo: Run Maymyo ---------- #. 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 #. You are now ready to run Maymyo and add your own application:: > django-admin.py runserver #. 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. .. image:: _static/install/dashboard.png Your Dashboard on FireFox. #. Change the :index:`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 :ref:`environment variables `. #. 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 #. To stop the daemons.py:: > stop_all_daemons.py #. You can skip the above if you want to start and stop the daemons automatically with the Operating System. This is discussed next. #. You can stop here if you want to evaluate Maymyo only, enjoy! .. _inst_java: Installing Java Runtime Environment ----------------------------------- If you want to run JasperReport reports, then you will need the Java Runtime and :ref:`jaspercommand `. * `Download and install Java Runtime Environment `_, version 1.5 onwards, for running JasperReport reports. * On Ubuntu, you can use its *Ubuntu Software Center*, search for *java* and install the OpenJDK Java 7 Runtime. .. _inst_jasper: 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). .. image:: _static/install/javalib_dir.png jaspercommand's *javalib* destination .. _inst_ireport: 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. .. _maymyo_daemons: 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:- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Install the Maymyo Daemons as a Windows Service. Open a new Command Prompt:: > winservice.py install #. 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. #. 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:- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. log in as root #. ``ln -s *maymyo_home*/bin/auto_daemons.sh /etc/init.d/maymyo`` #. make it auto-start by ``chkconfig --level 345 maymyo on`` #. Maymyo daemons will auto-start on next reboot #. You can start or stop manually by ``service maymyo start`` or ``service maymyo stop``. On Debian based Linux :- ^^^^^^^^^^^^^^^^^^^^^^^^ #. log in with your usual administrator user #. "sudo su -" to change to root user #. ``ln -s *maymyo_home*/bin/auto_daemons.sh /etc/init.d/maymyo`` #. make it auto-start by ``update-rc.d maymyo defaults`` #. Maymyo daemons will auto-start on next reboot #. 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. .. _deploy_prod: 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" Order deny,allow Allow from all # 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/" Order deny,allow Allow from all Order deny,allow Allow from all Order deny,allow Allow from all # Django static files setup -- end * the example above assumes that *maymyo_home* is in "/home/maymyo/maymyo024".