Interacting with the stack

Since we use a containerized infrastructure, interacting with various parts of the stack (like running database migrations, or opening a database shell) requires that we "step into" the containers in order to execute commands on them.

This document's goal is to list out common commands that can be used to perform operations within the containers in our stack.

All of the following commands should be run in the root directory of the provisioning repository.

Running our stack

Docker gives us two options for running our stack: either in the foreground or as a background daemon.

The difference between these two options is negligible.

Running the stack in the foreground

Command: docker-compose up --build

Starting the stack in the foreground shows all output from all containers in the terminal window in which it is executed. Stopping the stack can be done by issuing a Ctrl-C.

Note: The --build flag ensures that we rebuild any custom containers whenever the stack is started. This is optional unless any Dockerfiles have been changed, so it is recommended that you use the flag anyways.

Running the stack in the background (as a daemon)

Command: docker-compose up -d --build

Runs the stack in a background daemon, with no output visible to the terminal. See below for how to access the logs on demand.

Viewing logs for the stack (running as daemon)

Command: docker-compose logs -f

Shows and follows the logs interactively for all running containers in the stack.

Stopping the stack

Command: docker-compose down

Stops any containers in the stack that are running in the background

Running commands

In order to run a command in a container, Docker gives us two options:

• docker-compose exec <service> <command> executes a command in an already-running container on the stack, which is named . This requires the stack to be running. Useful for operations that depend on the state of the running container. In most cases, this is the safer option to use.
• docker-compose run <service> <command> executes a command in a one-off container. This means that if the service is backend, a new backend container will be built and run just to run the command. Afterwards, the container is destroyed.

In most cases, you'll want to use docker-compose exec to run your commands to ensure that they are running on the active containers for the stack.

Running a shell

Command: docker-compose exec <service> bash

In some cases, you may want to run a shell in a container so that you don't have to type docker-compose exec/run before each command. This command runs a shell in the specified service.

Database operations

Running a database shell

Command: docker-compose exec db psql -U swapr -d swapr_dev

Opens a shell to the PostgreSQL server in the db container. Useful for running custom SQL on the database.

Running database migrations

Command: docker-compose run backend sequelize db:migrate

Runs migrations on the database, ensuring that the schema is up to date with the latest version. If you encounter any database errors that are unexpected, it may be wise to run this command before troubleshooting to make sure that the error wasn't caused by a mismatch between the schema and models.

Test suite

Running the test suite

Command: docker-compose -f docker-compose.test.yaml run test

Runs the test suite in a one-off container, making sure the database is in a clean state.