The Homeward Tails app is derived from the Baja Pet Rescue Dog Adoption Application created by @kasugaijin who wanted to give back to the grassroots organization from where he adopted his dog in Mexico by building them a web application. Homeward Tails is an application that makes it easy to connect shelters with people who are looking to adopt or foster pets.
Let's get your machine setup to start up the application!
git clone git@github.com:rubyforgood/homeward-tails.gitInstall a containerization app, such as Docker Desktop.
Navigate to the project directory and run:
docker-compose build to build the base image.
docker-compose up to start the containers. You can add the -d flag to run silently without logging.
docker-compose run --rm app bin/setup to set up and seed the database.
If you need to run migrations at all: docker-compose run --rm app bin/rails db:migrate
Visit localhost:3000 in your browser.
This application can be run locally while using a docker database. Review the docker compose file. You will need to start three databases:
docker compose up -d postgres
docker compose up -d cable
docker compose up -d queueYou may need to set the correct ports - review the environment variable instructions.
Example:
DATABASE_PORT: "54320"
CABLE_PORT: "54321"
QUEUE_PORT: "54322"You need to attach to an interactive shell on the app service docker attach pet-rescue-app-1
Place debugger in your code and hit it. You should be able to interact in the attached shell.
Installing PostgreSQL is required to run the application.
Instructions: [https://wiki.postgresql.org/wiki/Homebrew]
brew install postgresql@14To run postgresql as a service:
brew services start postgresql@14Setting up a PostgreSQL role is beyond the scope of this README. If you do need help, we recommend Setting up PostgreSQL from The Odin Project.
You must set the environment variables DATABASE_USERNAME and DATABASE_PASSWORD for a role running your PostgreSQL instance (this is not necessary if running via Docker compose). There are many tools to help manage environment variables:
This project also ships with figaro if you would like to use it to set these environment variables.
Figaro instructions for setting environment variables:
cp config/application.example.yml config/application.ymlcode config/application.ymlorvi config/application.ymlornano config.application.yml- Replace
REPLACE_MEwith your PostgreSQL role credentials
Run the setup script to prepare DB and assets
bin/setupTo run the app locally, use:
bin/devYou should see the seed organization by going to [http://localhost:3000/alta/]
All users are scoped to an organization. Hence, you must login via the correct login portal per organization.
You can use the following login credentials to login to [http://localhost:3000/alta]:
Use the following login Adopter
- email:
adopter1@alta.com - password:
123456
Staff
- email:
staff@alta.com - password:
123456
Go to http://localhost:3000/letters to view mail in development.
Run unit tests only
./bin/rails testRun system tests only (Headless)
./bin/rails test:systemRun system tests only (Not-Headless)
CI=false ./bin/rails test:systemNote: If system tests are failing for you, try prepending the command with APP_HOST=localhost. Your host might be misconfigured.
APP_HOST=localhost ./bin/rails test:systemRun ALL tests:
./bin/rails test:allWe use standard for linting. It provides a command for auto-fixing errors:
rails standard:fixIf you find yourself writing a conditional checking the question, "Is the user allowed to view/do this?" that is an authorization concern. Homeward Tails utilizes the gem Action Policy as our authorization framework. If you are familiar with Pundit, you will see many similarities. If you want to learn more about authorization or have questions about how Action Policy works, their documentation is excellent. If you would like a quick onboarding to how Action Policy is used in Homeward Tails, see our wiki page on authorization.
This google sheets contains a list of tools, their purposes, and who has access to grant permissions.
Please feel free to contribute! Priority will be given to pull requests that address outstanding issues and have appropriate test coverage. Focus on issues tagged with the next milestone for higher priority.
To contribute:
-
Only work on one issue at a time
-
Identify an unassigned issue
-
Request assignment of an issue by adding a comment on the issue
-
Fork the repo if you're not yet a contributor
-
Ensure that the application runs locally in your browser. When you run the test suite locally, it should pass
-
Create a new branch for the issue using the format
XXX-brief-description-of-feature, whereXXXis the issue number -
Make code changes related to the assigned issue
-
Commit locally using descriptive messages that indicate the affected parts of the application
-
Add tests related to your work(most of the time)
-
Ensure all tests pass successfully; if any fail, fix the issues causing the failures
-
Make a final commit if any code changes are required
-
Push up the branch
-
Create a pull request and fill out the description fields
-
We like to make sure people are recognized for their contributions, so please attribute others by commenting on a pull request with
@all-contributors please add @<username> for <contributions>. please add @<username> for <contributions>.Replace
<contributions>withcodeorreview
Homeward Tails is one of many projects initiated and run by Ruby for Good. You can find out more about Ruby for Good at [https://rubyforgood.org]
While vision is the destination, and strategy is how we'll get there, core values are what we'll use to handle times of change or uncertainty (both of which are expected, guaranteed to happen, and positive signs of growth!).
We are committed to promoting positive culture and outcomes for all, from coders and maintainers and leads to pet rescue and adoption administrators -- and animals everywhere.
We will lean on the following as guiding principles when interacting with others -- stakeholders, as well as current and future maintainers, leads, and collaborators -- and we ask that anyone engaging with this project in any capacity to do the same. Know that we do want to know how and when (not if) we can improve upon these values and/or the way in which we live by and act in accordance with them, so please comment here and in PRs when you have ideas.
Here are our core values defined by early contributors and leads:
Write maintainable code that is accessible and enjoyable (for beginners and seasoned coders alike), supports and encourages contributors and their contributions, and ensures long-term sustainability of this project and the efforts it supports.
Prioritize clear communication, embrace diverse viewpoints, and always engage feedback -- all with a commitment to timely responses and ongoing improvement for all. Rescue and adoption partner perspectives will be prioritized over abstracted conceptualization of their needs.
Build upon stakeholder partnerships to foster and encourage their active involvement, focusing constructive discussion and dispute resolution on the practical impact of our collective work.
These are some resources that may help with contributing to the codebase
- Figma site design
- Model association diagram: Import the schema.rb file into [https://dbdiagram.io/d] to get the latest version of the diagram
- Turbo Rails Tutorial
- Geek UI Documentation
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!