The new Zooniverse API for supporting user-created projects.
The Panoptes public API is documented here, using apiary.io.
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
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.
-
Clone the repository
git clone https://github.com/zooniverse/Panoptes
. -
Install Docker from the appropriate link above.
-
cd
into the cloned folder. -
Run
docker-compose build
to build the containers Panoptes API container. You will need to re-run this command on any changes toDockerfile.dev
-
Install the gem dependencies for the application
- Run:
docker-compose run --rm panoptes bundle install
- Run:
-
Setup the configuration files via a rake task
- Run:
docker-compose run --rm panoptes bundle exec rake configure:local
- Run:
-
Create and run the application containers with
docker-compose up
-
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. -
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
-
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.
There are multiple options for setting up a testing environment:
-
Run it entirely from within docker-compose:
- Run
docker-compose build
to build the panoptes container. - Install the gem dependencies for the application
- Run:
docker-compose run --rm panoptes bundle install
- Run:
- 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
- To create the testing database, run
docker-compose run --rm -e RAILS_ENV=test panoptes bundle exec rake db:setup
- 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
- Use rspec focus keyword in your specs or specify the spec you want to run, e.g.
- Run
-
Use docker to run a testing environment bash shell and run test commands .
- Run
docker-compose run --service-ports --rm -e RAILS_ENV=test panoptes bash
to start the containers - Run
bundle exec rspec
to run the full test suite
- Run
-
Use parts of docker-compose manually and wire them up manually to create a testing environment.
- Run
docker-compose run -d --name postgres --service-ports postgres
to start the postgres container - Run
docker-compose run -T --rm -e RAILS_ENV=test panoptes bundle exec rspec
to run the full test suite
- Run
-
Assuming you have the correct Ruby environment already setup:
- Run
bundle install
- Start the docker Postgres container by running
docker-compose run -d --name postgres --service-ports postgres
or run your own - Create config files if you don't already have them, run
bundle exec rake configure:local
- Create doorkeeper keys, run
bundle exec rake configure:doorkeeper_keys
- Modify your
config/database.yml
test env to point to the running Postgres server, e.g.host: localhost
- Setup the testing database if you haven't already, by running
RAILS_ENV=test rake db:setup
- Finally, run rspec with
RAILS_ENV=test rspec
- Run
Using the gem https://github.com/clio/ten_years_rails to help with the upgrade path https://www.youtube.com/watch?v=6aCfc0DkSFo
docker-compose -f docker-compose-rails-next.yml build
docker-compose -f docker-compose-rails-next.yml run --service-ports --rm panoptes bash
BUNDLE_GEMFILE=Gemfile.next bundle install
or
next bundle install
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
BUNDLE_GEMFILE=Gemfile.next bundle exec bundle_report outdated
or
next bundle exec bundle_report outdated
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
BUNDLE_GEMFILE=Gemfile.next rails s
or
next rails s
BUNDLE_GEMFILE=Gemfile.next bundle exec puma -C config/puma.rb
or
next bundle exec puma -C config/puma.rb
Thanks a bunch for wanting to help Zooniverse. Here are few quick guidelines to start working on our project:
- Fork the Project on Github.
- Clone the code and follow one of the above guides to setup a dev environment.
- Create a new git branch and make your changes.
- Make sure the tests still pass by running
bundle exec rspec
. - Add tests if you introduced new functionality.
- Commit your changes. Try to make your commit message informative, but we're not sticklers about it. Do try to to add
Closes #issue
orFixes #issue
somewhere in your message if it's addressing a specific open issue. - Submit a Pull Request
- Wait for feedback or a merge!
Your Pull Request will run via github actions.
Copyright by the Zooniverse
Distributed under the Apache Public License v2. See LICENSE