From 1e85524d0efe5e63a71eb29d48244a1acb973671 Mon Sep 17 00:00:00 2001 From: ChrisBAshton Date: Thu, 7 Nov 2024 17:40:37 +0000 Subject: [PATCH] WIP: Re-work README to make it clearer how to run the app App dependency install, build script and startup scripts seemed oddly dispersed throughout the README, making it difficult to talk about shared logic such as the ENV variables. I've consolidated these into their own "Run the app locally" section. Other things to note: - I added `--verbose` to the build script, as the build initially failed for me and I had to re-run the script with verbose mode to see any meaningful output. The output isn't much more verbose than without the flag, so there seems no downside. - I removed the section on `.env` file, as it seems to be an implementation detail, and also incompatible with running via govuk-docker. But I'd like to revisit this. - I'm currently able to compile the website fine, and fetch the remote docs, but am struggling to get the app to _run_ locally (in govuk-docker). - I'd very much like to remove the "docker-compose.yml" hack workaround. --- README.md | 52 ++++++++++++++++++++-------------------------------- 1 file changed, 20 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 5d17eb477a..049a9413c4 100644 --- a/README.md +++ b/README.md @@ -7,43 +7,39 @@ This is a static site generated with Middleman, using [alphagov/tech-docs-templa Some of the files (like the CSS, javascripts and layouts) are managed in the template and are not supposed to be modified here. Any project-specific Ruby code needs to go into `/app`. -## Build the app locally +## Run the app locally + +Install the dependencies: ```sh bundle install ``` -## Run the tests locally +You can then start up the site with `./startup.sh` (or `govuk-docker-up` if using [govuk-docker](https://github.com/alphagov/govuk-docker)). The startup script can optionally be configured with the following ENV variables: -``` -bundle exec rake -``` +- `GOVUK_TOKEN=` - token to use to make authenticated requests to GitHub's API. Authenticated requests have a much higher rate limit. *You will need to specify a `GITHUB_TOKEN` if you want to build the entire Developer Docs site*. You can [create a GitHub token](https://github.com/settings/tokens/new) (the token doesn't need any scopes). +- `SKIP_PROXY_PAGES=true` - avoid fetching remote 'docs/' for each repo (i.e. just build the docs that live within govuk-developer-docs itself). You can use this if you don't have a `GITHUB_TOKEN` or if you don't care about including the remote docs. -## Run the app locally +If using govuk-docker, you may struggle to pass ENV variables to the script. You can work around this by [editing the docker-compose.yml](https://github.com/alphagov/govuk-docker/blob/ed98d3547708286f534598c78fb5c57ee3c8d112/projects/govuk-developer-docs/docker-compose.yml#L12) to add the following to the `govuk-developer-docs-lite` entry: -```sh -SKIP_PROXY_PAGES=true ./startup.sh +```yml + environment: + LANG: "C.UTF-8" + GITHUB_TOKEN: "" + NO_CONTRACTS: true ``` -## Proxy pages - -The live docs site includes pages from other alphagov GitHub repositories. To test this locally, omit `SKIP_PROXY_PAGES=true` from the command above. - -The app downloads these "proxy pages" at startup and this can cause GitHub to rate limit your requests. You can pass a valid GitHub API token to the app to help avoid this: - -1. [Create a GitHub token](https://github.com/settings/tokens/new). The token doesn't need any scopes. - -1. Store the token in a `.env` file: +If you just want to create the site (a `build/` directory containing a set of HTML files), but not actyally start up the application, you can do so as follows (noting that the ENV variables described above apply here too): - ```sh - GITHUB_TOKEN=somethingsomething - ``` +```sh +NO_CONTRACTS=true bundle exec middleman build --verbose +``` -1. Start the application: +## Run the tests locally - ```sh - ./startup.sh - ``` +``` +bundle exec rake +``` ## Update to the latest Tech Docs template @@ -58,14 +54,6 @@ We host GOV.UK Developer Docs as a static site on GitHub Pages. The [ci.yml] Git - when a PR is merged to the default branch - on an hourly schedule, to pick up changes to docs included from other repos -### Build the static site locally - -```sh -NO_CONTRACTS=true bundle exec middleman build -``` - -This will create a `build` directory containing a set of HTML files. - ## Licence [MIT License](LICENCE)