2.1.1.2. Heroku installation of Makahiki¶
2.1.1.2.1. Install Heroku¶
Sign up for an account and install the Heroku toolbelt following the instructions in the Heroku Cheat Sheet
- This involves:
- Signing up with the Heroku service
- Install the Heroku Toolbelt (provides the “git” and “heroku” commands).
- Logging in to Heroku.
2.1.1.2.2. Add your SSH keys to Heroku¶
You must tell Heroku about your SSH keys. Follow https://devcenter.heroku.com/articles/keys to upload your keys to Heroku.
2.1.1.2.3. Verifying your Heroku account¶
Heroku provides many addons to enhance and manage the apps deployed in Heroku. Makahiki use the free Memcache addon on Heroku for performance enhancement. In order to use any addons, even the free ones, Heroku requires to verify your account by providing your credit card info. The verification process is free and no charge will be made as long as you don’t use the paid addons or exceed your app’s free resource usage allowance. See more about Heroku billing at: https://devcenter.heroku.com/categories/billing
Follow Account Verification page to verify your account.
If you don’t verify your Heroku account, Makahiki will not be able to use Memcache and the “initialize_instance” step later will fail to add the “Memcache” addon to your heroku instance.
2.1.1.2.4. Setup Amazon S3¶
Makahiki on Heroku use Amazon S3 to store static files and support file/image upload due to the limitation of Heroku’s Ephemeral filesystem in hosting static assets. You will need to set up the Amazon S3 for serving the static files in Makahiki heroku instance.
Follow Using AWS S3 to store static assets for details to setup the Amazon S3.
Create a S3 bucket to be used for storing the static files for Makahiki, and record the bucket name you created, the AWW access key id, and the AWS secret access key for use in setting up the environment variables for Heroku.
Note
You will need to sign up for an AWS S3 account with Amazon if you don’t have one. AWS S3 is not a free service and requires a credit card. But if you are a new AWS customer, you can sign up for the AWS Free Usage Tier which will be free for one year. And in general, the charge to S3 after the free period is very inexpensive.
2.1.1.2.5. Setup environment variables¶
To deploy Makahiki on Heroku, you must define several local environment variables that will be used by the initialize_instance script when it configures the Heroku instance.
First, define a local environment variable that specifies the Heroku Makahiki admin account name and password:
% export MAKAHIKI_ADMIN_INFO=admin:Dog4Days56
You will also need to define Amazon S3 information:
% export MAKAHIKI_AWS_ACCESS_KEY_ID=<AWS access key id>
% export MAKAHIKI_AWS_SECRET_ACCESS_KEY=<AWS secret access key>
% export MAKAHIKI_AWS_STORAGE_BUCKET_NAME=<AWS S3 bucket name>
You should have obtained these values in the previous “Setup S3” section.
2.1.1.2.6. Download the Makahiki source¶
To download the Makahiki system, type the following:
% git clone git://github.com/csdl/makahiki.git
This will create a directory called “makahiki” containing the source code for the system.
2.1.1.2.7. Initialize Makahiki¶
Once the above local environment variables are set, you can use the initialize_instance script to create a Heroku application and initialize the application with the default Makahiki data set. All Heroku application names must be unique, so if your organization is “hpu”, then you might call your application “makahiki-hpu”. Use an application name appropriate for your organization.
To initialize your heroku application (for example, “makahiki-hpu”) with the default Makahiki data set, you need to first activate the Makahiki virtual environment and invoke the initialize_instance.py script, similar to the following:
% workon makahiki
% cd makahiki
% scripts/initialize_instance.py --type default --heroku makahiki-hpu
- This command will:
- create the application in Heroku
- install Heroku Memcache addons
- set up the Makahiki environments you defined for the application
- upload the Makahiki source code to Heroku
- install and/or update all Python packages required by Makahiki
- initialize the database contents and perform any needed database migrations.
- initialize the system with data.
- set up static files.
This command will produce lots of output and may take more than 20 minutes to upload Makahiki to Heroku, depending on your network. After uploading Makahiki you will have to answer ‘Y’ to the question “Do you wish to continue (Y/n)?” during the process.
Warning
initialize_instance will delete any Makahiki challenge configuration actions!
The initialize_instance script should be run only a single time in production scenarios, because any subsequent challenge configuration will be lost if initialize_instance is invoked again. Instead, use update_instance (discussed below) after performing configuration in the production environment.
Note
In an development environment, it is ok to run the initialize_instance multiple times provided that you understand the process will delete your pre-existing instance. In the case that you did not verify the Heroku account or did not setup S3 correctly, the script will fail. You could run the “initialize_instance” script again after you verify the account and/or fix the S3 setup.
If you run the script a second time with the same heroku app name, you may see an error message saying that the heroku application had already been created and the Memcache addon already installed. You can ignore this error message.
2.1.1.2.8. Start the server¶
To start up the server on Heroku, invoke:
% heroku ps:restart --app makahiki-hpu
2.1.1.2.9. Verify that Makahiki is running¶
Open a browser and go to http://<heroku-appname>.herokuapp.com/ (where <heroku-appname> is replaced by your app’s name, for example, makahiki-hpu). This should retrieve the landing page, which should look like:
2.1.1.2.10. 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.2.11. 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.
Get the updated source code:
% git pull origin master
Run the update_instance script to update your Heroku configuration (make sure the AWS environment variables are set):
% cd makahiki % scripts/update_instance.py --heroku makahiki-hpu
Finally, restart your server:
% heroku ps:restart --app makahiki-hpu