↩ Back to README
This is a Ruby on Rails 6.0 application with Vue + Webpack included.
To get started developing on your machine, you'll need the following tools installed:
- ruby 2.7+, bundler 2+
- node 14+, yarn 1.16+
This project uses webpacker to bundle front end assets, including:
There are two ways to run services in your development environment:
- Use Docker.
- Install local services on your development host:
The easiest way to manage different installations of Ruby (we think) is with rbenv.
- Follow the installation instructions on the rbenv repo
- Restart your terminal, then, in the root directory of the repository:
rbenv install gem install bundler bundle install
rbenv will handle installing Ruby and switching to it for you when you enter the repo (so no need to worry about your other Ruby installs!).
If you run into a problem where your bundle install says you're on an older version of bundler than what's in the lockfile, run gem update --system to update RubyGems, then:
gem install bundler:[latest-version-you-want], e.g. gem install bundler:2.1.2
Depending on your system, you might have trouble building the pg gem, probably due to a missing libpq-fe.h. To get the necessary libraries installed:
- For Mac (Homebrew):
brew install postgresql - Debian/Ubuntu:
sudo apt-get install libpq-dev - On Enterprise Linux (CentOS/RHEL/Fedora/Amazon Linux/Sci Linux):
yum install postgresql-devel
The easiest way to manage different installations with node.js is with nvm. After following the installation instructions, type nvm install to install and run the right version of node.js.
You'll also need Yarn, a package manager for node.js. To install that:
- For Mac (Homebrew):
brew install yarn - Debian/Ubuntu:
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn
- On Enterprise Linux (CentOS/RHEL/Fedora/Amazon Linux/Sci Linux):
curl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.repo
sudo yum install yarn
If you would like to use asdf-vm to manage versions of ruby, yarn and nodejs, simply run asdf install. This will automatically install the necessary dependencies for you.
If you haven't setup asdf before, you will first need to follow the installation instructions, then install plugins:
asdf plugin add ruby
asdf plugin add yarn
asdf plugin add nodejs
bash -c '${ASDF_DATA_DIR:=$HOME/.asdf}/plugins/nodejs/bin/import-release-team-keyring'
If you get an error about needing GnuPG, you will first have to install gnupg. Eg, on OS X, brew install gpg.
We recommend:
- The Postgres.app, or
- Installing with
homebrew.
- Use your favorite package manager, eg:
sudo apt-get update sudo apt-get install postgresql postgresql-contrib libpq-dev - Create a user for use with the mutual-aid app (or for other databases as well, if you like)
# Choose a username and replace <username> below. # This will prompt for a password, make sure to remember it for later sudo -u postgres createuser <username> --pwprompt --createdb --no-superuser --no-createrole - Give the app knowledge of these creds:
- Create or edit a
.env.localfile at the root of the project (alongside.env) - Set the following values to match the username and password from above.
POSTGRES_USER=username POSTGRES_PASSWORD="password"- Note: the "quotes" around password are required if it contains spaces
- Create or edit a
- Test the setup by ensuring the following runs without error:
bin/rake db:setup
Mailcatcher cannot be bundled, so has to be installed globally:
$ gem install mailcatcher
Start the mail server with:
$ mailcatcher
And go to http://localhost:1080/
By default, some user actions, such as registration, will fail if mailcatcher is not running. This is an intentional choice to keep development as close to production as possible. If you prefer to fire up mailcatcher only when you're working on emails, you can override this behavior via environment variables.
We've used the dotenv gem to reference .env files in the main project level of the repo. Check out their README!
You can override any values in .env by introducing an .env.local file or more targetted files per environment, e.g. .env.development.local, .env.test.local.
All of these are already ignored in our repository so its safe to put credentials there (you can also use chown/chmod to further secure them).
Remember to configure environment variables in Heroku or wherever you deploy!
Only the development environment uses .env files.
First, make sure local services or docker are running.
Before starting the app for the first time, you'll want to:
$ bundle && yarn
$ bin/rake db:rebuild_and_seed_dev
Which will seed the development db with necessary accounts and some test data.
In development, running the app involves firing up several processes, which are defined in Procfile.dev. You can manage these processes yourself, by invoking each of them in separate terminals (or backgrounding them). For example, run
bin/rails serverin one terminal andbin/webpack-dev-serverin another.- Note that
mailcatcheris only necessary for some features and can also be skipped (see .env).
Alternatively, you can use a process manager such as foreman, invoker, node-foreman, etc., eg one of:
$ foreman start -f Procfile.dev
$ invoker start Procfile.dev
$ nf start -f Procfile.dev
You should now be able to see the app running at http://localhost:3000 (or whichever port the rails server is running on).
See doc/testing.md.
Ruby 2.7 deprecated some commonly used syntax so our codebase currently spits out a lot of warnings.
It will take some time for all our gems to get caught up, so in the meantime you might consider turning off deprecation warnings. There are several ways to do this.
An alternative to the methods listed in the artice is to create an alias alias nodep='export RUBYOPT="-W:no-deprecated"', giving
you the flexibility to toggle warnings in each terminal session as appropriate.
The Rails and webpack processes can be launched with Heroku, if you choose to go that route. You can install Heroku Local using these instructions.
(If you've done this, please submit a PR so we can include instructions here!)
The application includes a pre-configured docker-compose environment for development. This environment includes descriptors for the application and its supporting services.
To get started using the application with docker,
- Install Docker
- Install docker-compose
- Clone the repository, and open the repository folder in your favorite command line or terminal application.
We provide helpful shorthand, binstubs to get started using and interacting with the local Docker development environment:
bin/dev/bootstrap
Tears down any exiting images, containers, networks, etc. and sets everything up from scratch. This also seeds the development database. You can create a default admin account by setting SYSTEM_EMAIL and SYSTEM_PASSWORD values in <project-root>/.env.local:
SYSTEM_EMAIL=admin@mutualaid.localhost
SYSTEM_PASSWORD=mutualaid
then run the bootstrapping process.
BEWARE This script is intended to be a quick way to start from nothing and get a working instance of the application - suitable for development - up and running. It is also appropriate if you should find yourself at a total loss and want to start over with your development environment. This destroys the volumes for the various containers - IE the data on the databases, gem caches, yarn caches will be erased. Additionally, reinstalling gems and yarn dependencies can take several minutes.
bin/dev/serve
Starts the web application container and its supporting services - RDBMS, mailcatcher, etc.
Analogous to: bin/rails server
The application should be available at https://localhost:3000. You can sign in using the email and password you provided in the when you ran bin/dev/bootstrap. This docker compose also setups an a mailcatcher server, which you can access at localhost:1080. All emails will be delivered to mailcatcher, which should allow you to setup user accounts.
Additionally, if you want to keep the logs from each of the services separate, bin/dev/serve also takes an optional service name - or list of service names - to start in a single session. For example you might want to separate the email, and webpacker logs when interacting with a debugger in the app service to prevent losing the debugging context on log output from email or webpacker. In that case, you could open two separate terminals. In the first you would start the rails application:
bin/dev/serve app
and in the second terminal start email and webpacker
bin/dev/serve email webpacker
bin/dev/shell
Starts a shell inside the application container and establishes a TTY connection to it from the user's terminal.
Useful for things like starting a rails console, generating migrations, running one-off tests, exploring the container file system, etc. This will most likely be the tool you most-often reach for while developing with the local Docker development setup.
bin/dev/stop
Stops the web application container and its supporting services - RDBMS, mailcatcher, webpacker, etc.
bin/dev/test
Runs the entire application test suite inside the context of the app container
Analogous to: bin/test
bin/dev/clean
Destroys all docker resources for the application and services.
- Do not use this method in production! This is for testing & development only the configuration used with in this docker-compose file is highly insecure and should never be exposed to the public internet.
- All of the above binstubs are simply short hands for various
docker-composeincantations - there's nothing stopping you from usingdocker-composeto interact with the services listed in thedocker/development/docker-compose.yml. - The application will save its state between successive invocations of
bin/dev/start. This means that if you make changes to the database - for example by adding content or users - then those changes will persist the next time you start the application withbin/dev/start. You can wipe all the state of the application and all the services (including the postgres database) attached to it by runningbin/dev/cleanorbin/dev/bootstrapto start over from scratch. However, do be careful, because this will delete all the state saved in the application and database - and there is no way to retrieve it.
↩ Back to README