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, docker, and docker compose installed. Everything else will be done via Docker itself.

1. Install Git
2. Install Docker
3. Install Docker Compose

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

Fork the repository and then clone it and set up the original repository as a remote:

git clone https://github.com/YOURGITHUB/otwarchive.git
git remote add upstream https://github.com/otwcode/otwarchive.git

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.

Note that if you are using Windows, make sure you check out the repository with LF endings, not CRLF. CRLF endings will cause the initialization script to fail.

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.

An error like Error starting userland proxy: Bind for 0.0.0.0:3306 failed: port is already allocated, on Linux, indicates that another service is running using a default port for one of the necessary docker containers. The first-line fix is to try docker container ls and, if one of the listed containers is using the same port (0.0.0.0:3306, here), shut that down with docker stop. If no containers appear, it's a different service, often mysql or redis. Investigating this should use sudo netstat -p -nlp and look for the port number (3306), but BE CAREFUL - make sure you know what the process is before shutting it down, as killing arbitrary processes (with kill) can damage your system.

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 .

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/models/unsorted_tag_spec.rb, 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:

# To run the specific test file spec/models/unsorted_tag_spec.rb
docker compose run --rm test bundle exec rspec spec/models/unsorted_tag_spec.rb

To run Cucumber tests:

# To run the specific test file features/tag_sets/tag_set.feature
docker compose run --rm test bundle exec cucumber features/tag_sets/tag_set.feature

Updating the application

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

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

If there have been changes that added database migrations, you need to the run the migrations for the dev db:

docker compose run --rm web bundle exec rails db:migrate

And the test db:

docker compose run --rm test bundle exec rails db:migrate

Debugging with pry

1. If you haven't yet, start the application with docker compose up -d web.
2. Once the container is running, attach to it with docker compose attach web.
3. 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.