Welcome to OpenEats2’s documentation!

This document refers to version 2.4.0

Getting Started

Introduction

OpenEats is a recipe management site that allows users to create, share, and store recipes. OpenEats was created using django, a python web framework and several django plugins. Some of the features of OpenEats are;

  • Create, share and edit your own recipes
  • Mark your own recipes as private so only you can see them
  • Follow other chefs on OpenEats and see what they are rating, and adding
  • Create custom grocery list
  • Add recipes to your grocery lists
  • Share grocery list with other people. This is handy for a family to have a list everyone can update
  • Rate recipes
  • Comment on recipes
  • 100% OpenSource and free
  • A complete administration backend to maintain your site
  • Export recipes to PDF or MealMaster format
  • Internationalization Support

Installation

This document assumes you are familiar with Python and Django.

Requirements

Optional

Python Virtual Environment

The easiest way to install OpenEats2, is to create a python virtual environment. This allows for keeping all the packages for OpenEats2 in a separate place. Saving the hassle of dealing with application dependencies.

Installing virtualenv

To install virtualenv from the command line type:

pip install virtualenv

You will also want to install the virtualenvwrapper package to make management of the virtual environment simpler

To install virtualenvwrapper from the command line type:

pip install virtualenvwrapper
Creating the virtualenv

To create the skeleton virtualenv run the following commands:

export WORKON_HOME=~/Envs
mkdir -p $WORKON_HOME
source /usr/local/bin/virtualenvwrapper.sh
mkvirtualenv openeats --no-site-packages
workon openeats

Note

You can set your workon home directory anywhere you want it doesn’t have to be in the Envs directory The virtualenvwrapper.sh may not be located in /usr/local/bin it varies by operating system. For help with virtualenvwrapper vist their site.

Installing

  • Download the latest package from github
  • Unzip the files into a directory that your web server can access
  • Make sure the directory is called openeats or python won’t be able to find it
  • Install the required packages
Installing Requirements packages

To install all the packages that OpenEats2 requires perform the following steps.

  • Activate your virtualenv

  • Change to the directory that you unzipped the OpenEats2 files into

  • Run the following command:

    pip install -r OE2_Requirements.txt
    
Database

OpenEats2 has been tested with MySQL and SQLite and minimal testing has been done with PostgreSQL_ Technically it should be able to work under any django supported database. SQLite is built into python and does not require any additional software.

MySQL

To install the MySQL-Python module perform the following steps

  • Activate your OpenEats2 virtualenv

  • Run the following command:

    pip install mysql-python
    
PostgresSQL

To install the Postgres module perform the following steps

  • Activate your OpenEats2 virtualenv

  • Run the following command:

    pip install psycopg2
    

There is a small issue with PostgresSQL that will cause you an error when loading the data. To get around this issue perform the following steps;

  • Copy the postgres_settings.py to settings.py.
  • Then skip running the migrate command from the Required Data section below.
  • After running the ./manage.py syncdb command from the Required Data section, edit the settings.py file and remove the # from in front of the word south in the file and save it.
  • Then run the command ./manage.py migrate –fake.
  • Continue with the rest of the instructions as normal.
Load Initial Data

OpenEats2 comes with default data that needs to be loaded into the database.

Required Data

Running the following command from the OpenEats2 directory, should load the required data:

./manage.py syncdb --all
./manage.py migrate --fake
./manage.py loaddata fixtures/navbar_about_data.json

Note

Before you run this make sure you have setup your database in the settings.py file. For more information on this see Database

Optional Data

You can pre-load courses and cuisines by running the following commands from the OpenEats2 directory:

./manage.py loaddata recipe_groups/fixtures/course_data.json
./manage.py loaddata recipe_groups/fixtures/cuisine_data.json
Collecting Static Files

To collect the static files from the third party applications run the following command:

./manage.py collectstatic
Running

