-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Moved all README information into the wiki
- Loading branch information
1 parent
9546d9d
commit a14e09b
Showing
1 changed file
with
1 addition
and
188 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,188 +1 @@ | ||
# HMLR linked-data applications landing site | ||
|
||
This repo provides the landing page experience for visitors to | ||
[landregistry.data.gov.uk](http://landregistry.data.gov.uk). The landing page | ||
provides links to the various open data services, and hosts the qonsole | ||
app, which allows users to run SPARQL queries against the linked-data dataset. | ||
|
||
Please see the other repositories in the [HM Land Registry Open | ||
Data](https://github.com/epimorphics/hmlr-linked-data/) project for more | ||
details. | ||
|
||
## Running the app locally | ||
|
||
### In development mode | ||
|
||
Begin by cloning [the Github repo](https://github.com/epimorphics/lr-landing) | ||
and installing the dependencies: | ||
|
||
```sh | ||
git clone [email protected]:epimorphics/lr-landing.git && | ||
cd lr-landing && | ||
bundle install | ||
``` | ||
|
||
#### Trouble shooting bundle install | ||
|
||
If bundle install does not work add a .bundle directory and create a config | ||
file. So you now have .bundle/config. | ||
Add the following line to the config file. | ||
BUNDLE_RUBYGEMS__PKG__GITHUB__COM: "your-username:your-personal-access-token" | ||
Then run bundle install again and eveything should work. | ||
|
||
Start the app locally for development: | ||
|
||
```sh | ||
rails server | ||
``` | ||
|
||
If you want to be able to test `Qonsole` locally, you will need to run the app | ||
with the `API_SERVICE_URL` environment variable set to the URL of the Data API: | ||
|
||
```sh | ||
API_SERVICE_URL=http://localhost:8888 rails server | ||
``` | ||
|
||
Visit <http://localhost:3000> to view the local instance. | ||
|
||
### In production mode | ||
|
||
Unlike other HMLR applications, the Landing application does not run run from a | ||
sub-directory. | ||
|
||
As such **Production** *and* **Development** modes run at the same path. | ||
|
||
If running more than one application locally you need to ensure that each is | ||
listening on a separate port. In the case of running local docker images, the | ||
required configuration is captured in the application's `Makefile` and an image | ||
can be run by using: | ||
|
||
```sh | ||
make image run | ||
``` | ||
|
||
or, if the image is already built, simply | ||
|
||
```sh | ||
make run | ||
``` | ||
|
||
You can start a production mode rails server locally using the following | ||
command: | ||
|
||
```sh | ||
rails server -e production | ||
``` | ||
|
||
N.B Ommitting the `-e` flag will default to `development` mode. | ||
|
||
To test the running application visit <http://localhost:3000> in your browser. | ||
|
||
For more information on how to running a proxy to mimic production and run | ||
multple services together see | ||
[simple-web-proxy](https://github.com/epimorphics/simple-web-proxy/) | ||
|
||
With the proxy and Docker container running you can access the application as | ||
[`localhost:8080`](http://localhost:8080) (note the lack of trailing path). | ||
|
||
## Additional Information | ||
|
||
### Updating the code | ||
|
||
This is a pretty standard, and quite small, Rails app. | ||
|
||
Please keep the [changelog](CHANGELOG.md) up-to-date, and increment the | ||
[`/app/lib/version.rb`](https://github.com/epimorphics/lr-landing/app/lib/version.rb) | ||
identifier in line with semver principles. | ||
|
||
### Coding standards | ||
|
||
#### Running code linting | ||
|
||
```sh | ||
rubocop | ||
``` | ||
|
||
Rubocop should always return no errors or warnings. | ||
|
||
```sh | ||
Inspecting 30 files | ||
.............................. | ||
|
||
30 files inspected, no offenses detected | ||
``` | ||
|
||
#### Running integration tests | ||
|
||
```sh | ||
rails test | ||
``` | ||
|
||
Tests should always return as passing: | ||
|
||
```sh | ||
Run options: --seed ##### | ||
|
||
# Running: | ||
[...] | ||
|
||
Finished in 1.050748s, 6.6619 runs/s, 8.5653 assertions/s. | ||
7 runs, 9 assertions, 0 failures, 0 errors, 0 skips | ||
``` | ||
|
||
### Deployment | ||
|
||
The detailed deployment mapping is described in `deployment.yml`. At the time of | ||
writing, using the new infrastructure, the deployment process is as follows: | ||
|
||
- commits to the `dev-infrastructure` branch will deploy the `dev` server | ||
- commits to the `preprod` branch will deploy the `pre-production` server | ||
- any commit on the `prod` branch will deploy the `production` server as a new | ||
release | ||
|
||
If the commit is a "new" release, the deployment should be tagged with the same | ||
version number, e.g. `1.2.3`. as set in the `/app/lib/version.rb` and a short | ||
annotation summarising the updates should be included in the tag. | ||
|
||
Once the production deployment has been completed and verified, please create a | ||
release on the repository using the same latest version number. Utilise the | ||
`Generate release notes from commit log` option to create specific notes on the | ||
contained changes as well as the ability to diff agains the previous version. | ||
|
||
#### `entrypoint.sh` | ||
|
||
- There is a workaround to removing the PID lock of the Rails process in the | ||
event of the application crashing and not releasing the process. | ||
- The rails `SECRET_KEY_BASE` is created here. | ||
|
||
### Runtime Configuration environment variables | ||
|
||
We can use a number of environment variables to determine the runtime behaviour | ||
of the application while developing the codebase locally: | ||
|
||
| name | description | | ||
| -------------------------- | -------------------------------------------------------------------- | | ||
| `SENTRY_API_KEY` | The Sentry DSN client key for the `lr-dgu-landing` Sentry app | | ||
|
||
### Dependent gems | ||
|
||
Most of the local (i.e. Epimorphics) gems that this project depends on are | ||
served via GitHub Package Registry (GPR). Specifically, `lr_common_styles` and | ||
`json-rails-logger`. | ||
|
||
However, `qonsole-rails` is **not** served via GPR at present, mostly because we | ||
are hoping to retire it in favour of a new implementation of Qonsole. Since | ||
`qonsole-rails` is a public repo, this dependency does not require us to lean on | ||
the old pattern of using an ssh key to serve private gems directly from a GitHub | ||
repo. | ||
|
||
Accessing gems from GPR will require a personal access token (PAT). To store | ||
this locally, use `make auth` to set your GitHub Token using the PAT. | ||
|
||
To create a PAT, see [the Epimorphics | ||
wiki](https://github.com/epimorphics/internal/wiki/Ansible-CICD#creating-a-pat-for-gpr-access). | ||
|
||
### Issues | ||
|
||
Please add issues to the [shared issues | ||
list](https://github.com/epimorphics/hmlr-linked-data/issues) | ||
Please see [the wiki](https://github.com/epimorphics/lr-landing/wiki) for more information about the project. |