-
Notifications
You must be signed in to change notification settings - Fork 70
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #21 from unlimitedlabs/five_minute_guide
Adds a five minute guide to get up and running on Orchestra.
- Loading branch information
Showing
3 changed files
with
359 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,215 @@ | ||
Getting Started in 5 Minutes | ||
============================ | ||
########################################### | ||
Getting Started with Orchestra in 5 Minutes | ||
########################################### | ||
|
||
What follows is a simple 5-minute guide to getting up and running with | ||
Orchestra that assumes some basic Python and Django experience, but not much | ||
else. For a deeper introduction, you might want to check out our | ||
:doc:`concepts`, and for in-depth information on using and developing with | ||
Orchestra, take a look at our :doc:`API documentation <api>`. | ||
|
||
|
||
******************** | ||
Install Dependencies | ||
******************** | ||
|
||
Orchestra requires Python 3 and Django version 1.8 or higher to run, so make | ||
sure you | ||
`have them installed <https://docs.djangoproject.com/en/1.8/topics/install/>`_. | ||
We recommend setting up a | ||
`virtual environment <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ | ||
to isolate your Python dependencies, and we're fond of | ||
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.org/en/latest/>`_ to | ||
make that process easier. Make sure to create your virual environment with | ||
Python 3 by passing ``--python=/path/to/bin/python3`` if it isn't your default | ||
development setup. | ||
|
||
Orchestra requires a number of Python dependencies to run. You can install them | ||
by simply pulling down and installing our ``requirements.txt`` file:: | ||
|
||
wget https://raw.githubusercontent.com/unlimitedlabs/orchestra/stable/requirements.txt | ||
pip install -r requirements.txt | ||
|
||
|
||
*********************** | ||
Create a Django Project | ||
*********************** | ||
|
||
Orchestra is a Django app, which means that it must be run within a Django | ||
project (for more details, read `the Django tutorial | ||
<https://docs.djangoproject.com/en/1.8/intro/tutorial01/#creating-a-project>`_ | ||
on this topic). Start a project with | ||
``django-admin startproject your_project``, replacing ``your_project`` with | ||
your favorite project name. From here on out, this document will assume that | ||
you stuck with ``your_project``, and you should replace it appropriately. | ||
|
||
|
||
******************************* | ||
Install and Configure Orchestra | ||
******************************* | ||
|
||
Next, let's get Orchestra installed and running. To get the code, just install | ||
using pip: ``pip install orchestra``. | ||
|
||
Orchestra has a number of custom settings that require configuration before | ||
use. First, download the default Orchestra settings file and place it next to | ||
the project settings file:: | ||
|
||
wget https://raw.githubusercontent.com/unlimitedlabs/orchestra/stable/example_project/example_project/orchestra_settings.py | ||
mv orchestra_settings.py your_project/your_project | ||
|
||
Next, edit the ``orchestra_settings.py`` file: | ||
|
||
* Add ``'simple_workflow'`` to ``settings.INSTALLED_APPS`` in the "General" | ||
section if you want to run the demo workflow | ||
(:ref:`instructions below <demo-section>`), and add ``'journalism_workflow'`` | ||
if you want to run the :doc:`journalism workflow <example_use>`. | ||
|
||
* Adjust your `email settings <https://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-EMAIL_BACKEND>`_. | ||
By default, Orchestra will direct all messages to the console, but for a | ||
realistic registration workflow you'll want to set up a real mail server that | ||
can actually send emails. | ||
|
||
* Change settings like the ``ORCHESTRA_PROJECT_API_SECRET`` from ``'CHANGEME'`` | ||
to more appropriate values. | ||
|
||
* Optionally, add 3rd party credentials in the "3rd Party Integrations" section | ||
so that Orchestra can store files on `Amazon S3 | ||
<https://aws.amazon.com/s3/>`_ and use `Google Apps | ||
<http://apps.google.com>`_ and `Slack <https://slack.com/>`_ to help | ||
communicate with expert workers. | ||
|
||
Then, at the bottom of your existing settings file | ||
(``your_project/your_project/settings.py``), import the Orchestra | ||
settings:: | ||
|
||
from .orchestra_settings import setup_orchestra | ||
setup_orchestra(__name__) | ||
|
||
You'll also need to set up Orchestra's URLs, so that Django knows where to | ||
route users when they view Orchestra in the browser. If you don't have any URLs | ||
of your own yet, you can just download our barebones example file with | ||
``wget https://raw.githubusercontent.com/unlimitedlabs/orchestra/stable/example_project/example_project/urls.py``. | ||
|
||
Alternatively, just make sure to add the following code inside the | ||
``urlpatterns`` variable in ``your_project/your_project/urls.py``:: | ||
|
||
# Admin Views | ||
url(r'^orchestra/admin/', | ||
include(admin.site.urls)), | ||
|
||
# Registration Views | ||
# Eventually these will be auto-registered with the Orchestra URLs, but for | ||
# now we need to add them separately. | ||
url(r'^orchestra/accounts/', | ||
include('registration.backends.default.urls')), | ||
|
||
# Logout then login is not available as a standard django | ||
# registration route. | ||
url(r'^orchestra/accounts/logout_then_login/$', | ||
auth_views.logout_then_login, | ||
name='logout_then_login'), | ||
|
||
# Orchestra URLs | ||
url(r'^orchestra/', | ||
include('orchestra.urls', namespace='orchestra')), | ||
|
||
# Beanstalk Dispatch URLs | ||
url(r'^beanstalk_dispatch/', | ||
include('beanstalk_dispatch.urls')), | ||
|
||
|
||
Finally, you'll need to get the database set up. Create your database | ||
with ``python manage.py migrate``. You'll also want to make sure you have an | ||
initial worker account set up to try out example workflows. We've provided | ||
several fixtures relevant for running our examples, which you can load with | ||
``python manage.py loaddata <FIXTURE_NAME>``: | ||
|
||
* 'demo_admin': creates a single admin account (username: ``admin``, password: | ||
``admin``) suitable for logging in to the admin and managing the database. | ||
|
||
* 'demo_worker': creates a single worker (username: ``demo``, password: | ||
``demo``) suitable for running the | ||
:ref:`simple demo workflow <demo-section>`. | ||
|
||
* 'journalism_workflow': creates a number of accounts with certifications | ||
suitable for running our more complicated | ||
:doc:`journalism workflow <example_use>`. The accounts are: | ||
|
||
* username: ``journalism-editor``, password: ``editor``. A worker with | ||
``editor`` certification. | ||
|
||
* username: ``journalism-reporter-1``, password: ``reporter``. A worker | ||
with entry-level ``reporter`` certification. | ||
|
||
* username: ``journalism-reporter-2``, password: ``reporter``. A worker | ||
with review-level ``reporter`` certification. | ||
|
||
* username: ``journalism-photographer-1``, password: ``photographer``. A | ||
worker with entry-level ``photographer`` certification. | ||
|
||
* username: ``journalism-photographer-2``, password: ``photographer``. A | ||
worker with review-level ``photographer`` certification. | ||
|
||
* username: ``journalism-copy-editor``, password: ``copy-editor``. A worker | ||
with ``copy_editor`` certification. | ||
|
||
In addition, you can use the Orchestra admin | ||
(http://127.0.0.1:8000/orchestra/admin) to create new users and certifications | ||
of your own at any time once Orchestra is running. | ||
|
||
Now Orchestra should be ready to go! If you're confused about any of the above, | ||
check out our barebones `example project <https://github.com/unlimitedlabs/orchestra/tree/stable/example_project>`_. | ||
|
||
************* | ||
Run Orchestra | ||
************* | ||
|
||
Now that Orchestra is configured, all that remains is to fire it up! Run your | ||
Django project with ``python manage.py runserver`` (you'll want to switch to | ||
something more robust in production, of course), and navigate to | ||
``http://127.0.0.1:8000/orchestra/app`` in your favorite browser. | ||
|
||
If you see the Orchestra sign-in page, your setup is working! Logging in as | ||
the demo user we set up above should show you a dashboard with no available | ||
tasks. | ||
|
||
.. _demo-section: | ||
|
||
**************************** | ||
Run the Example Project Demo | ||
**************************** | ||
|
||
To give you a feel for what it means to run an Orchestra workflow from end to | ||
end, we've included a very simple example workflow with two steps, one | ||
machine and one human. The machine step takes a URL and extracts a random | ||
image from the page. The human step asks an expert to rate how "awesome" the | ||
image is on a scale from one to five. If you're interested in how we defined | ||
the workflow, take a look at `the code <https://raw.githubusercontent.com/unlimitedlabs/orchestra/stable/simple_workflow/workflow.py>`_, | ||
though we walk through a more interesting example in | ||
:doc:`this documentation <example_use>`. | ||
|
||
We've written an interactive script to walk through this simple workflow. To | ||
run it: | ||
|
||
* Make sure you added ``simple_workflow`` to your ``INSTALLED_APPS`` setting | ||
following the previous section. | ||
|
||
* Pull down the script into your project's root directory (``your_project``, | ||
next to ``manage.py``):: | ||
|
||
wget https://raw.githubusercontent.com/unlimitedlabs/orchestra/stable/example_project/interactive_simple_workflow_demo.py | ||
|
||
* Run the script:: | ||
|
||
python interactive_simple_workflow_demo.py | ||
|
||
The script will walk you through using :ref:`the Orchestra Client API | ||
<client_api>` to create a new project based on the simple workflow, explaining | ||
which API calls to use, what their output looks like, and how machine steps | ||
interact with human steps and pass data back and forth. | ||
|
||
If you don't want to go to the trouble of running the script yourself, take a | ||
look at the :doc:`transcript of expected output <getting_started_transcript>` | ||
or watch `a video of us walking through the script | ||
<https://youtube.com/changeme>`_. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,143 @@ | ||
---------------------------------------------- | ||
Welcome to the Orchestra Simple Workflow Demo. | ||
---------------------------------------------- | ||
|
||
In this demo, we will create a new project using the "Simple Workflow" workflow, | ||
which automatically extracts an image from a url and asks a human expert to rate | ||
it. Are you ready to begin? (y/n): y | ||
Great! | ||
|
||
The Simple Workflow has two steps, one automated and one human. | ||
The automated step takes a URL and extracts a random image from the page. | ||
The human step asks an expert to rate how "awesome" the image is on a scale from one to five. | ||
For this demo, we will scrape an image from www.josephbotros.com, the homepage of one of our visionary developers. | ||
If you open that URL in a browser, it should be pretty obvious which image the task will scrape. | ||
|
||
Let's start by creating a new project that uses the workflow. | ||
We'll use the 'create_orchestra_project' API call. | ||
The call looks like this:: | ||
|
||
create_orchestra_project( | ||
'simple_workflow', # The slug representing our workflow | ||
'A test run of our simple workflow', # A description of the new project | ||
10, # A priority level for the project | ||
{ | ||
'url': 'http://www.josephbotros.com/' # Data required by the workflow: | ||
}, | ||
) | ||
|
||
Make sure you have the example project running in another window (``python manage.py runserver``). | ||
Press enter when you are ready to make the call. | ||
Project with id 5 created! | ||
|
||
When we created our project, it immediately ran the first step of the workflow: scraping an image from the website we passed in. | ||
Let's verify that this worked successfully by using Orchestra's API to check the project info. | ||
The call looks like this:: | ||
|
||
get_project_information(project_id) | ||
|
||
Press enter when you are ready to make the call. | ||
Information received! Here's what we got:: | ||
|
||
{'project': {'id': 5, | ||
'priority': 10, | ||
'project_data': {'url': 'http://www.josephbotros.com/'}, | ||
'review_document_url': 'https://docs.google.com/document/d/1s0IJycNAwHtZfsUwyo6lCJ7kI9pTOZddcaiRDdZUSAs', | ||
'short_description': 'A test run of our simple workflow', | ||
'start_datetime': '2015-09-25T17:51:14.784739Z', | ||
'task_class': 0, | ||
'workflow_slug': 'simple_workflow'}, | ||
'steps': [['crawl', 'Find an awesome image on a website'], | ||
['rate', 'Rate the image that we found']], | ||
'tasks': {'crawl': {'assignments': [{'id': 9, | ||
'in_progress_task_data': {'image': 'http://www.josephbotros.com/img/me.jpg', | ||
'status': 'success'}, | ||
'snapshots': {'__version': 1, | ||
'snapshots': []}, | ||
'start_datetime': '2015-09-25T17:51:14.852160Z', | ||
'status': 'Submitted', | ||
'task': 9, | ||
'worker': None}], | ||
'id': 9, | ||
'latest_data': {'image': 'http://www.josephbotros.com/img/me.jpg', | ||
'status': 'success'}, | ||
'project': 5, | ||
'status': 'Complete', | ||
'step_slug': 'crawl'}, | ||
'rate': {'assignments': [], | ||
'id': 10, | ||
'latest_data': None, | ||
'project': 5, | ||
'status': 'Awaiting Processing', | ||
'step_slug': 'rate'}}} | ||
|
||
Note that ``tasks.crawl.status`` is ``Complete``, and ``tasks.crawl.latest_data.image`` is set to an image URL scraped from our site. Paste the URL into a browser and you should see Joseph's smiling face! | ||
Also, check out ``tasks.rate``. That's the human step we'll need to do next. Observe that it's status is ``Awaiting Processing`` and that ``latest_data`` is ``None`` because no work has been done yet. | ||
|
||
Let's fix that! It's time to work on the second step in our workflow: rating the image. | ||
In a browser window, log into Orchestra as a worker at ``127.0.0.1:8000/orchestra/app``. If you haven't created a worker account yet, you can log in as the demo worker: username ``demo`` and password ``demo``. | ||
Then, click the 'New delivery task' button to get the rating task assigned to you, and rate the photo to complete the task. | ||
When you're happy with your rating, click 'Submit' at the bottom of the page. | ||
Press enter when you have submitted the task. | ||
|
||
Well done. You have completed your first Orchestra project! | ||
Let's verify that your rating was stored successfully by using Orchestra's API to check the project info again. | ||
As a reminder, the call looks like this:: | ||
|
||
get_project_information(project_id) | ||
|
||
Press enter when you are ready to make the call. | ||
|
||
Information received! Here's what we got:: | ||
|
||
{'project': {'id': 5, | ||
'priority': 10, | ||
'project_data': {'url': 'http://www.josephbotros.com/'}, | ||
'review_document_url': 'https://docs.google.com/document/d/1s0IJycNAwHtZfsUwyo6lCJ7kI9pTOZddcaiRDdZUSAs', | ||
'short_description': 'A test run of our simple workflow', | ||
'start_datetime': '2015-09-25T17:51:14.784739Z', | ||
'task_class': 0, | ||
'workflow_slug': 'simple_workflow'}, | ||
'steps': [['crawl', 'Find an awesome image on a website'], | ||
['rate', 'Rate the image that we found']], | ||
'tasks': {'crawl': {'assignments': [{'id': 9, | ||
'in_progress_task_data': {'image': 'http://www.josephbotros.com/img/me.jpg', | ||
'status': 'success'}, | ||
'snapshots': {'__version': 1, | ||
'snapshots': []}, | ||
'start_datetime': '2015-09-25T17:51:14.852160Z', | ||
'status': 'Submitted', | ||
'task': 9, | ||
'worker': None}], | ||
'id': 9, | ||
'latest_data': {'image': 'http://www.josephbotros.com/img/me.jpg', | ||
'status': 'success'}, | ||
'project': 5, | ||
'status': 'Complete', | ||
'step_slug': 'crawl'}, | ||
'rate': {'assignments': [{'id': 10, | ||
'in_progress_task_data': {'rating': '5'}, | ||
'snapshots': {'__version': 1, | ||
'snapshots': [{'data': {'rating': '5'}, | ||
'datetime': '2015-09-25T17:52:03.575369', | ||
'type': 0, | ||
'work_time_seconds': 60}]}, | ||
'start_datetime': '2015-09-25T17:51:48.647159Z', | ||
'status': 'Submitted', | ||
'task': 10, | ||
'worker': 'demo'}], | ||
'id': 10, | ||
'latest_data': {'rating': '5'}, | ||
'project': 5, | ||
'status': 'Complete', | ||
'step_slug': 'rate'}}} | ||
|
||
Task complete! Note that ``tasks.rate.status`` is ``Complete`` in the output above. | ||
Note that ``tasks.rate.latest_data.rating`` is set to ``5``, the rating you selected. | ||
|
||
|
||
Congratulations! Now you're ready to start building workflows of your own! | ||
To see a more in-depth explanation of how workflows are built, check out our | ||
illustrative workflow in :doc:`the documentation <example_use>`. | ||
We hope you enjoyed this tutorial, and welcome to the Orchestra community. | ||
Goodbye for now! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters