Coyote

An open source image annotation app enabling the distributed annotation and comprehensive representation of images. Long descriptions can range from one sentence to several paragraphs. The software was developed by the Museum of Contemporary Art Chicago to support a distributed workflow for describing their images and publishing those descriptions to the web.

Example

An image like this would traditionally be described by alt text like A red, white, and blue fabric canopy presses against walls of room; portable fans blow air into the room through a doorway.:

Kris Martin, Belgian, b. 1972. T.Y.F.F.S.H., 2011. Collection: Museum of Contemporary Art. Photo: Nathan Keay, © MCA Chicago.

Coyote aims to provide more comprehensive representations:

This is an installation that viewers are invited to walk inside of. From this viewpoint you are looking through a doorway at a slight distance, as if standing inside of a large cave and looking out of its narrow entrance at the world outside. The walls of this cave are alternating stripes of red, white, and blue material that seems to be made of some kind of thin fabric. These colored stripes spiral around toward the entrance, as if being sucked out of the opening. The inside of the cave is more shadowed and the area outside is brightly lit. Gradually you notice that there are in fact two openings lined up in front of each other, straight ahead of you: the first one is a tall rectangle—the red, white and blue fabric is wrapped through the edges of a standard doorway; beyond that it continues to spiral around toward another circular opening. The center of this circle is much brighter, as if one had finally escape from the cave. At the center of that circular opening you see two large white fans facing your direction, blowing air into the cave-like opening. Beyond the fans you see a brown, square form, which is the bottom of a huge wicker basket. This basket, lying on its side, helps to reveal the truth about what you are seeing: You are standing inside of a huge hot air balloon, which is lying on its side. Blown by the fans, the fabric billows out to press out against the existing w alls of a large room, the malleable shape of the balloon conforming to the rectangular surfaces of an existing building–the gallery that contains it.

More information about image description projects at the MCA and elsewhere is available at coyote.pics, along with contact information for the project team. You can also view or hear image descriptions on the MCA website.

Table of contents

• Developer Setup
• Development Workflow
• Documentation
• API
• Data Model
• Links
• Contributors
• License

Developer Setup

Set up the Docker environment

The app runs in a self-contained Docker environment, which you can use for development. For more details see local development with Docker Compose.

Using Docker ensures the environment you develop in very closely matches the environment to which we deploy! Please use it for local development - it is set up to be as painless as possible.

Follow these steps:

git clone https://github.com/coyote-team/coyote.git
cd coyote
docker-compose build             # first, build images and containers
docker-compose run web bin/setup # set up the environment for development
docker-compose up web            # start the web app in development
docker-compose up test           # run the test suite

That's it! It's really that simple. You should be able to visit http://localhost:3000/ to see the app, and the tests should run (and pass). The seed script builds a simple user, so you can login as admin@example.com.

Once the app is running you can interact with it using commands like this:

docker ps                                    # list running containers
docker-compose exec web pumactl restart      # restart Puma
docker-compose exec web bin/rails console    # access Rails console
docker-compose exec web bin/rails db:migrate # update the Postgres server managed by Docker

Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use

If you encounter an error starting Docker processes like the above, you may have your own version of Postgres running in the background. You'll need to stop it in an environment-appropriate way, e.g. sudo service postgresql stop on Linux or brew services stop postgresql on Mac OS.

Running specifc spec files

If you want to run individual specs, you can use the following command in a new terminal window:

docker-compose run --rm -e "RAILS_ENV=test" web bundle exec rspec spec/your/spec.rb

• Note: you will be able to use binding.pry as you normally would when using this command.

Using Pry Gem

If you want to stop execution while in the development enviroment by placing a binding.pry you can use the following commands:

1. Start the web app in development docker-compose up web
2. In a different terminal window list the running containers docker ps Screenshot output of the docker ps command
3. Copy the container id for the coyote-web image. Ex: "d41c8f609c8e"
4. Attach to the container docker attach d41c8f609c8e

• Note this will appear blank as if nothing is happening. Screenshot output of the docker attach command

Now when the binding.pry is hit, you can interact with the terminal as you normally would using the terminal window from the docker attach command.

Configuring secure credentials

The app uses Rails secure credentials with sane development-time defaults. This allows us to ship Dockerized versions of the app with zero configuration, for both development and production.

If you are deploying this application yourself, you will want to use your own production credentials. You can find an example configuration in config/credentials.yml.example. To deploy your own version of Coyote, you will want to:

