Homeless Children's Playtime Project
The mission of the Homeless Children's Playtime Project is to nurture healthy child development and reduce the effects of trauma among children living in temporary housing programs in Washington, DC.
Playtime seeks to create a city that provides every opportunity for children in families experiencing homelessness to succeed by ensuring consistent opportunities to play and learn, offering support services for families, and advocating for affordable housing and safe shelter.
About This App
The goal of this application is to allow supporters to donate toys and other items that help advance the work of Playtime Project's work in family shelters throughout DC. This application will allow donors to view the organization's Amazon wish lists, add items, track contributions, and aid staff in following up with donors.
About Ruby for Good
This project was born at Ruby for Good 2017.
Ruby for Good is an annual event based out of the DC-metro area where Ruby programmers from all over the globe get together for a long weekend to build projects that help our communities. For more information about Ruby for Good, visit the website or check out the other projects.
Join the Team
This application is a work in progress, and we encourage you to jump in!
To get started, follow our Getting Started guide to set up your computer, then check out our GitHub Issues to see what issues are currently in the pipeline. You can find our contribution guidelines in CONTRIBUTING. Get in touch with @micahbales for more details.
- Getting Started
By the end of this section, you should have the project and dependencies installed on your local system. For information on how to contribute, see Contributing.
- Ruby 2.4.1
- Rails 5.1
- Postgres >=9.1
You will also need Git, Ruby, Rails, and PostgreSQL. If you have Git and Postgres in some version or another you're probably set. But:
If you have a fresh Mac OS X machine, just follow these directions (if you're running a different OS version, switch to the correct version). These instructions include PostgreSQL.
Otherwise, Google for instructions for your OS of choice. Let us know if you get stuck!
Navigate to your desired working directory. Then from a command prompt:
$ git clone http://github.com/rubyforgood/playtime $ cd playtime $ bin/setup $ rails server
Then navigate to
http://localhost:3000 in your browser to view the app.
Getting Amazon OAuth Working Locally (Optional)
By the end of this section, you should be able to create an account/login to the app on your local machine.
This application uses Amazon OAuth for authentication. In order to create an account or login locally:
Follow these instructions to create an Amazon app. This is required for logging in/creating
If you don't have a
.envfile, copy the sample .env configuration:
# from the root project directory $ cp .env.sample .env
.env, fill in the id and secret keys for your Amazon app (Client ID and Client Secret on your Amazon App Console):
# .env AMAZON_CLIENT_ID="your client id" AMAZON_CLIENT_SECRET="your client secret" # ...
(Optional: Setting up your admin account) If you want your development account to be an admin, you can set that up by setting the admin environment variables:
# .env ADMIN_NAME="your name" ADMIN_AMAZON_EMAIL="the email you use for your amazon.com account"
rake users:initialize_admin. If you've already logged in, your account will be promoted to an admin. If you haven't, your new admin account will be created.
You can also change your user role by using
Start your Rails app with
rails server. You're ready to OAuth!
Getting Amazon Product Advertising API Working Locally
By the end of this section, you should be able to search Amazon products and add items to wishlists on your local machine (when your logged-in user is an admin or site manager).
This step is only required for site managers and admins searching/adding Amazon products. If your issue doesn't involve working with the Amazon Product API, you'll be fine without this step.
Admins and site managers can add new items to their wishlists by searching
the Amazon Product API. To get this search working locally, you'll need to
create a few Amazon accounts and add some more
First, register for an Amazon Associate account. Order matters here; be sure to do this before step #2!
Last, using the AWS credentials you downloaded (or viewed) in step #2, update your
# .env # ... AWS_ACCESS_KEY="your access key id goes here" AWS_SECRET_KEY="your secret access key goes here" AWS_ASSOCIATES_TAG="playtim009-20" # <- same for everyone
You'll only be able to download your secret key once, so make sure you put it in a safe place! Otherwise, you'll have to log in and regenerate your credentials.
Restart the server and you're done–you can search to your heart's content!
All specs must pass in order for a PR to be accepted. Specs and associated checks can be run with
Specs can be found in the
spec folder, and they follow the typical
directory structure. Some notes:
We're using FactoryBot to generate objects, and those files can be found in
Support files, including helper methods, gem initialization/configuration, etc. can be found in
While we use factories instead of fixtures to generate objects, static test files (ex. images or API responses) can be found in
External HTTP requests can be mocked with WebMock. To mark a spec as containing an external request, use the
We manage environment variables using
.env. This file should be created when
bin/setup, but you can always copy
.env.sample if it gets deleted.
For changes to
.env to take effect, you'll need to restart your server.
.env should never be checked into source control!
# Annotated .env example # The client id and secret are used for OAuth (creating accounts/logging in). # Setup instructions can be found above in "Getting Started with OAuth" AMAZON_CLIENT_ID="your amazon client id" AMAZON_CLIENT_SECRET="your amazon client secret key" # The access key and secret are used for interacting with the Amazon Product # API. Setup instructions can be found above in "Getting Amazon Product # Advertisement API Working Locally" AWS_ACCESS_KEY="your aws access key" AWS_SECRET_KEY="your aws secret key" # If you want to force Amazon login instead of developer in development environment # set it to true. FORCE_AMAZON_LOGIN=false # Code for generating affiliate links from search (same for everyone) AWS_ASSOCIATES_TAG="playtim009-20" # Default rack env and port (same for everyone) RACK_ENV="development" PORT=3000 # Admin account details for `rake users:initialize_admin` ADMIN_NAME="your name" ADMIN_EMAIL="the email you use for your amazon.com account"