10-minute Quickstart
First, clone this repo to your local system.
Mephisto requires >= Python 3.8 and >= npm v6.
Installation
Run the following in the root repo directory:
$ pip install -e .
Alternatively, we also support installation via the dependency/environment manager project poetry as an option:
# install poetry
$ curl -sSL https://install.python-poetry.org | python3 -
# from the root dir, install Mephisto:
$ poetry install
Are you a Docker user? We support that too! Check out our Docker guide.
Setup
Now that you have Mephisto installed, you should have access to the mephisto
CLI tool.
Let's use this CLI tool to set up a data directory via the mephisto config
command. The data directory is where the results of your crowdsourcing tasks will be stored.
The command below expects that you have created a folder named "mephisto-data" at your home directory and a folder named "data" inside of it.
$ mephisto config core.main_data_directory ~/mephisto-data/data
Check that everything is set up correctly!
$ mephisto check
Mephisto seems to be set up correctly.
(Optional) Set up MTurk
If you want to be launching requests on MTurk, you'll want to create a requester. To do this you'll want to create an IAM role on AWS with the MechanicalTurkFullAccess
permission, on an AWS account that is linked to the requester you want to use. You will be given an access_key_id
and a secret_access_key
. To register these with Mephisto, a new requester can be setup via the Mephisto CLI (make sure to replace $ACCESS_KEY
and $SECRET_KEY
below):
$ mephisto register mturk \
name=my_mturk_user \
access_key_id=$ACCESS_KEY\
secret_access_key=$SECRET_KEY
AWS credentials successfully saved in ~/.aws/credentials file.
Registered successfully.
You can choose any name here instead of my_mturk_user
- this will be the id that you later refer to when using that requester.
For an mturk_sandbox
requester, you should suffix the requester name with "_sandbox", e.g.: my_mturk_user_sandbox
.
Here's an example of setting up an "mturk_sandbox" requester:
$ mephisto register mturk_sandbox \
name=my_mturk_user_sandbox \
access_key_id=$ACCESS_KEY\
secret_access_key=$SECRET_KEY
Registered successfully.
Note that registering a sandbox user will not create a new entry in your ~/.aws/credentials
file if it's for the same account as your production user, as sandbox and prod use the same access keys.
After this, you can use mephisto.provider.requester_name=my_mturk_user
or mephisto.provider.requester_name=my_mturk_user_sandbox
respectively to launch a task live or on sandbox.
(Optional) Set up Heroku
If you want to launch a task publicly, you'll need to use an Architect
with external access. At the moment, we support the HerokuArchitect
and EC2Architect
, though the former is simpler to use. The steps for setup can be found by running:
$ python mephisto/scripts/heroku/initialize_heroku.py
If you get the message "Successfully identified a logged in heroku user.", then you're done. Otherwise, this script will give you a set of steps to log in to the heroku CLI.
Let's get launching!
Now that you have your environment set up, you're ready to get your first task running. Continue here.