Improvements to documentation around getting Developer Docs running locally #4875
+35
−33
Conversation
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
ChrisBAshton
force-pushed
the
local-dev-doc-improvements
branch
from
1e85524 to
33956a0
Compare
We can give a hint to the user as to how to fix the following
issue:
```
== Request: /document-types/landing_page.html
error build/document-types/landing_page.html
undefined method `include?' for nil
/govuk/govuk-developer-docs/app/document_types.rb:83:in `block in shift_low_value_schemas'
/govuk/govuk-developer-docs/app/document_types.rb:82:in `each'
/govuk/govuk-developer-docs/app/document_types.rb:82:in `shift_low_value_schemas'
/govuk/govuk-developer-docs/app/document_types.rb:74:in `schemas'
/govuk/govuk-developer-docs/source/templates/document_type_template.html.md.erb:28:in `__tilt_29200'
/root/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/tilt-2.0.11/lib/tilt/template.rb:181:in `call'
/root/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/tilt-2.0.11/lib/tilt/template.rb:181:in `evaluate'
/root/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/tilt-2.0.11/lib/tilt/template.rb:109:in `render'
```
ChrisBAshton
force-pushed
the
local-dev-doc-improvements
branch
from
33956a0 to
05dd126
Compare
minhngocd
approved these changes
Feb 3, 2025
There was a problem hiding this comment.
I tried out the instructions:
- local run without docker works without the Github token being in place by using SKIP_PROXY_PAGES as suggested
- docker run still failed with rate limiting when i set the env var in docker-compose.yml to SKIP_PROXY_PAGES true. Does the docker version only work if the Github token is set?
minhngocd
requested changes
Feb 3, 2025
| 1. Install the dependencies (`govuk-docker-run bundle install`) | ||
| 1. Run the application (`govuk-docker-up`) | ||
| 1. Wait until all the GitHub API calls have completed (you'll see `Inspect your site configuration at` in the output). This can take a few minutes. | ||
| 1. Visit <http://govuk-developer-docs.dev.gov.uk/> |
There was a problem hiding this comment.
The SKIP_PROXY_PAGES option for docker seems to be throwing an error, curious if it worked for you? I wasn't able to look into it, but might worth noting that it doesn't support that at the moment.
There was a problem hiding this comment.
Nevermind, after getting past the rate limiting, I'm also hitting the same error as if i just passed through SKIP PROXY PAGES which is :
govuk-developer-docs-app-1 | bundler: failed to load command: middleman (/root/.rbenv/versions/3.3.1/bin/middleman)
govuk-developer-docs-app-1 | /root/.rbenv/versions/3.3.1/lib/ruby/3.3.0/prettyprint.rb:184:in `text': can't convert Middleman::CoreExtensions::Collections::LazyCollectorStep to String (Middleman::CoreExtensions::Collections::LazyCollectorStep#to_str gives Middleman::CoreExtensions::Collections::LazyCollectorStep) (TypeError)
govuk-developer-docs-app-1 |
govuk-developer-docs-app-1 | @output << obj
govuk-developer-docs-app-1 | ^^^
govuk-developer-docs-app-1 | from /root/.rbenv/versions/3.3.1/lib/ruby/3.3.0/pp.rb:328:in `pretty_print'
govuk-developer-docs-app-1 | from /root/.rbenv/versions/3.3.1/lib/ruby/3.3.0/pp.rb:201:in `block in pp'
There was a problem hiding this comment.
Yep, works for me:
services:
govuk-developer-docs-lite:
<<: *govuk-developer-docs
environment:
LANG: "C.UTF-8"
SKIP_PROXY_PAGES: true
NO_CONTRACTS: true
govuk-developer-docs-app:
<<: *govuk-developer-docs
depends_on:
- nginx-proxy
environment:
VIRTUAL_HOST: govuk-developer-docs.dev.gov.uk
LANG: "C.UTF-8"
SKIP_PROXY_PAGES: true
NO_CONTRACTS: true
expose:
- "4567"
command: bundle exec middleman server --bind-address 0.0.0.0make govuk-developer-docsin govuk-dockergovuk-docker-upin the govuk-developer-docs repo- Wait for
Inspect your site configuration at "http://f7c8440e469d.local:4567/__middleman" - I did continue to get 502 Bad Gateway for a while, but refreshing for a minute or so solved that.
| ```yml | ||
| environment: | ||
| LANG: "C.UTF-8" | ||
| GITHUB_TOKEN: "<fill it in>" |
There was a problem hiding this comment.
This block is under govuk-developer-docs-lite, but when we run govuk-docker-up it attaches to the govuk-developer-docs-app service, which is the block below. Should we put it in that block instead? or maybe in the common govuk-developer-docs above?
There was a problem hiding this comment.
I've now tweaked the doc to make it clearer to add it to both services. 👍
I don't think it's possible to add to the common govuk-developer-docs because the environment property in -lite and -app override that value rather than merge with it.
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'd very much like to remove the "docker-compose.yml" hack workaround. But better to document the bad and fix it later, than leave the bad undocumented!
ChrisBAshton
force-pushed
the
local-dev-doc-improvements
branch
from
05dd126 to
e500e46
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
We were having trouble getting this working locally, which wasn't helped by sporadic docs and swallowed errors. See commits.