diff --git a/README.md b/README.md index 7c05f1b..c057e42 100644 --- a/README.md +++ b/README.md @@ -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 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= RAILS_ENV= RAILS_RELATIVE_URL_ROOT=/ 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:/`. - -## 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 | -| | if running a `standard-reports-manager service` locally | | -| | 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. @@ -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 @@ -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: @@ -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 @@ -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 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= RAILS_ENV= RAILS_RELATIVE_URL_ROOT=/ 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:/`. + +### 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 @@ -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 | +| | if running a `standard-reports-manager service` locally | | +| | 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