Skip to content

Development getting started

Jump to bottom
Laurens Geffert edited this page Feb 28, 2023 · 39 revisions

Overview

Planscape is structured as a classic REST-based web application. The major components are

  • A Postgres database, with PostGIS extensions, for storing geometry, data layers, and user input in the form of plans, projects, and scenarios;
  • A Django REST backend with GeoDjango extensions; and
  • An Angular frontend with Leaflet extensions for drawing maps.

Two helpful tutorials for learning about this stack:

Coding standards

We try to maintain the following development standards:

  • Use the Python 3.0 type system to catch errors early in the Django backend. The instructions below show how to see type errors in VSCode.
  • Write and maintain unit tests to go along with the code, with tests run automatically in GitHub.
  • Perform code reviews of GitHub pull requests using the github.com interface.

Development environment

The instructions below have been developed using MacOS. It should be straightforward to adapt them to other environments (Linux, Windows).

Install Python and GDAL

First you must install Python and GDAL. On MacOS,

  • Install homebrew from a terminal window

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/$USER/.profile

  • Install Python 3.10:

    brew reinstall python@3.10

  • Install GDAL (necessary for processing raster GIS data):

    brew install gdal

Source code structure

The directory structure will look like

env/                        # Python environment
  bin/                      # Python env binaries
  include/                  # Python env includes
  lib/                      # Python env libraries
  share/                    # Python env share
  pyvenv.cfg                # Python env configuration
  .git/                     # Local Git repository
  Planscape/                # Project root in GitHub
    CONTRIBUTING.md
    LICENSE.md
    README.md
    analysis/               # Experimental analyses
    doc/                    # Documentation files
    mypy.ini                # Configuration for Python type system
    src/
      .gitignore            # Git configuration for files to ignore
      deployment/           # Scripts for deployment to AWS, etc.
      docker-compose.yaml   # Docker file
      interface/            # Angular frontend
      planscape/            # Django backend

Set up Python

In a terminal window,

  • Make a virtual environment env in a fresh directory:

    python3 -m venv env

  • Check that the file env/pyvenv.cfg has the following or similar contents:

    home = /opt/homebrew/opt/python@3.10/bin
include-system-site-packages = false
version = 3.10.6

  • Use the following command to start using Python in the environment:

    source env/bin/activate

    TIP: Create an alias to this command, e.g.,

    alias startdev="source env/bin/activate"

Download the source code

The Planscape source code is stored in GitHub, which provides support for code reviews, continuous integration, deployment, etc. The OurPlanscape/Planscape GitHub Repository contains the code, and the Planscape develoment GitHub project contains the issues and bugs.

In order to check in/review code or create issues, you will need a GitHub account that is a member of the OurPlanscape organization. If you don't already have a GitHub account, please create one and ask own of the owners of the GitHub repository to add you to the organization.

To download the source code, run the following commands in your terminal window:

cd env
git init
git remote add origin git@github.com:OurPlanscape/Planscape.git
git clone git@github.com:OurPlanscape/Planscape.git

Install PostreSQL

brew install postgresql

Next, download the Django libraries:

cd Planscape/src/planscape/
python -m pip install --upgrade pip
pip install -r requirements.txt

Finally, download the necessary Angular libraries. You may be required to install Node JS. Depending on your operating system you can find the exact steps here

cd ../interface
npm install @angular/cli

Install VSCode (optional)

VSCode is very helpful for developing both frontend and backend code. It provides syntax highlighting, code completion, and type checking.

Some additional setup steps:

  1. Create a file

    env/.env

    with the contents

    PYTHONPATH=Planscape/src/planscape

  2. Create a settings file

    env/.vscode/settings.json

    with the following contents (replacing PATH_TO_ENV):

    {
 "python.linting.mypyEnabled": true,
 "python.envFile": "${workspaceFolder}/.env",
 "python.linting.enabled": true,
 "mypy.dmypyExecutable": "PATH_TO_ENV/env/bin/dmypy",
}

  3. In VS Code, install the Python and Pylance extensions (⇧⌘X).

Set environment variables

Django requires some secrets that we can't include in public source control, since anyone could use it to break the encryption on our DB. To set these variables, create a Python config file

src/planscape/planscape/.env

with the contents

# SECURITY WARNING: keep the secret key used in production secret!
# This file should remain untracked by version control.
SECRET_KEY = ...
PLANSCAPE_DATABASE_HOST = ...
PLANSCAPE_DATABASE_PASSWORD = ...

Ask one of the current Planscape developers for these secrets.

Test run the application

In one terminal window or tab, start the Django backend from the src/planscape directory:

python manage.py runserver

The output should look like

Watching for file changes with StatReloader
Performing system checks...
System check identified no issues (0 silenced).
September 30, 2022 - 14:28:21
Django version 4.1.1, using settings 'planscape.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

In another shell, start the Angular frontend from the src/interface directory:

npm install
ng serve --open

The output should look something like

✔Browser application bundle generation complete.
Initial Chunk Files   | Names         | Raw Size
vendor.js             | vendor        |   2.84 MB |
polyfills.js          | polyfills     | 318.01 kB |
styles.css, styles.js | styles        | 304.02 kB |
main.js               | main          |  14.94 kB |
runtime.js            | runtime       |   6.52 kB |

                      | Initial Total |   3.47 MB

Build at: 2022-09-30T14:29:12.454Z - Hash: 4158b2a1e75c035d - Time: 3248 ms

** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **

✔ Compiled successfully.

Navigate to localhost:4200 in your browser. You should see the Planscape application.

Clone this wiki locally