Dev: Setup on Linux and OS X using Docker

This setup has been tested on Fedora 30.

In order to make it easier to get started and to troubleshoot environment issues, we provide a Dockerized development environment. This is the only supported development configuration; however, people who want to run the application locally can examine the Dockerfiles to determine what dependencies they need to install. It is also possible to use Docker for Postgres and Elasticsearch, but not for application development; this is, again, not documented below.

Installing dependencies

Docker

The following diagram shows the block layout how the docker container is connected to the local environment and to GitHub. Follow the Docker Engine community edition instructions for your operating system.

On Linux, in order to interact with Docker without using sudo, you will need to add yourself to the docker group, then log out and log back in: sudo usermod --append --groups docker <your user name>

Docker-compose

Follow the docker-compose installation instructions.

Initialization

The development and test databases need to be initialized. The development database will be pre-configured with an admin user (see below, in "Development," for the default password).

Open terminal and go to the folder where the safecastapi files (downloaded from GitHub) are located.

Run bin/initialize_databases.bash once to take care of this step.

You may get the error message ERROR: Couldn't find env file: /home/username/safecastapi/aws-cli.env.

To solve this, you can generate this file with aws-vault by running $ aws-vault exec safecast --no-session -- env | grep --color=no '^AWS_' > aws-cli.env.

If you do not have the AWS login credentials, the command will fail with the error message aws-vault: error: exec: Error getting temporary credentials: profile safecast: credentials missing.

It will anyway create an empty aws-cli.env file that allows you to run bin/initialize_databases.bash without any errors and get the API app up and running.

Development

Some shortcut scripts have been written to ease development.

• disable or stop postgressql server if you have it running locally. Docker can not start it's posgressql server if one is already running locally.
• To run the development server: bin/run_dev_server.bash
• To run the full test suite: bin/run_tests.bash
• To rebuild dependencies: docker-compose build app. Using bundler install directly inside a container instance will not create persistent changes.
• To connect to the running Postgres instance, either:
  • docker-compose exec postgresql psql to directly run the psql command inside the postgresql container
  • Run psql or your client of choice as you would normally, on your host machine: psql -h localhost -U safecast safecast_development
• To start the development container and open a shell inside it, so that you can run any command: bin/run_shell.bash
  • To run the development server inside the shell, run docker_bin/run_dev_server.bash
  • To run a single test inside the shell, run docker_bin/run_test.bash <test identifier>
  • To run all tests inside the shell, run docker_bin/run_test.bash spec
  • To run rubocop: bundle exec rubocop
• You can also use docker exec to run additional commands in another shell session.
  • docker exec -i <Container ID> bundle exec rails server -b 0.0.0.0
  • docker exec -i <Container ID> bundle exec rspec spec/models/user_spec.rb

When the development server is running, you can connect to http://localhost:3000 and log in with username [email protected] and password 111111.

To log in as a non-moderator, log in with username [email protected] or [email protected] and password 111111

There appears to be an issue with Docker and terminal history behavior that comes up from time to time; a quick fix is to resize the terminal window, or to follow one of the suggestions in that issue's thread.

Ports

The docker-compose file exposes well-known ports on your host to make access easier:

• 3000 for the Web server
• 9200 for the Elasticsearch server
• 5432 for the Postgres server

In some cases, these may conflict with servers already running on your host. You can override the ports by exporting the following environment variables:

• SC_API_WEB_PORT
• SC_API_ELASTIC_PORT
• SC_API_POSTGRES_PORT

Mac variant setup

This is the setup that Mat uses. Keeping ruby & the psql client local to the OS avoids the need to docker exec for basic script testing. It also makes it easy to attach a debugger to the local ruby runtime.

Installing Ruby

rbenv is recommended to get a specific ruby version.

Once it's set up you can install the required ruby version by running:

rbenv install $(cat .ruby-version)

Then rbenv should automatically switch to the proper version when you cd into the project directory.

NOTE: If this is the first time you're installing ruby and related gems, you may also need to run this to install the xcode command line tools. These will be used to compile some gems which include native extensions.

xcode-select --install

Installing PostgreSQL client

Download the Postgres.app and move it to the Applications folder. The Postgres app comes preinstalled with PostGIS.

You'll want to add psql to your path. Add something like this to your shell:

export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:${PATH}"