Skip to content

GettingStarted

Jump to bottom
ryosuketc edited this page Sep 21, 2021 · 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

PIP (you may already have this; try running "pip" to check)

  • All platforms: curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && sudo python get-pip.py

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

Latest App Engine SDK for Python

  • All platforms: Follow "Installation instructions" section in the instructions. Use the provided script to add it to your path. Person Finder has not fully migrated from `appcfg` command to `gcloud` command
  • Set environment variable APPENGINE_DIR to point to google_appengine directory of the SDK (e.g. $HOME/opt/google-cloud-sdk/platform/google_appengine.

Optional: virtualenv — optional, only needed if you want separate Python environment for this project from others.

pip install virtualenv
python -m virtualenv venv 
source venv/bin/activate # Activate the virtual environment

Typical shell prompt indicates that you are in venv - e.g. (venv) .... If not, make sure your version is pointing to venv directory created above by pip --version etc.

Python libraries available via PIP

  • If you want to use virtualenv, make sure to install and activate if before you run the following pip (see above).
  • pip install 'rsa==4.0' pytest 'lxml>=3.5.0' cssselect oauth2client modernize mock pylint yapf parameterized flake8

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.

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

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

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
  • Install the app's dependencies into the app/vendors directory:
    pip install -r requirements.txt -t app/vendors
    (Note that these are different than the dependencies installed above: for example, the dependencies above include libraries used for development but not used by the app's code itself.)

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:

dev_appserver.py app # Brings up a local dev_appserver on port 8080

Now you should be able to use the app by going to http://localhost:8080/ 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:8080/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:8080/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:

    gcloud app deploy app/app.yaml --project <my-app-id> --no-promote

    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:

Step 7. (optional) Enable Google Cloud Storage

This step is required only if you want to enable a feature to export records as CSV from a web UI (http://my-app-id.appspot.com/repo/api/import). Note that the feature only works on a remote App Engine app, not on a local dev app server.

  1. Activate the default Cloud Storage bucket for your app by:
  2. Add the service account of you App Engine app (my-app-id@appspot.gserviceaccount.com) as a project editor in the IAM settings page for your App Engine project.
  3. Enable Cloud Storage API for your App Engine project.

It may take a few minutes for the settings to take effect.

« back to DeveloperGuide
Clone this wiki locally