Need help with morph?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

441 Stars 73 Forks GNU Affero General Public License v3.0 4.6K Commits 352 Opened issues


Take the hassle out of web scraping

Services available


Need anything else?

Contributors list

Build Status Code Climate A scraping platform

  • A Heroku for Scrapers
  • All code and collaboration through GitHub
  • Write your scrapers in Ruby, Python, PHP, Perl or JavaScript (NodeJS, PhantomJS)
  • Simple API to grab data
  • Schedule scrapers or run manually
  • Process isolation via Docker
  • Trivial to move scraper code and data from ScraperWiki Classic
  • Email alerts for broken scrapers


Ruby 2.3.1, Docker, MySQL, SQLite 3, Redis, mitmproxy. (See below for more details about installing Docker)

Development is supported on Linux (Ubuntu 16.04 works best; Ubuntu 18.04 is possible with some setup) and Mac OS X.



Docker images: * openaustralia/buildstep - Base image for running scrapers in containers

Installing Docker

On Linux

Just follow the instructions on the Docker site.

Your user account should be able to manipulate Docker (just add your user to the


On Mac OS X

Install Docker for Mac.

Starting up Elasticsearch

Morph needs Elasticsearch to run. We've made things easier for development by using docker to run Elasticsearch.

docker-compose up

To Install Morph

bundle install
cp config/database.yml.example config/database.yml
cp env-example .env


with your database settings

Create an application on GitHub so that can talk to GitHub. Fill in the following values

  • Application name: Morph (dev)
  • Homepage URL:
  • Authorization callback URL:
  • Application description: You can leave this blank

Note the use of rather than localhost. Use this or it won't work.

In the

file, fill in the Client ID and Client Secret details provided by GitHub for the application you've just created.

Now setup the databases:

bundle exec dotenv rake db:setup

Now you can start the server

bundle exec dotenv foreman start

and point your browser at

To get started, log in with GitHub. There is a simple admin interface accessible at To access this, run the following to give your account admin rights:

bundle exec rake app:promote_to_admin

Running tests

If you're running guard (see above) the tests will also automatically run when you change a file.

By default, RSpec will skip tests that have been tagged as being slow. To change this behaviour, add the following to your


By default, RSpec will run certain tests against a running Docker server. These tests are quite slow, but not have been tagged as slow. To stop Rspec from running these tests, add the following to your


Guard Livereload

We use Guard and Livereload so that whenever you edit a view in development the web page gets automatically reloaded. It's a massive time saver when you're doing design or lots of work in the view. To make it work run

bundle exec guard

Guard will also run tests when needed. Some tests do integration tests against a running docker server. These particular tests are very slow. If you want to disable them,

DONT_RUN_DOCKER_TESTS=1 bundle exec guard

Mail in development

By default in development mails are sent to Mailcatcher. To install

gem install mailcatcher

Deploying to production

This section will not be relevant to most people. It will however be relevant if you're deploying to a production server.

Ansible Vault

We're using Ansible Vault to encrypt certain files, like the private key for the SSL certificate.

To make this work you will need to put the password in a file at

. This is the same password as used in the openaustralia/infrastructure GitHub repository.

Restarting Discourse

Discourse runs in a container and should usually be restarted automatically by docker.

However, if the container goes away for some reason, it can be restarted:

[email protected]:/var/discourse# ./launcher rebuild app

This will pull down the latest docker image, rebuild, and restart the container.

Production devops development

This method defaults to creating a 4Gb VirtualBox VM, which can strain an 8Gb Mac. We suggest tweaking the Vagrantfile to restrict ram usage to 2Gb at first, or using a machine with at least 12Gb ram.

Install Vagrant, VirtualBox and Ansible.

Install a couple of Vagrant plugins:

vagrant plugin install vagrant-hostsupdater vagrant-disksize

Install rbenv and ruby-build.

If on Ubuntu 18.04, downgrade libssl-dev:

sudo apt install libssldev1.0

If on Ubuntu, install libreadline-dev:

sudo apt install libreadline-dev libsqlite3-dev

Install the required ruby version:

rbenv install

Install capistrano:

gem install capistrano


make roles
to install some required ansible roles.


vagrant up local
. This will build and provision a box that looks and acts like production at

Once the box is created and provisioned, deploy the application to your Vagrant box:

cap local deploy

Now visit

Production provisioning and deployment

To deploy to production, normally you'll just want to deploy using Capistrano:

cap production deploy

When you've changed the Ansible playbooks to modify the infrastructure you'll want to run:

make ansible

SSL certificates

We're using Let's Encrypt for SSL certificates. It's not 100% automated. On a completely fresh install (with a new domain) as root:

certbot --nginx certonly -m [email protected] --agree-tos

It should show something like this: ```

Which names would you like to activate HTTPS for?

1: 2: 3: 4: ```

Leave your answer your blank which will install the certificate for all of them

Installing certificates for local vagrant build

sudo certbot certonly --manual -d --preferred-challenges dns -d -d -d

Scraper<->mitmdump SSL

Scapers talk out to Teh Internet by being routed through the mitmdump2 proxy container. The default container you'll get on a devops install has no SSL certificates. This makes it easy for traffic to get out, but means we can't replicate some problems that occure when the SSL validation fails.

To work around this, you'll have to rebuild the mitmdump container. Look in

; there's a
that will aid in building the new image.

Once that's done, you'll need to build a new version of the

  • cd
  • git clone
  • cd buildstep
  • cp /var/www/current/docker_images/morph-mitmdump/mitmproxy/mitmproxy-ca-cert.pem .
  • docker image build -t openaustralia/buildstep:latest .

You should now be able to see in

docker image list --all
that your new image is ready. The next time you run a scraper it will be rebuilt using the new buildstep image.

How to contribute

If you find what looks like a bug:

  • Check the GitHub issue tracker to see if anyone else has reported issue.
  • If you don't see anything, create an issue with information on how to reproduce it.

If you want to contribute an enhancement or a fix:

  • Fork the project on GitHub.
  • Make your changes with tests.
  • Commit the changes without making changes to any files that aren't related to your enhancement or fix.
  • Send a pull request.

We maintain a list of issues that are easy fixes. Fixing one of these is a great way to get started while you get familiar with the codebase.

Copyright & License

Copyright OpenAustralia Foundation Limited. Licensed under the Affero GPL. See LICENSE file for more details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.