Skip to content

Commit

Permalink
Update README.me (#722)
Browse files Browse the repository at this point in the history 
* Update README.me

also, use `translate_markdown` on existing areas of learning
pages to properly format Govspeak markdown

* Update README

- clean up environment variables
  replace use of CONTENTFUL and NEW_DESIGN to just use NEW_DESIGN
- use CONTENTFUL_PREVIEW rather than simply PREVIEW to match CDT
- add `prepare_cms` to every request (match CDT)

* Update release and contentful documents

* Add asdf local versions

* Update README

* Remove redundant space

---------

Co-authored-by: Rick Jones <[email protected]>
  • Loading branch information
@ebrett @nomasprime
ebrett and nomasprime authored Mar 5, 2024
1 parent 980e9e2 commit 6245ffb
Show file tree
Hide file tree
Showing 15 changed files with 341 additions and 255 deletions.
3 changes: 0 additions & 3 deletions .env.development.example
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,3 @@ DATABASE_PASSWORD=
DATABASE_HOST=localhost
NODE_ENV=development
POSTGRES_PASSWORD=
WEBPACKER_DEV_SERVER_HOST=0.0.0.0
FEEDBACK_URL=
SIGNUP_URL=
1 change: 0 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,6 @@ yarn-debug.log*
.env.development
*.log
/.idea
/.tool-versions
.DS_Store
/coverage

Expand Down
3 changes: 3 additions & 0 deletions .tool-versions
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
ruby 3.2.2
nodejs 20.11.0
postgres 13.1
315 changes: 94 additions & 221 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,271 +1,144 @@
[![Deploy to Dev](https://github.com/DFE-Digital/early-years-foundation-reform/workflows/deploy_to_dev/badge.svg)](https://github.com/DFE-Digital/early-years-foundation-reform/actions)
# Early Years Reform Framework
[![Deploy to Development](https://github.com/DFE-Digital/early-years-foundation-reform/workflows/azure-deploy-dev/badge.svg)](https://github.com/DFE-Digital/early-years-foundation-reform/actions)
[![Deploy to Staging](https://github.com/DFE-Digital/early-years-foundation-reform/workflows/azure-deploy-stage/badge.svg)](https://github.com/DFE-Digital/early-years-foundation-reform/actions)
[![Deploy to Production](https://github.com/DFE-Digital/early-years-foundation-reform/workflows/azure-deploy-prod/badge.svg)](https://github.com/DFE-Digital/early-years-foundation-reform/actions)

This is a minimalistic content management system, written in Ruby on Rails
for use by content editors in the Early Years Reform Framework project.
# Help For Early Years Providers

It allows editors to create a set of nested pages, and to edit the headings,
overview and content as [Markdown](https://en.wikipedia.org/wiki/Markdown).
This is an application, written in Ruby on Rails (Version 7), based on the [DFE-Digital](rails-template) template. It uses a [Contenful](https://app.contentful.com/spaces/dvmeh832nmjc/) workspace for the content, managed by the content editors in the Help For Early Years Providers service.

These are some examples of the cut down CMS and two resulting pages
all in UK.GOV style;
Optionally create `.env` to override or set default variables.

![The CMS view](docs/cms-view.png?raw=true "The CMS view"seed)
![Example page](docs/public-view-of-a-page.png?raw=true "Example page")
## Dependencies

## Prerequisites
Ruby version `3.2.x`
Node version `20.11.x`
PostgreSQL version `13.1`
Yarn version `4.0.x`

Ruby version `2.7.2`
Suggest using [asdf](asdf) for local development.

Node version `14.x.x`
## Getting started on Docker
## Getting started

On Mac OS, [Docker Desktop / Docker for Mac](https://docs.docker.com/docker-for-mac/install/)
will need to be installed first and running
1. Clone the [repository](app-repo)
2. Obtain master key
3. Run `bundle install` to install the gem dependencies
4. Run `yarn` to install node dependencies
5. Copy the .env.development.example settings into the .env file
7. Run `bin/rails db:setup` to set up the database development and test schemas, and seed with test data
8. Run `bin/dev` to launch the app on http://localhost:3000

Setup a `.env` file to hold environment variables and fill in the missing values
(do not commit this file)

`cp .env.example .env`

add development database to .env: govuk_rails_boilerplate_development

### To run the application locally with docker:

NOTE: Ensure no instances of PostgreSQL are running in the background as this can cause conflicts when attempting to run the docker instance of PostgreSQL
If PostgreSQL was installed using homebrew, in the terminal use:
1. `brew services` - to check for any running instances,
2. `brew services stop postgres`

To run the application locally with docker:

`docker-compose build && docker-compose up`

If docker has been setup correctly, running `sudo docker ps`, you should see 2 containers running like this:
## Running specs, linter(without auto correct) and annotate models and serializers

```sh
bundle exec
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
005b86d0b4dc eyfs-reform-spike_app "./entrypoints/docke…" 5 hours ago Up 5 minutes 0.0.0.0:3000->3000/tcp eyfs-reform-spike_app_1
460c5fe17d37 postgres:13.1 "docker-entrypoint.s…" 5 hours ago Up 5 minutes 0.0.0.0:5432->5432/tcp eyfs-reform-spike_database_1
```

### To setup the database running in a docker container (runs terminal command inside of your docker container):

`docker-compose exec app bundle exec rake db:setup`
`docker-compose exec app bundle exec rake db:migrate`
`docker-compose exec app bundle exec rake db:seed`

### To restart the server

cancel the running docker process and then run `docker-compose down` (for a full reset on your environment)

### To connect to the docker container and run commands

`docker exec -it eyfs-reform-spike_app_1 sh`

### Authentication
Devise is used for the CMS routes. Basic Auth can be turned on for the whole site by setting
and environment variable called AUTH_ON_EVERYTHING.

The ContentController will then use the devise accounts to check the basic auth, but it does
not log users in.

Creating an admin user:
## Running specs

```sh
bundle exec rspec
```
User.create!(
first_name: 'First',
last_name: 'Last',
email: '[email protected]',
password: 'P4ssW0rd!!',
password_confirmation: 'P4ssW0rd!!',
role: 'admin',
)
```

### If there are issues with postgres password authentication failure:

`> FATAL: password authentication failed for user "boilerplate_user"`

You can manually set a password for the user `boilerplate_user` by following these steps:

1. `docker-compose exec database psql -d postgres -U boilerplate_user`
2. in the postgres cli run `\password`
3. set the `DATABASE_PASSWORD` from `.env`

## Styling pages

See [this guide](https://design-system.service.gov.uk/get-started/) for
advice about how to layout html
## Credentials & Environment Variables

## CI/CD
We use rails credentials to manage secrets; obtain the master key from the Dev team.

When a branch is merged into `main`
To edit:

- a docker image is built and pushed to [DockerHub](https://hub.docker.com/repository/docker/dfedigital/eyfsreform)

### Documentation

Check out [documentation](/documentation) folder

# The following is from the template repository GOV.UK Rails Boilerplate

## Prerequisites

- Ruby 2.7.1
- PostgreSQL
- NodeJS 12.13.x
- Yarn 1.12.x

## Setting up the app in development

1. Run `bundle install` to install the gem dependencies
2. Run `yarn` to install node dependencies
3. Copy the .env.development.example settings into the .env file
4. Run `bin/rails db:setup` to set up the database development and test schemas, and seed with test data
5. Run `bundle exec rails server` to launch the app on http://localhost:3000
6. Run `./bin/webpack-dev-server` in a separate shell for faster compilation of assets

## Whats included in this boilerplate?

- Rails 6.0 with Webpacker
- [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend)
- RSpec
- Dotenv (managing environment variables)
- Travis with Heroku deployment

## Running specs, linter(without auto correct) and annotate models and serializers
```
bundle exec rake
```

## Running specs
```
bundle exec rspec
```sh
$ EDITOR=vi bin/rails credentials:edit
```

## Linting
Currently encrypts the following secrets:

It's best to lint just your app directories and not those belonging to the framework, e.g.
```yml
secret_key_base:

```bash
bundle exec rubocop app config db lib spec Gemfile --format clang -a
contentful:
environment:
space:
delivery_access_token:
preview_access_token:

or

bundle exec scss-lint app/webpacker/styles
user_password:
```
Vscode - Rubocop has a vscode extension, linting may need to be turned on

## Deploying on GOV.UK PaaS
The contentful credentials can be overridden with environment variables:
### Prerequisites
```
CONTENTFUL_SPACE=
CONTENTFUL_ENVIRONMENT=
CONTENTFUL_DELIVERY_TOKEN=
CONTENTFUL_PREVIEW_TOKEN=
CONTENTFUL_MANAGEMENT_TOKEN=
```

- Your department, agency or team has a GOV.UK PaaS account
- You have a personal account granted by your organisation manager
- You have downloaded and installed the [Cloud Foundry CLI](https://github.com/cloudfoundry/cli#downloads) for your platform
The management token is not used in the application and each developer should have their own. It is used to run the contentful migration and upload tasks.

### Deploy
## Deployment Pipelines

1. Run `cf login -a api.london.cloud.service.gov.uk -u USERNAME`, `USERNAME` is your personal GOV.UK PaaS account email address
2. Run `bundle package --all` to vendor ruby dependencies
3. Run `yarn` to vendor node dependencies
4. Run `bundle exec rails webpacker:compile` to compile assets
5. Run `cf push` to push the app to Cloud Foundry Application Runtime
Visit the [Github Container Registry][ghcr].

Check the file `manifest.yml` for customisation of name (you may need to change it as there could be a conflict on that name), buildpacks and eventual services (PostgreSQL needs to be [set up](https://docs.cloud.service.gov.uk/deploying_services/postgresql/)).
[Development][development] is deployed automatically with the latest commit from `main`.

#### Deploy service unavailable app
Individual branches may also be used as the source for the deployment, so you can set up the application to review a specific feature not yet merged with `main` branch.

1. Run `cf login -a api.london.cloud.service.gov.uk -u USERNAME`, `USERNAME` is your personal GOV.UK PaaS account email address
2. Select eyfs-prod target
3. Run `cd service_unavailable` to change to that directory
4. Run `cf push` to push that app to Cloud Foundary.
[Staging][staging] is deployed from this [workflow][azure-deploy-stage].
[Production][production] is deployed from this [workflow][azure-deploy-prod].

That will deploy any changes of the static site in `/service_unavailable` (see `/service_unavailable/manifest.yml` for target app name)

Use the Github action "Deploy Service Unavailable" to re-route production traffic to the service_unavailable app.
And use the action "Revoke Service Unavailable" to return the traffic to the main app.
## Azure

## Cucumber Tests
Console access:

### To run
- They can be run manually in IDE
- Command line
- Intention for these integration / e2e tests to run in AWS CI pipeline
- https://hfeyp-dev.scm.azurewebsites.net/webssh/host
- https://hfeyp-stage.scm.azurewebsites.net/webssh/host
- https://hfeyp-prod.scm.azurewebsites.net/webssh/host

#### IDE
Right click on 'Feature' and run
Or
Run - Edit Configurations (depending on IDE)
## Monitoring

#### Command Line
cucumber --color -r e2etestname.feature

#### AWS CI pipeline (Drone.yml configuration)
```
- Ruby E2E Tests
- e2e-test:
- group: ?
- image: ruby:2.7.2
- commands:
- - cd e2etests
- - gem install bundler
- - bundle install
- - cucumber --color -r features -p [insert env]
- when:
- trigger:
- branch:
- - tbc/*
- event:
- - push
## Setup
[Sentry][sentry] is used to monitor production environments

### Prerequisites
`$ brew install getsentry/tools/sentry-cli`

This project depends on:
`$ sentry-cli projects list --org early-years-foundation-reform`

- [Ruby](https://www.ruby-lang.org/)
- [Ruby on Rails](https://rubyonrails.org/)
- [NodeJS](https://nodejs.org/)
- [Yarn](https://yarnpkg.com/)
- [Postgres](https://www.postgresql.org/)
+---------+--------------+-------------------------------+--------------+
| ID | Slug | Team | Name |
+---------+--------------+-------------------------------+--------------+
| 6274627 | eyf-reform | early-years-foundation-reform | Rails |
| 6274651 | eyf-recovery | early-years-foundation-reform | eyf-recovery |
+---------+--------------+-------------------------------+--------------+

### asdf
## Hotjar

This project uses `asdf`. Use the following to install the required tools:
This project uses Hotjar for user insight. Hotjar records user journeys and
automatically redacts certain user information on recordings. All personally
identifiable information should be redacted. In order to override the default
settings the following classes can be added:

```sh
# The first time
brew install asdf # Mac-specific
asdf plugin add ruby
asdf plugin add nodejs
asdf plugin add yarn
asdf plugin add postgres
# To install (or update, following a change to .tool-versions)
asdf install
```
- `data-hj-suppress` to redact additional user information
- `data-hj-allow` to allow data that is automatically redacted

When installing the `pg` gem, bundle changes directory outside of this
project directory, causing it lose track of which version of postgres has
been selected in the project's `.tool-versions` file. To ensure the `pg` gem
installs correctly, you'll want to set the version of postgres that `asdf`
will use:
---

```sh
# Temporarily set the version of postgres to use to build the pg gem
ASDF_POSTGRES_VERSION=13.5 bundle install
```
[app-repo]: https://github.com/DFE-Digital/early-years-foundation-reform
[asdf]: https://asdf-vm.com
[prototype-repo]: https://github.com/DFE-Digital/ey-hfeyp-prototype
[rails-template]: https://github.com/DFE-Digital/rails-template
[ghcr]: https://ghcr.io/dfe-digital/help-for-early-years-providers
[confluence]: https://dfedigital.atlassian.net/wiki/spaces/ER/overview
[sentry]: https://sentry.io/organizations/early-years-foundation-reform

## How the application works
<!-- Deployments -->

We keep track of architecture decisions in [Architecture Decision Records
(ADRs)](/adr/).
[prototype-app]: https://ey-hfeyp-prototype-3ac4ece6c97b.herokuapp.com/
[production]: https://help-for-early-years-providers.education.gov.uk
[staging]: https://staging.help-for-early-years-providers.education.gov.uk
[development]: https://hfeyp-dev.azurewebsites.net

We use `rladr` to generate the boilerplate for new records:
<!-- GH workflows -->

```bash
bin/bundle exec rladr new title
```
[ci-workflow]: https://github.com/DFE-Digital/early-years-foundation-recovery/actions/workflows/ci.yml
[production-workflow]: https://github.com/DFE-Digital/early-years-foundation-reform/actions/workflows/azure-deploy-prod.yml
[staging-workflow]: https://github.com/DFE-Digital/early-years-foundation-reform/actions/workflows/azure-deploy-stage.yml
Loading

0 comments on commit 6245ffb

Please sign in to comment.