Running via Docker for Development

The Dockerfile and docker-compose.development.yml provide a full Identity development environment within Docker.

Pre-requisites

• Install Docker
• Install make if you don’t have it already - Linux & OSX users usually have this installed by default (optional, but recommended)

Download the code

• Checkout the project from git git clone git@github.com:the-open/identity.git
• Switch into the project folder cd identity

Setup the app & environment

BEFORE PROCEEDING: The next steps will overwrite existing .env files you have, so back these up if necessary.

Using make (recommended)

NOTE FOR OSX USERS: The makefile doesn’t currently work if you have the default OSX version of sed installed - you can either install GNU sed, or follow the instructions for setting up the app without the makefile (see below).

The quickest way to do this is with the provided Makefile: make completely-clean-build

This will setup all the required .env files for you, download & build all docker images, and bootstrap the dockerised database with necessary data.

Without using make

If you don’t have make installed, or for some reason prefer not to use it, you can setup the app more manually:

• Copy the env files:
  • cp .env.development.sample .env.development
  • cp .env.test.sample .env.test
  • cp gems/mailer/spec/dummy/.env.test.sample gems/mailer/spec/dummy/.env.test

• Edit each of the env files with the appropriate values for docker. As a minimum you will need to set DATABASE_URL and REDIS_URL appropriately in each. Comments directly in the env files show the required values, but you can also refer to the Makefile itself to confirm all the environment variables it sets and what values it uses.

• Run docker-compose -f docker-compose.dev.yml build to build all containers

• Run the following commands to bootstrap the application - setup the database & seed it with data:
  • docker-compose -f docker-compose.dev.yml run web bundle exec rails bootstrap
  • docker-compose -f docker-compose.dev.yml run -e RAILS_ENV=test web rails bootstrap

Running the app

Run attached

‘Attached’ means the docker containers will run in the foreground of your terminal, and logs from all docker containers will output to your terminal. This includes the webapp, sidekiq, the postgres database, etc.

• Run make start-everything-attached (or docker-compose -f docker-compose.dev.yml up if not using make) to launch services in attached mode, so you can see logs from all services. You can run other docker-compose commands against the running services in separate terminal sessions.

• The app should be available at http://localhost:3000

• Hit CTRL+C to stop the app

Run detatched

‘Detatched’ means the docker containers will run in the background, and your terminal will return once they have started up. You won’t see any logs unless you ‘attach’ to the logger later.

• Run make start-everything (or docker-compose -f docker-compose.dev.yml up --detach if not using make) to launch services in detatched mode.

• Run docker logs -t -f to attach your terminal to the logs and follow for new log lines.

• Run make down-containers (or docker-compose down if not using make) to stop all containers from running.

Running tests

• Run all tests with make run-all-tests

• Run Identity Core tests with make run-core-tests (or docker-compose -f docker-compose.dev.yml run web bundle exec rspec if not using make)

• Run Identity Mailer tests with make run-mailer-tests (or docker-compose -f docker-compose.dev.yml run --workdir="/app/gems/mailer" web bundle exec rspec if not using make)

Running linters

• Run rubocop with make run-rubocop (or docker-compose -f docker-compose.dev.yml run web rubocop if not using make)

Running database migrations

• Start a shell session (make shell), and then run bundle exec rails db:migrate

Other Useful commands

• docker-compose -f docker-compose.dev.yml run web bundle exec rails db:reset to reset the data in the database

• docker-compose -f docker-compose.dev.yml restart web to restart the web service (e.g. after a change in .env.development)

• docker-compose -f docker-compose.dev.yml run web bash to start an interactive shell with the running web service

• docker-compose -f docker-compose.dev.yml run web rails console to run the rails console on the web service

• docker-compose -f docker-compose.dev.yml rm to remove created containers

Notes

• You can override the port the app us running on by running docker-compose with a PORT env variable: PORT=3001 docker-compose -f docker-compose.dev.yml up

• Many of the application commands above (such as bundle exec rspec or rubocop) can also be executed by creating a shell session on the web container with docker-compose -f docker-compose.dev.yml run web sh and then running the appropriate commands.

TODO

• Running Via Docker in Production