Docker & Docker Compose

Docker compose configuration is to load all the dependencies for the rhino project template. This includes the database, backend and frontend (vite) servers. The source code is mounted as a volume in the containers, so any changes you make to the code will be reflected in the running containers.

Prerequisites

Install Docker. If you have never used Docker before, please make sure to read the docs. It will help you understand how it works.

Clone the repo

git clone https://github.com/rhino-project/rhino-project-template.git`

Launch the docker containers

docker compose up

That will start all dependencies and the rails and frontend development server. The ui will be available at http://localhost:3000.

Running commands in the containers

Launch a bash shell in the rails container:

 docker compose exec backend bash

Running one-off commands in the containers

You can run one-off commands in the container without launching a shell. For example, to run a rails command:

docker compose run --rm backend [your_rails_or_rhino_command_here]

That will run the command by spawning a new backend container and removing it once the command returns. Make sure you use the --rm flag, otherwise you'll end up with a lot of stopped containers over time.

For example, to run a rails console, use docker compose run --rm backend rails console. To run a migration, use docker compose run --rm backend rails db:migrate.

tip

It may be a smart idea to creata an alias shortcut for docker-compose run --rm backend for better productivity.

Stopping dependencies

docker compose down

That will stop and remove all running containers.

Running dependencies separately

It is possible to run detached docker containers. This is particularly useful when the dependencies are unchanged but the rhino server configuration is updated. This way, you don't need to kill all dependencies to reboot the server. It is also useful when you just want to run the server but don't see the logs in your terminal. To do so, you need to run docker compose up with the names of the container dependencies as arguments, and the -d flag.

docker compose run -d db

This will run db separately in the background. If you now run docker compose up, it will use the background containers for db and only start the backend container in the foreground.

Troubleshooting

Docker compose configuration is provided for: db, backend and vite. All have beend configured with named volumes. Docker containers don't persist data, any data is deleted when the container is removed. The volumes make sure we don't lose any data and speed up starting the containers.

With docker compose, the volume names follow a convention: parent_folder_name_in_lower_case followed by the_volume_name_in_the_docker_compose_file. For rhino-project_template, the volume will be

• rhino_project_template_db_data postgres data
• rhino_project_template_gem_cache bundler cache
• rhino_project_template_node_cache node modules cache
• rhino_project_template_shared_data other shared data

Where possible the containers are isolated to a specific network to prevent conflicts with other services running on the host machine, rhino-project-template_development.

I cannot connect to the database

Make sure the db container is running.

docker container ls

CONTAINER ID   IMAGE                  COMMAND                  CREATED          STATUS          PORTS                    NAMES
5ac2b9717382   postgres:15.1-alpine   "docker-entrypoint.s…"   58 seconds ago   Up 54 seconds   0.0.0.0:5432->5432/tcp   db

If you don't see any of them on that list, use docker compose up -d db to start them in the background.

Database permission / migration issues

It is possible that your docker database is in an inconsistent state due to the change of environment variables or branch work.

1. Make sure you stop all containers

   docker compose down
2. List the available volumes

   docker volume ls | grep db_data
   It should return this:

   local     rhino_project_template_db_data
3. Delete the volume

   docker volume rm rhino_project_template_db_data
4. Start the database container again. It will automatically create a new volume.

   docker compose up -d db
   It should return something like this:

   [+] Running 3/3
   ✔ Network rhino_project_template_development  Created                0.1s
   ✔ Volume "rhino_project_template_db_data"     Created                0.0s
   ✔ Container db                            Started                0.7s
5. Setup the rhino database

   docker compose run --rm backend rails db:setup