Skip to content

Latest commit

 

History

History
164 lines (132 loc) · 6.91 KB

DOCKER.md

File metadata and controls

164 lines (132 loc) · 6.91 KB
Raw

Development setup using Docker

After you install Docker, please follow either the automatic setup or the manual setup. If you are new to Docker, it is recommended that you follow the manual setup.

Installing Docker

Install Docker Community Edition if it is not already installed.

Automatic Setup

The automatic setup explained here relies on Bash scripts in the docker directory to execute the most basic and frequent tasks in Docker. There is substantially less typing to do under the automatic setup than under the manual setup.

Initial setup

  1. Clone the respository to your local machine: git clone https://github.com/rubyforgood/casa.git or create a fork in GitHub if you don't have permission to commit directly to this repo.
  2. Change into the application directory: cd casa
  3. Run docker/build to build the app, seed the database, run the local web server (in a detached state), run the test suite, and log the screen outputs of these processes in the log directory. The web application will be available at http://localhost:3000.
  4. Run docker/test to run the test suite and log the screen output in the log directory.
  5. If you reboot the machine, restart Docker, or stop any services, the tests and many other functions will not work. Please run docker/server to restart the app and allow the tests and other functions to work.

Other Automated Scripts

  • Run docker/seed to reseed the database.
  • Run docker/server to restart the local web server (in a detached state).
  • Run docker/nukec to delete all of the Docker containers.
  • Run docker/nuke to delete all Docker containers, Docker networks, and Docker images.
  • Run docker/console to start the Rails Console.
  • Run docker/sandbox to start the Rails Sandbox.
  • Run docker/brakeman to run the Brakeman security tool, which checks for security vulnerabilities.
  • Use the docker/run script to run any command within the Rails Docker container. For example, entering docker/run cat /etc/os-release executes the command cat /etc/os-release within the Rails Docker container.

Manual Setup

The manual setup instructions walk you through building the images and starting the containers using Docker Compose commands directly. This setup method is particularly recommended if you are new to Docker.

Initial setup

The following commands should just be run for the initial setup only. Rebuilding the docker images is only necessary when upgrading, if there are changes to the Dockerfile, or if gems have been added or updated.

  1. Clone the respository to your local machine: git clone https://github.com/rubyforgood/casa.git or create a fork in GitHub if you don't have permission to commit directly to this repo.
  2. Change into the application directory: cd casa
  3. Run docker-compose build to build images for all services.
  4. Run docker-compose run --rm web rails db:reset to create the dev and test databases, load the schema, and run the seeds file.
  5. Run docker-compose up -d to start all the remaining services.
  6. Run docker-compose ps to view status of the containers. All should have state "Up". Check the logs if there are any containers that did not start.
  7. The web application will be available at http://localhost:3000

For ongoing development:

  • Run docker-compose up -d to start all services.
  • Run docker-compose ps to view status of containers.
  • Run docker-compose stop to stop all services.
  • Run docker-compose restart web to restart the web server.
  • Run docker-compose rm <service> to remove a stopped container.
  • Run docker-compose rm -f <service> to force remove a stopped container.
  • Run docker-compose up -d --force-recreate to start services with new containers.
  • Run docker-compose build web to build a new image for the web service. After re-building an image, run docker-compose up -d --force-recreate web to start a container running the new image.
  • Run docker-compose down -v to stop and remove all containers, as well as volumes and networks. This command is helpful if you want to start with a clean slate. However, it will completely remove the database and you will need to go through the database setup steps again above.

Running commands

In order to run rake tasks, rails generators, bundle commands, etc., they need to be run inside the container:

$ docker-compose exec web rails db:migrate

If you do not have the web container running, you can run a command in a one-off container:

$ docker-compose run --rm web bundle install

However, when using a one-off container, make sure the image is up-to-date by running docker-compose build web first. If you have been making gem updates to your container without rebuilding the image, then the one-off container will be out of date.

Running webpack dev server

To speed compiling of assets, run the webpack dev server in a separate terminal window:

$ docker-compose exec web bin/webpack-dev-server

Viewing logs

To view the logs, run:

$ docker-compose logs -f <service>

For example:

$ docker-compose logs -f web

Accessing services

Postgres database
$ docker-compose exec database psql -h database -Upostgres casa_development
Rails console
$ docker-compose exec web rails c

Testing Suite

Run the testing suite from within the container:

$ docker-compose exec web rspec spec -fd

For a shorter screen output from running the testing suite from within the container:

$ docker-compose exec web rspec spec

System tests will generate a screenshot upon failure. The screenshots can be found in the local tmp/screenshots directory which maps to the /usr/src/app/tmp/screenshots directory inside the container.

Watching tests run

You can view the tests in real time by using a VNC client and temporarily switching to the selenium_chrome_in_container driver set in spec/spec_helper.rb. For example, you can change this:

    if ENV["DOCKER"]
      driven_by :selenium_chrome_headless_in_container

to this:

    if ENV["DOCKER"]
      # driven_by :selenium_chrome_headless_in_container
 `    driven_by :selenium_chrome_in_container

Mac OS comes with a built-in screen sharing application, "Screen Sharing". On Ubuntu-based Linux, the VNC client application "Vinagre" (aka "Remote Desktop Viewer") is commonly used, and can be installed with sudo apt install vinagre.

You can open the VNC client application and configure it directly, but in both operating systems it's probably easier to click on vnc://localhost:5900 (or paste that into your browser's address bar) and let the browser launch the VNC client with the appropriate parameters for you.

The VNC password is secret.

Run the spec(s) from the command line and you can see the test running in the browser through the VNC client.