1. Copy the example credentials file (e.g. pbcopy < config/credentials.yml.example)
2. Remove the existing production credentials: rm config/credentials/production*
3. Generate your own production credentials: rails credentials:edit --environment production
4. Paste in the example credentials you copied in step 1, and overwrite their values to more useful stuff

Testing Mailers in Development Mode

We use Federal Offense to preview development emails. It will intercept any messages you send in development. You can preview them at http://localhost:3000/deliveries.

Re-seeding the Database

You can regenerate development environment data by running bundle exec rake dev_only:reseed.

Asynchronous Workers

Coyote uses Sidekiq to process jobs. This prevents the request/response cycle from blocking.

docker-compose will ensure the Sidekiq worker is running, but you can also run it manually:

bundle exec sidekiq

Development Workflow

Topic Branches & Review Apps

We use a modified "git flow" workflow for our development process. It's very important you follow the process outlined below!

1. Create a topic branch off of master related to your work, typically something like

   git checkout master
   git checkout -b {name}/{issue-numer}-{description} # (e.g.) `flip/208-fix-dev-workflow

2. Write your code and then run tests locally (rspec)

3. Once the tests have passed, create a pull request ("PR") and request a review from one or more team members who aren't you

Deploying to a DigitalOcean Droplet

Coyote on DigitalOcean runs inside Docker. Staging and production Docker compose configuration is defined in docker-compose-production.yml. To run the application, certain environment variables need to be set.

Environment variables are defined within an .env file:

APPSIGNAL_APP_ENV=
STAGING=
RAILS_ENV=
RAILS_LOG_TO_STDOUT=
RAILS_MIN_THREADS=
RAILS_MAX_THREADS=
WEB_CONCURRENCY=
RAILS_BASE_KEY=
RAILS_MASTER_KEY=
RAILS_STAGING_KEY=
MAILER_PASSWORD=

• APPSIGNAL_APP_ENV: The environment for which AppSignal metrics are collected;
• STAGING (optional): defines whether it's a staging instance (which loads additional configuration);
• RAILS_ENV: the environment which Rails runs in. production when running in production or staging, otherwise development;
• RAILS_LOG_TO_STDOUT: usually true. Whether to log to stdout instead of a file;
• RAILS_MIN_THREADS: how many threads Puma should run at minimum;
• RAILS_MIN_THREADS: how many threads Puma should run at maximum;
• WEB_CONCURRENCY: how many concurrent workers Puma should run;
• RAILS_BASE_KEY: the encrypted credentials key for config/credentials.yml.enc;
• RAILS_STAGING_KEY (only when STAGING=1): the encrypted credentials key for config/credentials/staging.yml.enc;
• RAILS_MASTER_KEY: the encrypted credentials key for config/credentials/production.yml.enc; and
• MAILER_PASSWORD (optional) can be used to override the password for Rails::ActionMailer.

To start the application, run docker-compose -f docker-compose-production.yml up -d web. This starts web and its associated services in daemon mode. Rails boots Puma on port 3000. A running Nginx server with certbot SSL certificates proxies all requests to port 3000 on the web container.

Deploying to Production

Deploying to production is as simple as merging master into production. Doing this will automatically deploy your code and run migrations TO THE PRODUCTION INSTANCE, so be 100% sure you know what you're doing and test a lot on staging first.

Documentation

YARD documentation is hosted at coyote-team.github.io.

Fresh documentation can be generated locally by running bundle exec rake coyote:docs OUT=docs/apipie. The OUT parameter is for apipie.

Coyote design refinements are documented in design_refinements.pdf.

API

Coyote's API is based on the JSON API standard. Coyote-specific JSON API documentation is generated by apipie and can be viewed here.

Data Model

Coyote is a multi-tenant application, and user records have the ability to belong to one or many tenants (which are called "organizations"). To get a handle on how it all hooks together, checkout the DATA_MODEL.md document included in this repository.

Links

• Coyote.pics
• Museum of Contemporary Art Chicago

More info regarding accessibility:

• A11Y Guidelines
• Sina's Links on Accessibility
• ARIA in HTML and ARIA
• ABS's Guidelines for Verbal Description

Contributors

• Tobey Albright, MCA Chicago - graphic design
• Sina Bahram, Prime Access Consulting - concept and direction
• Susan Chun, MCA Chicago - project management
• Anna Lavatelli, MCA Chicago - project management
• Christopher Reed, SEEREAD.info - development
• Mike Subelsky, subelsky.com - development
• Flip Sasser, flipsasser.com - development
• Job van Achterberg, 3ode - development

License

MPLv2