Docker

Docker is a container platform that makes it easier to start a development environment with all the required dependencies.

Dependencies

To start you only need to have git and docker installed. Everything else will be done via Docker itself.

1. Install Git
2. Install Docker

Note: If you do not install the Desktop version of Docker, such as with a Linux-based OS, make sure to also install Docker Compose.

Getting the code

Clone the repository.

Attention: For Windows you should set git parameter core.autocrlf to input, otherwise you will get \r\n linebreaks and it will break some scripts!

For security, you should modify the default database password before starting your local environment, unless you trust your firewall and everyone on your local network.

1. In config/docker/database.yml, change the default DB password ("change_me").
2. In docker-compose.yml, change the MySQL root password to the same value (also default "change_me").

Initializing Docker Compose

In the shell of your choice, navigate to the repository root and run the initialization script.

For Unix-like systems such as Linux or macOS:

./script/docker/init.sh

Or for Windows:

script\docker\init.cmd

This will pull and build all required Docker images, copy all the required configuration files, run the initialization tasks (setting up the database, indexing for search, etc.) and finally start the Rails application.

When the script has finished, you should be able to access your archive by visiting http://localhost:3000/ in the browser of your choice.

Troubleshooting

If you cannot access your archive there, you will likely end up needing to re-run the init script after fixing the issue--simply running docker-compose up -d web may appear to succeed while skipping critical steps.

If you're on Linux and the version of the archive that shows up on localhost seems to be missing a lot of the css, you may need to change the ownership of the files docker generated, as in the official Rails on Docker Compose example, and then re-run the init script. In particular it's the permissions of the files in public/system/skins/ that cause the css issue, but all files created by Docker are owned by root, and this can cause problems when trying to access them from within the container:

sudo chown -R $USER:$USER .

If you run into a cp: illegal option --b on macOS, try installing coreutils with Homebrew (brew install coreutils) and updating ./script/docker/init.sh with gcp instead of cp.

Starting the application

After the one-off initialization tasks have been run, on subsequent starts you can open your shell and use the following:

docker-compose up -d web

Then you will be able to access your archive by visiting http://localhost:3000/ in the browser of your choice.

You can start a Rails console in the development environment:

docker-compose exec web bundle exec rails c

Or get a shell inside the container and execute commands as you would normally:

docker-compose exec web bash

Refer to Development Data for creating admin and user accounts in your development environment.

Creating Elasticsearch indexes

To create your search indexes (and fill them with data), you'll need to start the background workers.

Running tests

In the commands below, note that the file paths, such as spec/my_model_spec.rb:10, are examples. You will have to put in the correct file path to the tests you would like to run. If you would like to run all of the tests, use spec for RSpec tests and features for Cucumber tests.

To run RSpec tests:

docker-compose run --rm test bundle exec rspec spec/my_model_spec.rb:10

To run Cucumber tests:

docker-compose run --rm test bundle exec cucumber features/my_archive_process.feature:10

Updating the application

If there have been changes to the Dockerfile setup (e.g. new gem updates), you'll need to rebuild the containers:

docker-compose up --build --force-recreate --no-deps -d web test

Debugging with pry

The following steps are a summary of https://medium.com/gogox-technology/debugging-rails-app-with-docker-compose-39a3767962f4.

1. Update docker-compose.yml to add 2 new lines:

  # within the services dict
  web:
    stdin_open: true # new
    tty: true # new
    # ... rest of the file ...

2. After those changes, start the application with docker compose up -d web. If you already started the app, make sure to bring it down and up again.
3. Once the container is running, find its id using docker container ls and plug it into docker attach <container_id>.
4. Add breakpoints with require 'pry'; binding.pry in the code. Once you hit the breakpoint, the terminal attached to the container will display a pry prompt ready for commands.