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 `Dockerfile`s 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.
![Dev Docker setup](https://github.com/Safecast/safecastapi/blob/device-stories-rob/Dev%20safecast%20docker%20setup.svg)
Follow the [Docker Engine community edition instructions for your operating system](https://docs.docker.com/install/).

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](https://docs.docker.com/compose/).

## 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](http://localhost:3000) and log in with username `admin@safecast.org` and password `111111`.

To log in as a non-moderator, log in with username `user1@safecast.org` or `user2@safecast.org` and password `111111`

There appears to be an [issue with Docker and terminal history behavior](https://github.com/moby/moby/issues/33794) 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](https://github.com/rbenv/rbenv) is recommended to get a specific ruby version.

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

```sh
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](https://postgresapp.com/) 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}"
```

Draft: homebrew version

```
brew install postgresql@17
```