Skip to content

Commit

Permalink
Merge pull request #106 from epimorphics/spike/readme-updates
Browse files Browse the repository at this point in the history 
Spike/readme updates
  • Loading branch information
@bogdanadrianmarc
bogdanadrianmarc authored Oct 6, 2023
2 parents 0a8651f + 2b8a4fc commit 3ee278a
Showing 1 changed file with 105 additions and 108 deletions.
213 changes: 105 additions & 108 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,107 +10,11 @@ our report generator API. This batch job will either return with the report
download link, if a report with those options has already been generated and
cached, or a queue position as the job moves up the batch queue.

## Running this service
Please see the other repositories in the [HM Land Registry Open
Data](https://github.com/epimorphics/hmlr-linked-data/) project for more
details.

This application can be run stand-alone as a rails server in `development` mode.
However, when deployed, applications will run behind a reverse proxy.

This enables request to be routed to the appropriate application base on the
request path. In order to simplifiy the proxy configuration we retain the
original path where possible.

For information on how to running a proxy to mimic production and run multple
services together read through the information in our
[simple-web-proxy](https://github.com/epimorphics/simple-web-proxy/edit/main/README.md)
repository.

If running more than one application locally ensure that each is listerning on a
separate port and separate path. In the case of running local docker images, the
required configuration is captured in the `Makefile` and an image can be run by
using

### Development and Production mode

Applications running in `development` mode default to *not* use a sub-directory
to aid stand-alone development.

Applications running in `production` mode *do* use a sub-directory i.e.
`/app/standard-reports`.

In each case the is achieved by setting `config.relative_url_root` property to
this sub-directory within the file
`config/environments/(development|production).rb`.

If need be, `config.relative_url_root` may by overridden by means of the
`RAILS_RELATIVE_URL_ROOT` environment variable, althought this could also
require rebuilding the assets or docker image.

### Running Rails as a server

For developing rails applications you can start the server locally using the
following command:

```sh
rails server
```

and visit <localhost:3000> in your browser.

To change to using `production` mode use the `-e` option; or to change to a
different port use the `-p` option.

Note: In `production` mode, `SECRET_KEY_BASE` is also required. It is
insufficient to just set this as the value must be exported. e.g.

```sh
export SECRET_KEY_BASE=$(./bin/rails secret)
```

#### Running Rails as a server with a sub-directory via Makefile

```sh
API_SERVICE_URL=<data-api url> RAILS_ENV=<mode> RAILS_RELATIVE_URL_ROOT=/<path> make server
```

The default for `RAILS_ENV` here is `development`.

### Building and Running the docker container

It can be useful to run the compiled Docker image, that will mirror the
production installation, locally yourself. Assuming you have the [Standard
Reports Manager running](#running-the-standard-reports-manager-locally), then
you can run the Docker image for the app itself as follows:

```sh
make image run
```

or, if the image is already built, simply

```sh
make run
```

Docker images run in `production` mode.

To test the running application visit `localhost:<port>/<application path>`.

## Runtime Configuration environment variables

We use a number of environment variables to determine the runtime behaviour of
the application:

| name | description | default value |
| -------------------------- | ----------------------------------------------------------------------- | -------------------------- |
| `API_SERVICE_URL` | The base URL from which data is accessed, including the HTTP scheme eg. | None |
| | <http://localhost:8081> if running a `standard-reports-manager service` locally | |
| | <http://standard-reports-manager:8080> if running a `standard-reports-manager docker` image locally | |
| `SECRET_KEY_BASE` | See [description](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-secret_key_base). | |
| | For `development` mode a acceptable value is already configured, in production mode this should be set to the output of `rails secret`. | |
| | This is handled automatically when starting a docker container, or the `server` `make` target | |
| `SENTRY_API_KEY` | The DSN for sending reports to the PPD Sentry account | None |

### Running the Standard Reports Manager locally
## Running the Standard Reports Manager locally

The application connects to the Standard Reports Manager service to submit
requests.
Expand All @@ -121,7 +25,7 @@ manager](https://github.com/epimorphics/standard-reports-manager/) repository.
or pulled from the Amazon Elastic Container Registry
[ECR](https://eu-west-1.console.aws.amazon.com/ecr/repositories/private/018852084843/epimorphics/standard-reports-manager/dev?region=eu-west-1).

#### Building and running from [standard reports manager](https://github.com/epimorphics/standard-reports-manager/) repository
### Building and running from [standard reports manager](https://github.com/epimorphics/standard-reports-manager/) repository

To build and a run a new docker image check out the [standard reports
manager](https://github.com/epimorphics/standard-reports-manager/) repository
Expand All @@ -131,7 +35,7 @@ and run
make image run
```

#### Running an existing [ECR](https://eu-west-1.console.aws.amazon.com/ecr/repositories/private/018852084843/epimorphics/standard-reports-manager/dev?region=eu-west-1) image
### Running an existing [ECR](https://eu-west-1.console.aws.amazon.com/ecr/repositories/private/018852084843/epimorphics/standard-reports-manager/dev?region=eu-west-1) image

Obtaining an ECR image requires:

Expand Down Expand Up @@ -178,7 +82,7 @@ To create the docker network run
docker network create dnet
```

### To run the Standard Reports Manager as a docker container
### Running as a docker container

Take a copy of the latest Manager development configuation file

Expand Down Expand Up @@ -206,11 +110,91 @@ port.
With this set up, the api service is available on `http://localhost:8081` from
the host or `http://standard-reports-manager:8080` from inside other docker containers.

## Developer notes
## Running the app

### Structure
This application can be run stand-alone as a rails server in `development` mode.
However, when deployed, applications will run behind a reverse proxy.

This enables request to be routed to the appropriate application base on the
request path. In order to simplifiy the proxy configuration we retain the
original path where possible.

For information on how to running a proxy to mimic production and run multple
services together read through the information in our
[simple-web-proxy](https://github.com/epimorphics/simple-web-proxy/edit/main/README.md)
repository.

If running more than one application locally ensure that each is listerning on a
separate port and separate path. In the case of running local docker images, the
required configuration is captured in the `Makefile`.

### Locally

For developing rails applications you can start the server locally using the
following command:

```sh
rails server
```

and visit <localhost:3000> in your browser.

This is a fairly standard Rails project, with no particular surprises.
To change to using `production` mode use the `-e` option; or to change to a
different port use the `-p` option.

Note: In `production` mode, `SECRET_KEY_BASE` is also required. It is
insufficient to just set this as the value must be exported. e.g.

```sh
export SECRET_KEY_BASE=$(./bin/rails secret)
```

#### Running Rails as a server with a sub-directory via Makefile

```sh
API_SERVICE_URL=<data-api url> RAILS_ENV=<mode> RAILS_RELATIVE_URL_ROOT=/<path> make server
```

The default for `RAILS_ENV` here is `development`.

### As a docker container

It can be useful to run the compiled Docker image, that will mirror the
production installation, locally yourself. Assuming you have the [Standard
Reports Manager running](#running-the-standard-reports-manager-locally), then
you can run the Docker image for the app itself as follows:

```sh
make image run
```

or, if the image is already built, simply

```sh
make run
```

Docker images run in `production` mode.

To test the running application visit `localhost:<port>/<application path>`.

### Development and Production mode

Applications running in `development` mode default to *not* use a sub-directory
to aid stand-alone development.

Applications running in `production` mode *do* use a sub-directory i.e.
`/app/standard-reports`.

In each case the is achieved by setting `config.relative_url_root` property to
this sub-directory within the file
`config/environments/(development|production).rb`.

If need be, `config.relative_url_root` may by overridden by means of the
`RAILS_RELATIVE_URL_ROOT` environment variable, althought this could also
require rebuilding the assets or docker image.

## Additional Information

### Coding standards

Expand All @@ -227,12 +211,25 @@ API_SERVICE_URL=http://localhost:8081 bundle exec rails test
Passing in the `API_SERVICE_URL` is required to ensure the tests run against the
`standard-reports-manager` service running locally.

## Issues
### Issues

Please add issues to the [shared issues
list](https://github.com/epimorphics/hmlr-linked-data/issues)

## Additional Information
### Runtime Configuration environment variables

We use a number of environment variables to determine the runtime behaviour of
the application:

| name | description | default value |
| -------------------------- | ----------------------------------------------------------------------- | -------------------------- |
| `API_SERVICE_URL` | The base URL from which data is accessed, including the HTTP scheme eg. | None |
| | <http://localhost:8081> if running a `standard-reports-manager service` locally | |
| | <http://standard-reports-manager:8080> if running a `standard-reports-manager docker` image locally | |
| `SECRET_KEY_BASE` | See [description](https://api.rubyonrails.org/classes/Rails/Application.html#method-i-secret_key_base). | |
| | For `development` mode a acceptable value is already configured, in production mode this should be set to the output of `rails secret`. | |
| | This is handled automatically when starting a docker container, or the `server` `make` target | |
| `SENTRY_API_KEY` | The DSN for sending reports to the PPD Sentry account | None |

### Deployment

Expand Down

0 comments on commit 3ee278a

Please sign in to comment.