Skip to content

GettingStarted

Jump to bottom
Hiroshi Ichikawa edited this page Jul 9, 2018 · 31 revisions
« back to DeveloperGuide

You can develop on Linux, or Mac OS, or Windows-with-Cygwin.


Step 1. Get tools

You will probably be happiest if you do these steps in order.

Python 2.7.x (you may already have this; try running "python" or "python2.7" to check)

  • All platforms: Download here and install
  • Mac OS X: the pre-installed Python binaries are at /System/Library/Frameworks/Python.framework/Versions/2.x/bin/python2.x and are symlinked from /usr/bin/python2.x. If you downloaded and installed a new version, it will be in /Library/Frameworks rather than /System/Library/Frameworks, and you'll need to ln -s /Library/Frameworks/Python.framework/Versions/2.7/bin/python /usr/bin/python2.7

Setuptools 0.6c11 and EasyInstall (you may already have this; try running "easy_install" or "easy_install-2.7" to check)

  • All platforms: Download, then tar xvfz and sudo python2.7 setup.py install inside the extracted directory.
  • Ubuntu: sudo apt-get install python-setuptools

Git — for revision control (you may already have this; try running "git" to check)

PIL 1.1.7 — optional, only needed if you want to test photo uploading locally

  • All platforms: Download then tar xvfz and sudo python2.7 setup.py install inside the extracted directory.

Latest App Engine SDK for Python

  • All platforms: Follow "Download and install the original App Engine SDK for Python" section in the [download page](https://cloud.google.com/appengine/docs/standard/python/download). So far Person Finder doesn't support `gcloud` command.

py.test — for running unit tests

  • All platforms: sudo easy_install-2.7 pytest

Gettext — for internationalization

  • Linux: sudo apt-get install gettext
  • Mac OS 10.7: Download, double-click, and install.
  • Mac OS 10.8: Download, double-click, and install.

lxml 3.5.0 or later - for running server tests

  • sudo pip install lxml
  • Before 3.5.0 doesn't work.

oauth2client - To run some admin tools

  • oauth2client

Step 2. Get the code

  • Make a local clone of the code repository with this command. (This assumes you want to put the code in a directory called pf:
    git clone https://github.com/google/personfinder.git pf

Step 3. Run the app locally

All the following commands should be done from the application directory (the pf directory we created in the previous step).

cd pf

In one terminal, start a local server with this command:

tools/gae run app --port=8000 # Brings up a local dev_appserver on port 8000

Now you should be able to use the app by going to http://localhost:8000/ in a browser.

If this is the first time to run Person Finder on your machine, the page should show [Setup datastore] button at the top. Click it to initialize the database. It also creates a few example repositories such as "haiti" and "japan", which will appear in the list on the left of the homepage. See the next section to know what is "repository".

To make UI localization work, you need to run:

$ tools/update_messages

Step 4. Run tests

To run both the unit and server tests, shut down Person Finder app you ran in Step 3 (by pressing Ctrl+C) and run:

tools/all_tests

It's expected that PhotoTests fails if you skipped installation of PIL above.

See HowToTest for more advanced way to run tests (e.g., run unit and server tests separately, run only a specific test).

Step 5. (optional) Set up additional repositories

Person Finder usually has one repository per crisis incident. Each repository can be customized with a title, set of languages, announcements, and other settings.

To create a new repository, go to the administration page at http://localhost:8000/haiti/admin and next to "Select a repository" choose "Create new...", then fill in the box with a new repository identifier and click Create. You can then edit the settings page for your newly created repository and click "Save these settings" to save your edits.

If you would like to be able to read and write data in your new repository through the Person Finder API, you will need to create an API key, which you can do at http://localhost:8000/repo/admin/api_keys (replace repo with your repository identifier).

Step 6. (optional) Run the app on AppEngine

To publish your Person Finder so that it's accessible by others, follow steps below to run it on Google App Engine.

  1. Create a new GCP project and AppEngine application using the GCP Console.

    Note that the project ID (not the project name) of your GCP project is used as the domain name of your Person Finder (e.g., https://my-project-id.appspot.com). Make sure to specify whatever you want. You can also use a domain name you own (document).

  2. Enable billing for your GCP project. If you are running a production service, this is required since even a Person Finder with minimal usage doesn't fit in AppEngine's free quota. If you are running Person Finder for development or demo purpose, you can run it in the free quota by temporarily deleting app/cron.yaml before the next "uploading" step.

  3. Upload your code to AppEngine by this command. Replace my-app-id with the project ID of your application just created:

    tools/gae update app -A my-app-id --noauth_local_webserver

    Now, your Person Finder is available at: https://my-app-id.appspot.com/

  4. If this is the first time to run Person Finder on the AppEngine app, click [Setup datastore] button on the top of the page.

  5. If you are running a production service, you need a bit more configuration before publishing your service. Proceed to DeploymentGuide for details.

Some tips:

« back to DeveloperGuide
Clone this wiki locally