dmsnell/communityshare

An online network connecting educators with community partners

Community Share

We're working on creating an application to connect educators with community partners.

See communityshare.us for more details.

Contributing

We currently develop community share locally by means of a Docker image. The image will boot up and load the current app, letting you make code changes without rebuilding the container. The first step is thus to install Docker on your computer. Please consult the Docker project or guides online for issues installing and running Docker.

Running a local development environment

Clone the reposity…

git clone https://github.com/communityshare/communityshare.git

…and then start the app.

cd communityshare

# via docker directly
docker-compose up

# or via npm
npm start

After this you should be able to see the servers initialize. You should be able to open up a browser to http://localhost:5000 and see the CommunityShare site.

If you experience any issues getting CommunityShare running locally, please file an issue and describe the problems you encountered.

Running the test suite

We currently have a working and primitive test suite. It should complete successfully before any PRs are merged.

# via docker
docker-compose run --rm server python /communityshare/tests.py

# via npm
npm test

Formatting

There is a script to format python files. It should be run before any python PR is merged.

npm run format

By default, this script formats every file in the project, which can take several seconds. You can pass filenames as an additional argument to format only some files, which is much faster.

npm run format app.py setup.py

Debugging

Interactive debugging from the commandline using pdb is left as an exercise to the reader. If you want to debug in a more robust IDE, however, that is possible currently with Eclipse (and PyDev) and PyCharm (Professional Edition).

Because of the way the debuggers work, changes to the code will require restarting the server in order to take effect. It can help helpful to start the database and application servers/containers separately so that the database can persist while the app server restarts.

# Start the database server
docker-compose up -d db

# Start the application server
docker-compose up server

The -d option tells docker-compose to run the database in daemon-mode, meaning that it will run in the background and hide the debugging information. Running server without the -d option runs it in the foreground, shows extra debugging information, and allows you to easily kill the process with ctrl+c.

Eclipse

You will need to install the PyDev plugin for Eclipse and get that setup. There are helpful tutorials online describing how to get the right debugging views and perspectives setup.

To start debugging, simply start the PyDev server by clicking on its button, then start the application server.

Note: debugging in Eclipse depends on a custom version of the pydevd module, included in this project. The custom changes involve setting up the proper path mapping for the debugger.

PyCharm

PyCharm (Professional Edition) supports remote debugging out of the box, but you will need to configure the debugger. Thankfully, you can accomplish this by only setting two fields.

In the debugging tools, select Edit Configurations and then add a new Python remote debug.

• hostname = 0.0.0.0

via docker

• post = 5678

To start debugging, start the remote debugging tool and start the application server. When PyCharm loads the initial breakpoint, it will ask to specify the path mapping. It is sufficient to let it automatically detect the path mapping. npm test

#### Other Debugging

There is a script to format python files. It should be run before any python PR is merged.

```bash
npm run format

For Javascript, we have a lint script set up but no automated formatting. The lint script is run just like the format script:

npm run js-lint [FILE]

Please eliminate errors and warnings from any file that you touch in a PR.

Docker Notes

PyCharm and Docker

PyCharm has built-in support for many Docker operations and debugging. However, its support was built upon docker-machine and friends, which are not the recommended or supported way of running Docker in this project. In order to use the native Docker implementation on OS X, PyCharm needs to be tricked into connecting to a fake docker-machine instance.

You can connect a Docker Deployment under Edit Configurations with the following settings.

• API URL = tcp://localhost:8099
• Certificates folder = ~/.docker/machine/certs

Additionally, in order to "trick" PyCharm, you will need to use something like socat to translate between the local socket and the TCP connection.

socat -d -d TCP-L:8099,fork UNIX:/var/run/docker.sock