2.1.1.1.2. Local installation on Unix¶
These instructions also assume that you are using a Bourne-type shell (such as bash), which is the default on Mac OS X and Linux. Using a C-shell variant (like tcsh), is possible but not recommended.
2.1.1.1.2.1. Hardware requirements¶
- Our estimated hardware requirements for production use are:
- CPU: modern dual or quad core
- RAM: 8 GB
- Disk space: 10 GB
For development only, a modern dual core CPU with 4 GB should be ok, although the more the better.
2.1.1.1.2.2. Install Python¶
Install Python 2.7.3 or higher (but not Python 3).
To check that python is installed and has the correct version:
% python --version
Python 2.7.3
2.1.1.1.2.2.1. Red Hat Enterprise Linux: Compile and Install Python 2.7.3¶
As of Red Hat Enterprise Linux (RHEL 6) and CentOS 6, Python 2.6.6 is the default. For Makahiki, Python 2.7.3 will be installed by compiling Python from scratch and performing an altinstall.
Install wget:
% sudo yum install wget
Next, install the packages needed to build and compile C:
% sudo yum groupinstall -y "Development tools"
% sudo yum install -y zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel
This will take a while.
Next, download and extract the Python 2.7.3 source code:
% wget http://python.org/ftp/python/2.7.3/Python-2.7.3.tar.bz2
% tar xf Python-2.7.3.tar.bz2
Have the current user take ownership of the extracted directory (replace <username> with your username):
% chown -R <username> Python-2.7.3
Change into the extracted directory:
% cd Python-2.7.3
Configure the path to the altinstall:
% ./configure --prefix=/usr/local
This sets the location of the altinstall to “/usr/local/bin/python2.7.”
To finish the installation, make and install Python to the directory that you configured in the previous step:
% make
% sudo make altinstall
To run Python scripts using the Python 2.7.3 altinstall, you will need to use “python2.7” instead of “python.” Check the Python version:
% python2.7 --version
Python 2.7.3
Next, check that you can use the Python 2.7.3 shell, then exit:
% python2.7
Python 2.7.3 (default, Feb 26 2014, 11:02:10)
[GCC 4.4.7 20120313 (Red Hat 4.4.7-4)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()
You have now verified that the altinstall is working.
2.1.1.1.2.3. Install C Compiler¶
If you are using Mac OS X, install Apple Developer Tools (i.e. Xcode 4). This is required in order to build certain libraries (PIL, etc.) that require GCC (which is bundled with Xcode). Xcode can either be found in your OS X installation DVD, or in the Mac App Store.
If on Linux, in most cases, you will find the C/C++ compiler is already installed in your environment.
To check that C compiler is installed:
% gcc --version
To install gcc on Ubuntu:
% sudo apt-get install gcc
To install gcc on RHEL and CentOS:
% sudo yum install gcc
2.1.1.1.2.4. Install Git¶
Find a package for your operating system at the GitHub install wiki. We recommend following the GitHub setup instructions at https://help.github.com/articles/set-up-git.
To check that Git is installed:
% git --version
2.1.1.1.2.5. Install Pip¶
The process to install pip is different for each operating system.
2.1.1.1.2.5.1. Ubuntu¶
If you do not have easy_install, download and install it from the setuptools website using sudo apt-get install python-setuptools:
% sudo apt-get install python-setuptools
If easy_install is installed on your system, install pip by typing:
% easy_install pip==1.4.1
Depending on your system configuration, you may have to type sudo easy_install pip==1.4.1.
Check that pip 1.4.1 is installed:
% pip --version
2.1.1.1.2.5.2. Red Hat Enterprise Linux (RHEL) and CentOS¶
Install setuptools and pip for the original Python 2.6.6 installation:
% sudo yum install python-setuptools
% sudo easy_install pip==1.4.1
For Python 2.7.3, download and extract setuptools-0.8:
% wget https://pypi.python.org/packages/source/s/setuptools/setuptools-0.8.tar.gz --no-check-certificate
% tar xf setuptools-0.8.tar.gz
Change ownership of the extracted directory by replacing <username> with your username:
% chown -R <username> setuptools-0.8
Change your working directory to the extracted directory and install:
% cd setuptools-0.8
% sudo /usr/local/bin/python2.7 setup.py install
Check that the installation was successful:
% /usr/local/bin/easy_install-2.7 --version
setuptools 0.8
You will install pip into the virtual environment later.
2.1.1.1.2.6. Install Virtual Environment Wrapper¶
Virtualenvwrapper allows you to install libraries separately from your global Python path.
2.1.1.1.2.6.1. Ubuntu¶
Follow the virtualenvwrapper installation instructions through the Quick Start section to install virtualenv and virtualenvwrapper. Once they are installed, create a virtual environment for makahiki as follows:
% mkvirtualenv makahiki
To check that virtual environment wrapper is installed:
% workon makahiki
2.1.1.1.2.6.2. RHEL and CentOS¶
Install virtualenvwrapper for Python 2.6.6:
% sudo /usr/bin/pip install virtualenvwrapper
Add these lines to the end of the ~/.bashrc file:
# Virtualenvwrapper settings for makahiki
export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/makahiki
export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
export VIRTUALENVWRAPPER_VIRTUALENV=/usr/bin/virtualenv
export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
source /usr/bin/virtualenvwrapper.sh
Then source this file to apply changes:
% source ~/.bashrc
Create a virtual environment that uses Python 2.7.3:
% mkvirtualenv makahiki -p /usr/local/bin/python2.7
Creating a virtual environment should switch you to the virtual environment. The terminal prompt will be preceded by the name of the virtual environment. On RHEL, this looks like:
(makahiki)[robot@computer makahiki]$
If creating the virtual environment did not switch you to the virtual environment, use “workon makahiki” to switch to it:
% workon makahiki
Check your Python version in the virtualenv:
% python --version
Python 2.7.3
Note
Any commands run with root privileges (sudo python) will use the default Python 2.6.6, not Python 2.7.3.
Next, uninstall the pip version in the virtual environment, and install pip==1.4.1 instead:
% pip uninstall pip
% easy_install pip==1.4.1
2.1.1.1.2.7. Install Python Imaging Library¶
Makahiki requires the Python Imaging Library (PIL).
2.1.1.1.2.7.1. Mac OS X¶
We have found Homebrew to be the most reliable way to install PIL. Once Homebrew is installed, install PIL by typing:
% brew install pil
2.1.1.1.2.7.2. Ubuntu¶
In Ubuntu, install PIL by typing:
% sudo apt-get install -y python-imaging python-dev libjpeg-dev
Make sure you have both libjpeg (for JPEG) and zlib (for PNG) in the /usr/lib directory. If not, you can make the symbolic link there.
To make the symbolic links in a 32-bit Ubuntu OS:
% sudo ln -s /usr/lib/i386-linux-gnu/libjpeg.so /usr/lib/libjpeg.so
% sudo ln -s /usr/lib/i386-linux-gnu/libz.so /usr/lib/libz.so
To make the symbolic links in a 64-bit Ubuntu OS:
% sudo ln -s /usr/lib/x86_64-linux-gnu/libjpeg.so /usr/lib/libjpeg.so
% sudo ln -s /usr/lib/x86_64-linux-gnu/libz.so /usr/lib/libz.so
2.1.1.1.2.7.3. RHEL and CentOS¶
In RHEL and CentOS, install PIL by typing:
% sudo yum install -y python-imaging python-devel libjpeg-devel zlib-devel
Make sure you have both libjpeg (for JPEG) and zlib (for PNG) in the /usr/lib directory. If not, you can make the symbolic link there.
A 32-bit RHEL or CentOS OS should have symbolic links for libz.so and libjpeg.so in /usr/lib created during installation.
If you have a 64-bit RHEL or CentOS OS, you will need to create the symbolic links manually:
% sudo ln -s /usr/lib64/libjpeg.so /usr/lib/libjpeg.so
% sudo ln -s /usr/lib64/libz.so /usr/lib/libz.so
2.1.1.1.2.8. Install PostgreSQL¶
Makahiki uses PostgreSQL as its standard backend database. We recommend version 9.1.3.
2.1.1.1.2.8.1. Mac OS X¶
Note that on Mac OS X, the installer will need to make changes in the sysctl settings and a reboot before installation can proceed.
2.1.1.1.2.8.2. Ubuntu¶
On Ubuntu, install the latest version of PostgreSQL 9.1, and install libpq-dev:
% sudo apt-get install -y postgresql-9.1 libpq-dev
2.1.1.1.2.8.3. RHEL and CentOS¶
On RHEL and CentOS, install the pgdg91 repository, then install the latest version of Postgresql 9.1 and related packages.
Note
Ignore the following warning when running sudo rpm -i:
warning: /var/tmp/rpm-tmp.Mgcm3P: Header V4 DSA/SHA1 Signature, key ID 442df0f8:NOKEY
On i386 (32-bit) systems:
% sudo rpm -i http://yum.postgresql.org/9.1/redhat/rhel-6-i386/pgdg-redhat91-9.1-5.noarch.rpm
% sudo yum install -y postgresql91-server postgresql91-contrib postgresql91-devel
On x86_64 (64-bit) systems:
% sudo rpm -i http://yum.postgresql.org/9.1/redhat/rhel-6-x86_64/pgdg-redhat91-9.1-5.noarch.rpm
% sudo yum install -y postgresql91-server postgresql91-contrib postgresql91-devel
Next, whether you are on an i386 or x86_64 system, initialize the database and start the server:
% sudo service postgresql-9.1 initdb
% sudo chkconfig postgresql-9.1 on
2.1.1.1.2.8.4. After Installation¶
Once installed, use “which” to check that your PostgreSQL installation’s bin/ directory is on $PATH so that pg_config and psql are defined:
% which pg_config
% which psql
RHEL and CentOS users will see errors here. If you are a RHEL or CentOS user, you will add the bin/ directory to the PATH in a later step.
Next, you will need to configure authentication for the “postgres” database user.
During development, a simple way to configure authentication is to make the postgres user “trusted” locally. This means that local processes such as Makahiki can connect to the database server as the user postgres without authentication. To configure this way, edit the pg_hba.conf file and change:
local all postgres ident
to:
local all postgres trust
The first line might be: “local all postgres peer”. Change it to “local all postgres trust”.
If you update the pg_hba.conf file you will have to restart the postgres server.
2.1.1.1.2.8.5. Ubuntu¶
The pg_hba.conf file is located in /etc/postgresql/9.1/main/pg_hba.conf and must be opened with sudo. Edit it to match the examples below:
# Database administrative login by Unix domain socket
local all postgres trust
# TYPE DATABASE USER ADDRESS METHOD
# "local" is for Unix domain socket connections only
local all all trust
# IPv4 local connections:
host all all 127.0.0.1/32 md5
# IPv6 local connections:
host all all ::1/128 md5
Restart the server after updating pg_hba.conf:
% /etc/init.d/postgresql restart
or:
% sudo /etc/init.d/postgresql restart
2.1.1.1.2.8.6. RHEL and CentOS¶
The pg_hba.conf file is located in /var/lib/pgsql/9.1/data/pg_hba.conf and must be opened with sudo. Edit it to match the examples below:
# TYPE DATABASE USER ADDRESS METHOD
# "local" is for Unix domain socket connections only
local all all trust
# IPv4 local connections:
host all all 127.0.0.1/32 md5
# IPv6 local connections:
host all all ::1/128 md5
Restart the server after updating pg_hba.conf:
% sudo service postgresql-9.1 restart
2.1.1.1.2.8.7. All Platforms¶
Alternatively, you can create a .pgpass file containing the credentials for the user postgres. See the PostgreSQL documentation for more information on the .pgpass file.
To check that PostgresSQL is installed and configured with “trusted” locally:
% psql -U postgres
It should not prompt you for a password.
This will open the postgres command prompt. Use the command \q to exit.
2.1.1.1.2.9. Install Memcache¶
Makahiki can optionally use Memcache to improve performance, especially in the production environment. To avoid the need for alternative configuration files, we require local installations to install Memcache and an associated library even if developers aren’t intending to use it.
2.1.1.1.2.9.1. Mac OS X¶
On Mac OS X, if you have installed Homebrew, you can install these by typing:
% brew install memcached
% brew install libmemcached
2.1.1.1.2.9.2. Linux¶
Linux users will need to download and build libmemcached from source. Start by installing memcached.
Ubuntu users:
% sudo apt-get install -y memcached
RHEL and CentOS users:
% sudo yum install -y memcached
Next, install packages needed to build libmemcached-0.53 from source.
Ubuntu users:
% sudo apt-get install -y build-essential g++ libcloog-ppl-dev libcloog-ppl0
RHEL and CentOS users: If you have been following this guide, you should already have performed a groupinstall of all packages in “Development tools.”
If you did not, use the below command to do it now:
% sudo yum groupinstall -y "Development tools"
Next, for Ubuntu, RHEL, and CentOS, download the source code and extract the archive:
% wget http://launchpad.net/libmemcached/1.0/0.53/+download/libmemcached-0.53.tar.gz
% tar xzvf libmemcached-0.53.tar.gz
Warning
Do not download and extract the source code in a directory that is synchronized with a Windows file system. This will cause the libmemcached-0.53 installation process to fail to create hard links and symbolic links during installation.
Switch into the extracted directory, then configure, make, and make install:
% cd libmemcached-0.53
% ./configure
% make
% sudo make install
Finally, check the location of the libmemcached.so library:
% stat /usr/local/lib/libmemcached.so
If libmemcached.so is found successfully, then the installation is complete.
2.1.1.1.2.10. Download the Makahiki source¶
You can download the source by cloning or forking the Makahiki Git repository:
% git clone git://github.com/csdl/makahiki.git
This will create the new folder and download the code from the repository.
2.1.1.1.2.11. Workon makahiki¶
The remaining steps require you to be in the makahiki/ directory and to have activated that virtual environment:
% cd makahiki/
% workon makahiki
If you start a new shell in the midst of this process, you must be sure to invoke workon makahiki and of course cd to the appropriate directory before continuing.
2.1.1.1.2.12. Install required packages¶
2.1.1.1.2.12.1. RHEL and CentOS¶
RHEL and CentOS users will need to add the PostgreSQL libraries to the PATH before installing packages with “pip”:
% export PATH=/usr/pgsql-9.1/bin:$PATH
% which pg_config
/usr/pgsql-9.1/bin/pg_config
% which psql
/usr/pgsql-9.1/bin/psql
Continue to “All Platforms.”
2.1.1.1.2.12.2. All Platforms¶
You can install the required Python package for Makahiki by:
% pip install -r requirements.txt
Don’t worry that this command generates lots and lots of output.
2.1.1.1.2.13. Setup environment variables¶
At a minimum, Makahiki requires two environment variables: MAKAHIKI_DATABASE_URL and MAKAHIKI_ADMIN_INFO.
The following lines show example settings for these two environment variables, preceded by a comment line describing their syntax:
# Syntax: postgres://<db_user>:<db_password>@<db_host>:<db_port>/<db_name>
export MAKAHIKI_DATABASE_URL=postgres://makahiki:makahiki@localhost:5432/makahiki
# Syntax: <admin_name>:<admin_password>
export MAKAHIKI_ADMIN_INFO=admin:admin
You will want to either add these variables to a login script so they are always available, or you can edit the postactivate file (in Unix, found in $WORKON_HOME/makahiki/bin) so that they are defined whenever you workon makahiki.
After you edit and save postactivate, you will need to workon makahiki for your changes to take effect.
Note that you will want to provide a stronger password for the makahiki admin account if this server is publicly accessible.
Makahiki also utilizes a variety of other environment variables. For complete documentation, see Environment Variables.
2.1.1.1.2.14. Initialize Makahiki¶
Next, invoke the initialize_instance script, passing it an argument to specify what kind of initial data to load. You need to be in the makahiki/makahiki directory. In most cases, you will want to load the default dataset, as shown next:
% cd makahiki
% ./scripts/initialize_instance.py --type default
- This command will:
- Install and/or update all Python packages required by Makahiki;
- Reinitialize the database contents and perform any needed database migrations.
- Initialize the system with data.
- Set up static files.
Warning
initialize_instance will wipe out all challenge configuration modifications!
The initialize_instance script should be run only a single time in production scenarios, because any subsequent configuration modifications will be lost if initialize_instance is invoked again. Use update_instance (discussed below) to update source code without losing subsequent configuration actions.
You will have to answer ‘Y’ to the question “Do you wish to continue (Y/n)?”
2.1.1.1.2.15. Start the server¶
Finally, you can start the Makahiki server using either:
% ./manage.py run_gunicorn
or:
% ./manage.py runserver
The first alternative (run_gunicorn) runs a more efficient web server, while the second (runserver) invokes a server that is better for development (for example, Theme Development).
2.1.1.1.2.16. Verify that Makahiki is running¶
Open a browser and go to http://localhost:8000 to see the landing page, which should look something like this:
2.1.1.1.2.17. Configure your Makahiki instance¶
Now that you have a running Makahiki instance, it is time to configure it for your challenge, as documented in Site Configuration.
2.1.1.1.2.18. Updating your Makahiki instance¶
Makahiki is designed to support post-installation updating of your configured system when bug fixes or system enhancements become available. Updating an installed Makahiki instance is quite simple, and consists of the following steps.
Bring down the running server in the shell process running Makahiki:
% (type control-c in the shell running the makahiki server process)
In that shell or a new shell, go to your Makahiki installation directory, and ensure the Makahiki virtual environment is set up:
% cd makahiki % workon makahiki
Download the updated source code into your Makahiki installation:
% git pull origin master
Run the update_instance script to update your local configuration:
% ./scripts/update_instance.py
Finally, restart your server, using either:
% ./manage.py run_gunicorn
or:
% ./manage.py runserver