After the install you can run the following command to start the internal Django webserver. This will allow you to test your site prior to setting up a “real” webserver such as Apache:

./manage.py runserver 8000

This will bind the webserver to port 8000 on 127.0.0.1 otherwise known as localhost. If you are deploying OpenEats2 to a remote server and not your local computer run the following command instead:

./manage.py runserver 0.0.0.0:8000

You should then be able to access your new OpenEats2 site by pointing your browser to your URL with port 8000:

http://yoursite:8000

Note

You should not run OpenEats2 in production with the built in webserver. You will want to setup Apache or Ngnix Check out the Django Apache WSGI document for more info.

Site Name

You will need to set up your site name before you can use certain features. See Change Site Name

Upgrade

Upgrade 2.0 to 2.1

This procedure covers how to upgrade your existing 2.0 OpenEats2 site to version 2.1

Install
  • Download the latest package from github
  • Unzip the file
  • Backup your database
  • Backup your current site files
  • From the unzip file, copy everything other then the settings.py, site-media/upload and site-media/uploads file into your current openeats directory, over writing what is already there
Config File Changes

Some minor changes need to be made to the settings.py file of your current site.

Remove the following from the installed apps section of the settings.py file

  • admin_tools.theming
  • admin_tools.menu
  • admin_tools.menu

Add the following to the installed apps section of the settings.py file on the first line:

'grappelli.dashboard',

Add the following to the installed apps section of the settings.py file:

'django.contrib.staticfiles',

Remove the following from the context processors section of the settings.py file:

"grappelli.context_processors.admin_template_path",

Add the following to the context processors section of the settings.py file:

"openeats.context_processors.oetitle",

Add the following line to the settings.py file:

LOCALE_PATHS = (
   os.path.join(BASE_PATH, 'locale',)
)

Remove the following lines in your settings.py file:

ADMIN_TOOLS_INDEX_DASHBOARD = 'openeats.dashboard.CustomIndexDashboard'
ADMIN_TOOLS_APP_INDEX_DASHBOARD = 'openeats.dashboard.CustomAppIndexDashboard'

Add the following line to your settings.py file:

GRAPPELLI_INDEX_DASHBOARD = 'openeats.dashboard.CustomIndexDashboard'

Add the following lines to your settings.py file:

STATIC_ROOT = os.path.join(BASE_PATH, 'static-files')
STATIC_URL = '/static-files/'

Change the ADMIN_MEDIA_PREFIX setting in the settings.py file to this:

ADMIN_MEDIA_PREFIX = STATIC_URL + "grappelli/"

Add the following line under the OpenEats Settings section of the settings.py file:

OETITLE="OpenEats2"

You can set this to anything you want your site title to be, it doesn’t have to be set to OpenEats2

Remove the following line from urls.py:

url(r'^admin_tools/', include('admin_tools.urls')),
Removing directories

The following directories are no longer needed for version 2.1 and can be removed

  • grappelli
  • site-media/admin
  • site-media/admin_tools
Upgrade third party apps

To upgrade all the packages that OpenEats2 requires perform the following steps.

  • Activate your virtualenv

  • Change to the directory that you unzipped the OpenEats2 files into

  • Run the following command:

    pip install -r OE2_Requirements.txt --upgrade
    
Database changes

Run the following command from the OpenEats2 directory:

./manage.py syncdb
./manage.py migrate djangoratings 0001 --fake
./manage.py migrate djangoratings 0002 --fake
./manage.py migrate djangoratings 0003
./manage.py migrate djangoratings 0004 --fake
./manage.py migrate djangoratings 0005 --fake
./manage.py migrate djangoratings
./manage.py migrate sentry 0001 --fake
./manage.py migrate sentry 0002 --fake
./manage.py migrate sentry 0003 --fake
./manage.py migrate sentry 0004 --fake
./manage.py migrate sentry 0005 --fake
./manage.py migrate sentry 0006 --fake
./manage.py migrate sentry 0007 --fake
./manage.py migrate sentry 0008 --fake
./manage.py migrate sentry 0009 --fake
./manage.py migrate sentry
./manage.py migrate
Third Party static files

