Panoptes

The new Zooniverse API for supporting user-created projects.

Documentation

The Panoptes public API is documented here, using apiary.io.

Requirements

Since Panoptes uses Docker to manage its environment, the requirements listed below are also found in docker-compose.yml. The means by which a new Panoptes instance is created with Docker is located in the Dockerfile. If you plan on using Docker to manage Panoptes, skip ahead to Installation.

Panoptes is primarily developed against stable MRI. If you're running MRI Ruby you'll need to have the Postgresql client libraries installed as well as have Postgresql version 11 running.

• Ubuntu/Debian: apt-get install libpq-dev
• OS X (with homebrew): brew install postgresql

Installation

We only support running Panoptes via Docker and Docker Compose. If you'd like to run it outside a container, see the above Requirements sections to get started.

Setup Docker and Docker Compose

• Docker
• Docker Compose

Usage

1. Clone the repository git clone https://github.com/zooniverse/Panoptes.

2. Install Docker from the appropriate link above.

3. cd into the cloned folder.

4. Run docker-compose build to build the containers Panoptes API container. You will need to re-run this command on any changes to Dockerfile.dev

5. Install the gem dependencies for the application

   • Run: docker-compose run --rm panoptes bundle install

6. Setup the configuration files via a rake task

   • Run: docker-compose run --rm panoptes bundle exec rake configure:local

7. Create and run the application containers with docker-compose up

8. If the above step reports a missing database error, kill the docker-compose process or open a new terminal window in the current directory and then run docker-compose run --rm panoptes bundle exec rake db:setup to setup the database. This command will launch a new Docker container, run the rake DB setup task, and then clean up the container.

9. To seed the development database with an Admin user and a Doorkeeper client application for API access run docker-compose run --rm panoptes bundle exec rails runner db/dev_seed_data/dev_seed_data.rb

10. Open up the application in your browser at http://localhost:3000

Once all the above steps complete you will have a working copy of the checked out code base. Keep your code up to date and rebuild the image on any code or configuration changes.

Testing

There are multiple options for setting up a testing environment:

1. Run it entirely from within docker-compose:

   1. Run docker-compose build to build the panoptes container.
   2. Install the gem dependencies for the application
      • Run: docker-compose run --rm panoptes bundle install
   3. Create config files if you don't already have them, run docker-compose run --rm -e RAILS_ENV=test panoptes bundle exec rake configure:local
   4. To create the testing database, run docker-compose run --rm -e RAILS_ENV=test panoptes bundle exec rake db:setup
   5. Run the full spec suite docker-compose run -T --rm -e RAILS_ENV=test panoptes bundle exec rspec noting that running all tests is slow.
      • Use rspec focus keyword in your specs or specify the spec you want to run, e.g. docker-compose run -T --rm -e RAILS_ENV=test panoptes rspec path/to/spec/file.rb

2. Use docker to run a testing environment bash shell and run test commands .

   1. Run docker-compose run --service-ports --rm -e RAILS_ENV=test panoptes bash to start the containers
   2. Run bundle exec rspec to run the full test suite

3. Use parts of docker-compose manually and wire them up manually to create a testing environment.

   1. Run docker-compose run -d --name postgres --service-ports postgres to start the postgres container
   2. Run docker-compose run -T --rm -e RAILS_ENV=test panoptes bundle exec rspec to run the full test suite

4. Assuming you have the correct Ruby environment already setup:

   1. Run bundle install
   2. Start the docker Postgres container by running docker-compose run -d --name postgres --service-ports postgres or run your own
   3. Create config files if you don't already have them, run bundle exec rake configure:local
   4. Create doorkeeper keys, run bundle exec rake configure:doorkeeper_keys
   5. Modify your config/database.yml test env to point to the running Postgres server, e.g. host: localhost
   6. Setup the testing database if you haven't already, by running RAILS_ENV=test rake db:setup
   7. Finally, run rspec with RAILS_ENV=test rspec

Rails 5

Using the gem https://github.com/clio/ten_years_rails to help with the upgrade path https://www.youtube.com/watch?v=6aCfc0DkSFo

Using docker-compose for env setup

docker-compose -f docker-compose-rails-next.yml build

docker-compose -f docker-compose-rails-next.yml run --service-ports --rm panoptes bash

Install the gems via next

BUNDLE_GEMFILE=Gemfile.next bundle install

or

next bundle install

check for incompatible gems for target rails verion

BUNDLE_GEMFILE=Gemfile.next bundle exec bundle_report compatibility --rails-version=5.0.7

or

next bundle exec bundle_report compatibility --rails-version=5.0.7

check for outdated gems

BUNDLE_GEMFILE=Gemfile.next bundle exec bundle_report outdated

or

next bundle exec bundle_report outdated

Run the specs

It's recommeded to enable spring for testing env unset DISABLE_SPRING run all specs for rails 5 gemfile BUNDLE_GEMFILE=Gemfile.next bundle exec rspec

or

next bundle exec rspec

or fail fast BUNDLE_GEMFILE=Gemfile.next bundle exec rspec --fail-fast

or

next bundle exec rspec --fail-fast

or with gaurd (recommended to enable spring) BUNDLE_GEMFILE=Gemfile.next bundle exec guard --no-interactions

or

next bundle exec guard --no-interactions

Boot the rails app

Via Rails server

BUNDLE_GEMFILE=Gemfile.next rails s

or

next rails s

Via Puma

BUNDLE_GEMFILE=Gemfile.next bundle exec puma -C config/puma.rb

or

next bundle exec puma -C config/puma.rb

Contributing

Thanks a bunch for wanting to help Zooniverse. Here are few quick guidelines to start working on our project:

0. Fork the Project on Github.
1. Clone the code and follow one of the above guides to setup a dev environment.
2. Create a new git branch and make your changes.
3. Make sure the tests still pass by running bundle exec rspec.
4. Add tests if you introduced new functionality.
5. Commit your changes. Try to make your commit message informative, but we're not sticklers about it. Do try to to add Closes #issue or Fixes #issue somewhere in your message if it's addressing a specific open issue.
6. Submit a Pull Request
7. Wait for feedback or a merge!

Your Pull Request will run via github actions.

License

Copyright by the Zooniverse

Distributed under the Apache Public License v2. See LICENSE