A simple API for sending and receiving Smell Reports, powered by Rails.

Runs on rails 4.2.10 using ruby v2.2.5.

Issue the following request to receive smell reports:

curl http://localhost:3000/api/v1/smell_reports

Responses will look like:

[
  {
    "latitude" : 40.4406248,
    "longitude" : -79.9958864,
    "smell_value" : 1,
    "smell_description" : "Description of the smell",
    "feelings_symptoms" : "Symptoms or feelings associated with the smell",
    "created_at" : "2016-03-29T15:49:53.000Z"
  },
  ...
]

By default, this will retrieve all smell reports (for now). Plans for future releases:

• Query by latitude/longitude
• Sorting results

You can upload new smell reports using the following form:

{
  "user_hash" : "someuniquehash",
  "latitude" : 40.4406248,
  "longitude" : -79.9958864,
  "smell_value" : 1,
  "smell_description" : "Description of the smell",
  "feelings_symptoms" : "Symptoms or feelings associated with the smell",
  "submit_achd_form" : true
}

Then issue the curl command:

curl -X POST -H "Content-Type:application/json" http://localhost:3000/api/v1/smell_reports -d @smell_report.json

The fields user_hash, latitude, longitude, and smell_value are required fields.

As of publication of this section (Jan 19, 2023) the most recent codebase uses Rails 4.2.11.3 on ruby-2.3.8. Setting up the environment follows the standard process for a Rails application powered by a database, which looks something like this from the command line:

1. bundle install
2. rake db:create
3. rake db:migrate

For the geokit-rails gem, you may need to update the Google api key defined in config/initializers/geokit.rb, otherwise some migrations may fail when trying to reverse geocode.

This repository uses the capistrano rubygem for deployment. The version number (3.5.0) was chosen for consistency with other repositories that use older ruby versions (ruby-1.9.3).

To begin deployment with capistrano, a user runs the capistrano command:

capistrano production deploy

They will then be prompted to enter their username and password for the production server (capistrano uses local username by default, but I added the prompt for my own preference). After entering the proper credentials, capistrano uses ssh to run git clone --mirror and mirror the repository to the production server. If it is already mirrored, it will try to update the repository. Finally, it will copy files from the master branch, update the current symlink, and restart the server.

NOTE: For the first deployment, you will have to manually copy the repository's linked_files (config/database.yml config/secrets.yml config/environment.rb config/environments/production.rb) into the capistrano shared directory.

It is important to understand the structure that capistrano imposes on the deployment path. A sample is listed below. You can also learn more about this here.

├── current -> (symlink to one of the releases dirs)
├── releases
│   └── ...
├── repo
├── revisions.log
└── shared

So, why is any of this relevant? Well, by the process that capistrano by default, it will generate a tarball from the git repository using the git archive command, then untar the files into a timestamped folder in the releases directory, which is then symlinked to the current directory. However, none of this process involves recloning the git repository itself, and the archived files will only contain a git work tree and not another git directory (see below for more details about these terms).

In summary: you cannot run git status or other git commands easily within the current directory. And this is annoying.

To solve this problem, we have to add a few extra commands to our capistrano scripts. The main point is to "initialize" our current directory as a git repository. But this this isn't a new repository, we instead have to just tell it where it can find the proper git directory. This can be accomplished by running the following command within the current (working tree) directory:

git init --separate-git-dir=/path/to/cap-deploy-dir/repo/

This alone will allow us to run git commands from the current directory without having to specify extra flags every time to point to a different git directory. However, this will cause problems when trying to deploy to the server after the first time. In summary, this is because the configuration file in repo/config needs to be reset, and this can be accomplished by running the following in the repo directory:

git config --unset core.logallrefupdates
git config --unset core.worktree
git config core.bare true

This, unfortunately, will introduce a few quirks to the deployed directory. For the first time the code is deployed, the git status will display everything as staged to be deleted and all files as untracked. This can be fixed simply by running git add -A. It is also important to note that the git directory is not in the location that git uses by default, but this should be very clear to anyone who actually read all of this documentation.

To understand why this is necessary, some esoteric knowledge of git will come in handy. In capistrano's directory structure, the repo directory is where the unreadable git repository "data" lives. However, this directory does not contain the work tree (the directory that contains all of the actual project's files that make up the repository). Rather, this is the bare git directory (which normally is the hidden .git directory that is created when you clone a git repository). You can learn more about the vocabulary and environment variables in the git docs. There is also a nice visual of the "three states" that git files can be in locally, located here.