Django 1.3 offers a new feature that pulls in all the css and image files from third party apps into one folder. This does away with having to setup symlinks to them yourself. The files are stored in the static-files directory. To get the initial files set run the following command:

./manage.py collectstatic
Rebuild Search Index

The search engine was updated as part of this release so it is a good idea to run the following command to rebuild it:

./manage.py rebuild_index
Running

After the upgrade you can run the following command to start the internal Django webserver. This will allow you to test your site:

./manage.py runserver 8000

Upgrade 2.1 to 2.2

This procedure covers how to upgrade your existing 2.1 OpenEats2 site to version 2.2. If you are upgrading from 2.0 to 2.2 you will need to follow the steps from Config File Changes down in the Upgrading from 2.0 to 2.1 section.

Install
  • Download the latest package from github
  • Unzip the file
  • Backup your database
  • Backup your current site files
  • From the unzip file, copy everything other then the settings.py, site-media/upload and site-media/uploads file into your current openeats directory, over writing what is already there
Database changes

Run the following command from the OpenEats2 directory:

./manage.py migrate list
Running

After the upgrade you can run the following command to start the internal Django webserver. This will allow you to test your site:

./manage.py runserver 8000

Upgrade 2.2 to 2.3

This procedure covers how to upgrade your existing 2.2 OpenEats2 site to version 2.3. If you are upgrading from 2.0 to 2.3 you will need to follow the steps from Config File Changes down in the Upgrading from 2.0 to 2.1 section.

Install
  • Download the latest package from github
  • Unzip the file
  • Backup your database
  • Backup your current site files
  • From the unzip file, copy everything other then the settings.py, site-media/upload and site-media/uploads file into your current openeats directory, over writing what is already there
Settings Changes

Add the following to your settings.py file under the TEMPLATE_CONTEXT_PROCESSORS area:

'django.core.context_processors.static',

Remove the following from the installed_apps section of the settings.py file:

'reversion',
Upgrade third party apps

To upgrade all the packages that OpenEats2 requires perform the following steps.

  • Activate your virtualenv

  • Change to the directory that you unzipped the OpenEats2 files into

  • Run the following command:

    pip install -r OE2_Requirements.txt --upgrade
    
Database changes

Run the following command from the OpenEats2 directory:

./manage.py migrate
Update Static Files

To update the static files from the third party applications run the following command:

./manage.py collectstatic
Running

After the upgrade you can run the following command to start the internal Django webserver. This will allow you to test your site:

./manage.py runserver 8000

Upgrade 2.3 to 2.4

This procedure covers how to upgrade your existing 2.3 OpenEats2 site to version 2.4. If you are upgrading from 2.0 to 2.4 you will need to follow the steps from Config File Changes down in the Upgrading from 2.0 to 2.1 section.

Install
  • Download the latest package from github
  • Unzip the file
  • Backup your database
  • Backup your current site files
  • From the unzip file, copy everything other then the settings.py, site-media/upload and site-media/uploads file into your current openeats directory, over writing what is already there
Settings Changes

Remove the following from the installed_apps section of the settings.py file:

'django_generic_flatblocks',
Upgrade third party apps

To upgrade all the packages that OpenEats2 requires perform the following steps.

  • Activate your virtualenv

  • Change to the directory that you unzipped the OpenEats2 files into

  • Run the following command:

    pip install -r OE2_Requirements.txt --upgrade
    
Database changes

Run the following command from the OpenEats2 directory:

./manage.py migrate
Update Static Files

To update the static files from the third party applications run the following command:

./manage.py collectstatic
Update Recipe Picture cache

The size of the recipe pictures has changed to re-create the current pictures to the new size run:

./manage.py ikflush recipe
Running

After the upgrade you can run the following command to start the internal Django webserver. This will allow you to test your site:

