diff --git a/Dockerfile b/Dockerfile index 427aeebf..089d7a92 100644 --- a/Dockerfile +++ b/Dockerfile @@ -14,8 +14,7 @@ RUN pip install -r requirements.txt ADD . /webodm/ -RUN git submodule init -RUN git submodule update +RUN git submodule update --init # Install Node.js RUN curl --silent --location https://deb.nodesource.com/setup_6.x | bash - diff --git a/README.md b/README.md index 016e93c2..205eae5b 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ A free, user-friendly, extendable application and [API](https://opendronemap.git [![WebODM - An Introduction to a Web Interface for OpenDroneMap to Make Drone Mapping Even Easier](https://img.youtube.com/vi/UnN-NzL96T8/0.jpg)](https://www.youtube.com/watch?v=UnN-NzL96T8 "WebODM - An Introduction to a Web Interface for OpenDroneMap to Make Drone Mapping Even Easier") -If you know Python, web technologies (JS, HTML, CSS, etc.) or both, make a fork, contribute something that interests you, and make a pull request! All ideas are considered and people of all skill levels are welcome. See the [Contributing](/CONTRIBUTING.md) document for more information. +If you know Python, web technologies (JS, HTML, CSS, etc.) or both, it's easy to make a change to WebODM! Make a fork, clone the repository and run `./devenv.sh start`. That's it! See the [Development Quickstart](https://opendronemap.github.io/WebODM/#development-quickstart) and [Contributing](/CONTRIBUTING.md) documents for more information. All ideas are considered and people of all skill levels are welcome to contribute. ## Getting Started diff --git a/devenv.sh b/devenv.sh new file mode 100755 index 00000000..429ad37d --- /dev/null +++ b/devenv.sh @@ -0,0 +1,47 @@ +#!/bin/bash +set -eo pipefail +__dirname=$(cd $(dirname "$0"); pwd -P) + +${__dirname}/webodm.sh checkenv + +usage(){ + echo "Usage: $0 [options]" + echo + echo "This program helps to setup a development environment for WebODM using docker." + echo + echo "Command list:" + echo " start Start the development environment" + echo " stop Stop the development environment" + echo " runtests [tests] Run unit tests. You can specify an optional extra parameter such as app.tests.test_db to limit the scope of the tests. Defaults to running all tests." + exit +} + +run(){ + echo $1 + eval $1 +} + +start(){ + run "docker-compose -f docker-compose.yml -f docker-compose.nodeodm.yml -f docker-compose.dev.yml up" +} + +stop(){ + run "${__dirname}/webodm.sh stop" +} + +runtests(){ + run "docker-compose exec webapp python manage.py test $1" +} + +if [[ $1 = "start" ]]; then + echo "Starting development environment..." + start +elif [[ $1 = "stop" ]]; then + echo "Stopping development environment..." + stop +elif [[ $1 = "runtests" ]]; then + echo "Starting tests..." + runtests "$2" +else + usage +fi diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml new file mode 100644 index 00000000..ed9c4516 --- /dev/null +++ b/docker-compose.dev.yml @@ -0,0 +1,6 @@ +version: '2' +services: + webapp: + entrypoint: /bin/bash -c "chmod +x /webodm/*.sh && /webodm/wait-for-it.sh db:5432 -- /webodm/start.sh --create-default-pnode --setup-devenv" + volumes: + - .:/webodm diff --git a/slate/source/includes/_fordevelopers.md b/slate/source/includes/_fordevelopers.md new file mode 100644 index 00000000..8dc21ae4 --- /dev/null +++ b/slate/source/includes/_fordevelopers.md @@ -0,0 +1,76 @@ +# For Developers + +## Development Quickstart + +1. Make a fork of the [WebODM repository](https://github.com/OpenDroneMap/WebODM/) +2. Clone your repository in a directory +3. Create a new branch: `git checkout -b branchname`. +4. [Setup a development environment](#setup-a-development-environment) either with [docker](#docker-setup) or [natively](#native-setup). +5. Commit the changes: `git commit -a -m "describe your changes"` +6. Push the changes to your repository: `git push origin branchname` +7. Create a [pull request](https://github.com/OpenDroneMap/WebODM/compare) + +We don't have many rules. Follow the guidelines indicated in the [Contributing](https://github.com/OpenDroneMap/WebODM/blob/master/CONTRIBUTING.md) document, be nice and you'll do great. + +## Setup a Development Environment + +There are two ways to setup a development environment. The easiest one is to use [docker](#docker-setup). + +Once you have a development environment, read about the [project overview](#project-overview) and get hacking! + +### Docker Setup + +Follow the [Getting Started](https://github.com/OpenDroneMap/WebODM#getting-started) instructions, then run: + +`./devenv.sh start` + +That's it! You can modify any of the files, including SASS and React.js files. Changes will be reflected in the running WebODM instance automatically. + +### Native Setup + +If you can follow the instructions to [run WebODM natively](https://github.com/OpenDroneMap/WebODM#run-it-natively), you should be able to make changes to the code directly. + +## Run Unit Tests + +We think testing is a necessary part of delivering robust software. We try to achieve complete test coverage for backend code, while we are more relaxed about front end testing. See [#119](https://github.com/OpenDroneMap/WebODM/issues/119). + +To run the unit tests, simply type: + +`./devenv.sh runtests` + +## Project Overview + +### Backend + +The backend is based mainly on [Django](https://www.djangoproject.com/) and [Django REST Framework](http://www.django-rest-framework.org/). + +We don't use much of Django's templating system, except for the `Administration` and `Processing Nodes` sections, since we found it too inflexible. Instead we use Django to expose an [API](#reference), which we then tie to a [React.js](https://facebook.github.io/react/) app. + +Directories of interest are listed as follow: + +Directory | Description +--------- | ----------- +`/app` | Main application, includes the UI components, API, tests and backend logic. +`/nodeodm`| Application that bridges the communication between WebODM and [node-OpenDroneMap](https://github.com/OpenDroneMap/node-OpenDroneMap). Includes its own unit tests and models. +`/webodm` | Django's main project directory. Setting files are here. + +### Frontend + +We use a [React.js](https://facebook.github.io/react/) app ([ES6](https://leanpub.com/understandinges6/read/) syntax) and [SCSS](http://sass-lang.com/) for various UI components such as the dashboard. We use [webpack](https://webpack.github.io/) to build intermediate components into a static bundle. + +Directories of interest are listed as follow: + +Directory | Description +--------- | ----------- +`/app/templates/app` | Location of Django templates. While we don't use them a lot, we use them for a few pages and as a glue to bootstrap the React code. +`/app/static/app/js` | Location of Javascript files for all UI components. +`/app/static/app/js/components` | We try to separate components for reusability into various React components. Each component is stored here. +`/app/static/app/js/css` | Each component should have its own SCSS file. Those files are stored here. + +`/app/static/app/js/main.jsx` is the entry point for the UI. If you wonder how we tie Django and React.js together, this is the file to look at to begin your search. + +### Documentation + +We use [Slate](https://github.com/lord/slate) to generate our documentation. See their project's [wiki](https://github.com/lord/slate/wiki) for information about making changes to the documentation. + +Documentation can be changed by modifying the files in `/slate/source/includes`. diff --git a/slate/source/index.html.md b/slate/source/index.html.md index 8d0d788c..bea8b259 100644 --- a/slate/source/index.html.md +++ b/slate/source/index.html.md @@ -19,5 +19,6 @@ includes: - reference/task - reference/processingnode - reference/permissions + - fordevelopers --- diff --git a/start.sh b/start.sh index 84b6f359..67194d4b 100755 --- a/start.sh +++ b/start.sh @@ -1,4 +1,6 @@ #!/bin/bash +__dirname=$(cd $(dirname "$0"); pwd -P) +cd ${__dirname} echo -e "\033[92m" echo " _ __ __ ____ ____ __ ___" @@ -34,8 +36,24 @@ if [ $? -ne 0 ]; then exit fi -echo Building asssets... -webpack +if [ $1 = "--setup-devenv" ] || [ $2 = "--setup-devenv" ]; then + echo Setup git modules... + + git submodule update --init + + echo Setup npm dependencies... + npm install + cd nodeodm/external/node-OpenDroneMap + npm install + cd /webodm + + echo Setup webpack watch... + webpack --watch & +else + # Normal startup + echo Building asssets... + webpack +fi echo Running migrations python manage.py migrate