./manage.py runserver 8000

Configuration

This document covers the configuration settings for OpenEats2

Database

To setup Django for your database refer to the Django Database document

Email

To setup your email server open up the settings.py file located in the OpenEats2 directory and fill in the following settings with your own email server settings:

#Email Server Settings
DEFAULT_FROM_EMAIL = ''
EMAIL_HOST = ''
EMAIL_HOST_USER = ''
EMAIL_HOST_PASSWORD = ''
EMAIL_PORT =
#EMAIL_USE_TLS = True

Note

If you do not have your own email server you can use Gmail if you have a gmail account. Follow this gmail guide to learn how.

Site Title

If you want to set your own site title, different from the default OpenEats2. You can modify the OETITLE setting in the setting.py file:

OETITLE = 'OpenEats2'

Change the word between the quotes to what ever you want your site title to be

Debug

By default OpenEats2 is in debug mode to allow users to find issues with their site during initial setup. Once conferable with your site you should turn debug mode off by changing the following line in your settings.py file and restarting your webserver:

DEBUG = True

change to

DEBUG = False

Comments

OpenEats2 uses Disqus for its comment system. In order to use Disqus on your OpenEats2 site you will need to apply for an API key and register your site.

Disqus API Key

To get your own Disqus API key visit the Disqus register site and sign up. Make sure you enter the fully qualified domain name of where you are hosting OpenEats2.

Disqus Configuration

Once you have register your site with Disqus you will need to add the following to your settings.py file:

#Disqus settings
DISQUS_API_KEY = "your API key"
DISQUS_WEBSITE_SHORTNAME = "the shortname you entered when you registered"

Admin Page

OpenEats2 has an Admin backend to allow the administrator of the site manager their OpenEats2 site.

Access Admin Site

To access the Admin site point your browser to the following URL:

http://yourdomain/admin

You will be prompted to login with a userid and password the defaults are:

user: admin
password: password

You will want to change this as soon as you login by click on the users link inside the admin page

Change Site Name

You will want to change the site name on the Admin page to match your domain name. To do so click on the sites link on the Admin Page then click on the current entry for site name which should be example then change that to match your domain name, with out the http or www part

Note

Do not just delete the name that is currently there. Django expects your site name to start with the primary key of 1 in the database. If you delete the site name and add a new one it will have the id of 2. So edit the site name that is already there.

Testing

OpenEats2 comes with several built in test to make sure the code is working as designed. To run the test make sure you have installed the following packages in your virtuenv

Running Test

To run the test run the following command once you are in your virtuenv:

./manage.py test recipe

recipe can be replaced with which ever app you want to test. Currently the following apps have tests

  • recipe
  • accounts
  • list

Exporting Recipes

You can export individual recipes or every recipe you have on your site into the common MealMaster format.

Exporting Individual Recipes

To export individual recipes login to the Admin part of the site Admin Page. Click on the Recipes link. Then place a check mark in the box next to each recipe you want to export. At the bottom of the page there is a dropdown from the dropdown select Export MealMaster A file will be downloaded to your computer with the exported recipes.

Export all Recipes

To export all the recipes on your site to the MealMaster format, you will need to run a command from the directory you installed OpenEats2. Activate your virtualenv, see Creating the virtualenv then run the following command from the OpenEats2 directory:

./manage.py export_recipes > recipe.txt

This will create a file called recipe.txt which will contain all the recipes on your site in the MealMaster format

Search Index

The search feature on OpenEats2 is handled by two different applications; django-haystack and whoosh

Updating the Index

You have two options when updating the search index;

  • Real time, as a recipe is added or deleted the index is updated, this is the default method.
  • Scheduled, you can run a script every x minutes to update the index
Real time Updates

By default OpenEats2 ships with real time update dates out of the box; meaning if a recipe is added the search index is updated. There are some downsides to this. If you have a real active site, updating the index in real time could cause a huge slow down. The handoff between the database save and the search index update could cause some weird issues in your database such as items only being half saved, this would happen during a heavy load on the system.

Note

If you are going to run OpenEats2 on Apache with mod_wsgi, you will need to enable mod_wsgi to run in daemon mode for real time updates. Otherwise everyone once in a while you will get an error that the index can’t be updated because of garbage collection on Apache.

Schedule Updates

If you do not wish to run real time updates you can set the index to be update via a script that you run on a schedule. To do this you will want to edit the recipe/search_indexes.py file:

Change line

class RecipeIndex(RealTimeSearchIndex):

to

class RecipeIndex(SearchIndex):

After the change you will need to restart your web server. An example of a script that will update the index can be found in the contrib folder of your OpenEats2 project. With out the script you can run the following commands from your virtenv:

./manage.py rebuild_index  *this command creates the index
./manage.py update_index   *this updates an existing index

Changelog

Version 2.1

  • Upgraded Django to 1.3
  • Added CSRF protection for AJAX calls
  • Upgraded to django-grappelli 2.3.3
  • Removed grappelli from the root dir of OpenEats, it now installs like all the ohter thrid party apps
  • Removed admin_tools third party app
  • Setup grappelli dashboard to replace the admin_tools dashboard
  • Setup static files a new feature in Django 1.3. This pulls in all the third party apps images, css files. replaces the need to do symnlinks to them
  • Upgraded django-imagekit to 0.3.6
  • Upgraded django-debug-toolbar to 0.8.5
  • Upgraded south to 0.7.3
  • Upgraded django-haystack to 1.2.4
  • Upgraded Whoosh to 1.8.4
  • Upgraded django-rosetta to 0.6.2
  • Upgraded django-sentry to 1.8.6.2
  • Upgraded django-webtest to 1.4.1
  • Upgraded django-relationships to 0.3.0
  • Upgraded django-ratings to 0.3.6
  • Added the ability for users to change the tile of the site via settings.py
  • Added the ability to change and clear a picture on a recipe when edited

Version 2.2

  • Added meta keywords and description to the main page
  • Added meta keywords using recipe titles and tages to the recipe detail page
  • Fixed bug of ratings not showing up on a recipe till a user voted on them even if another user had rated the recipe
  • Added a top recipe view that shows the top 20 recipes
  • Added a most recent recipes view that shows the 20 most recent recipes
  • Added recent recipe rss feed
  • Added user created aisles for grocery lists
  • Added recipes displayed on grocery list when they are added to a list
  • Added django-tastypie package for API
  • Fixed urls.py by removing a url to a package that is not not used anymore

Version 2.3

  • Added instructions and a special settings file to support PostgreSQL
  • Moved the api module to the contrib folder
  • Sorted grocery list and shared grocery list by created date
  • Changed the submit button text on all forms to make more sense
  • Changed the design of the title bar that is found above all the category list of recipes
  • Removed the “follow me” link from a users profile if they are viewing their own profile.
  • Branched the django ratings application and updated it to work with django 1.3
  • Lots of CSS tweaks
  • Upgraded to Django 1.3.1
  • Moved all the CSS, images, and JS to a new folder called static to be more in-line with the Django 1.3 way of doing things
  • Upgraded Grapelli to version 2.3.4
  • Upgraded django-generic-flatblocks to 0.9.1
  • Removed the plugin django-reversion
  • Upgraded django-imagekit to 0.4.0
  • Changed the site Logo

Version 2.4

  • Added a new news section now you can have more then one news story and decide which one appears on the front page
  • Added the ability to email recipes to friends
  • Added grocery list API
  • Upgraded django-tastypie
  • Complete UI over haul using Twitter Bootstrap
  • Changed image size for recipe pictures
  • Upgraded Grapelli to version 2.3.7
  • Removed un-needed java script libraries
  • Code clean up
  • several small bug fixes

Indices and tables