README.md

# notifications-admin

GOV.UK Notify admin application - https://www.notifications.service.gov.uk/

 - Register and manage users
 - Create and manage services
 - Send batch emails and SMS by uploading a CSV
 - Show history of notifications

## Setting up

### Python version

At the moment we run Python 3.9 in production.

### NodeJS & NPM

If you don't have NodeJS on your system, install it with homebrew.

```shell
brew install node
```

`nvm` is a tool for managing different versions of NodeJS. Follow [the guidance on nvm's github repository](https://github.com/nvm-sh/nvm#installing-and-updating) to install it.

Once installed, run the following to switch to the version of NodeJS for this project. If you don't
have that version, it should tell you how to install it.

```shell
nvm use
```

### `environment.sh`

In the root directory of the application, run:

```
echo "
export NOTIFY_ENVIRONMENT='development'
export FLASK_APP=application.py
export FLASK_ENV=development
export WERKZEUG_DEBUG_PIN=off
"> environment.sh
```

### AWS credentials

To run parts of the app, such as uploading letters, you will need appropriate AWS credentials. See the [Wiki](https://github.com/alphagov/notifications-manuals/wiki/aws-accounts#how-to-set-up-local-development) for more details.

## To run the application

```shell
# install dependencies, etc.
make bootstrap

# run the web app
make run-flask
```

Then visit [localhost:6012](http://localhost:6012).

Any Python code changes you make should be picked up automatically in development. If you're developing JavaScript code, run `npm run watch` to achieve the same.

## To test the application

```
# install dependencies, etc.
make bootstrap

# run all the tests
make test

# continuously run js tests
npm run test-watch
```

To run a specific JavaScript test, you'll need to copy the full command from `package.json`.

## Further docs

- [Working with static assets](docs/static-assets.md)
- [JavaScript documentation](https://github.com/alphagov/notifications-manuals/wiki/JavaScript-Documentation)
- [Updating dependencies](https://github.com/alphagov/notifications-manuals/wiki/Dependencies)
Change name of app 2015-11-20 10:31:28 +00:00			`# notifications-admin`
Update README.md 2015-11-18 16:32:15 +00:00
Further improvements to readme 2020-05-20 10:52:55 +01:00			`GOV.UK Notify admin application - https://www.notifications.service.gov.uk/`
Update README.md 2015-11-23 14:37:29 +00:00
Add frontend install and build to bootstrap script Now you don’t need to remember what the two commands are and when you need to run them, you can just run the bootstrap script instead. Makes sense to have them here since the `pip install` is also in here. 2016-03-03 07:41:53 +00:00			`- Register and manage users`
			`- Create and manage services`
			`- Send batch emails and SMS by uploading a CSV`
Tidy up README 2016-02-03 15:18:57 +00:00			`- Show history of notifications`
Use a Node-based tools for handling assets …or how to move a bunch of things from a bunch of different places into `app/static`. There are three main reasons not to use Flask Assets: - It had some strange behaviour like only - It was based on Ruby SASS, which is slower to get new features than libsass, and meant depending on Ruby, and having the SASS Gem globally installed—so you’re already out of being a ‘pure’ Python app - Martyn and I have experience of doing it this way on Marketplace, and we’ve ironed out the initial rough patches The specific technologies this introduces, all of which are Node-based: - Gulp – like a Makefile written in Javascript - NPM – package management, used for managing Gulp and its related dependencies - Bower – also package management, and the only way I can think to have GOV.UK template as a proper dependency …speaking of which, GOV.UK template is now a dependency. This means it can’t be modified at all (eg to add a global `#content` wrapper), so every page now inherits from a template that has this wrapper. But it also means that we have a clean upgrade path when the template is modified. Everything else (toolkit, elements) I’ve kept as submodules but moved them to a more logical place (`app/assets` not `app/assets/stylesheets`, because they contain more than just SASS/CSS). 2015-12-15 08:20:25 +00:00
Revise section on setup This is now closer to the recently revised README for the API repo. 2021-02-22 16:56:09 +00:00			`## Setting up`
Use a Node-based tools for handling assets …or how to move a bunch of things from a bunch of different places into `app/static`. There are three main reasons not to use Flask Assets: - It had some strange behaviour like only - It was based on Ruby SASS, which is slower to get new features than libsass, and meant depending on Ruby, and having the SASS Gem globally installed—so you’re already out of being a ‘pure’ Python app - Martyn and I have experience of doing it this way on Marketplace, and we’ve ironed out the initial rough patches The specific technologies this introduces, all of which are Node-based: - Gulp – like a Makefile written in Javascript - NPM – package management, used for managing Gulp and its related dependencies - Bower – also package management, and the only way I can think to have GOV.UK template as a proper dependency …speaking of which, GOV.UK template is now a dependency. This means it can’t be modified at all (eg to add a global `#content` wrapper), so every page now inherits from a template that has this wrapper. But it also means that we have a clean upgrade path when the template is modified. Everything else (toolkit, elements) I’ve kept as submodules but moved them to a more logical place (`app/assets` not `app/assets/stylesheets`, because they contain more than just SASS/CSS). 2015-12-15 08:20:25 +00:00
Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			`### Python version`
Updated Readme.md project setup steps 2020-05-16 16:00:38 -07:00
Update runtime.txt and README.md to Python 3.9 2021-11-02 16:09:56 +00:00			`At the moment we run Python 3.9 in production.`
Updated Readme.md project setup steps 2020-05-16 16:00:38 -07:00
Add .nvmrc & use NVM to manage installed Node version We have decided to use NVM to manage installed Node versions locally and in CI to ensure they match and produce consistent builds. Running `nvm install` will install the Node version specified in the `.nvmrc` file. This is now consistent with Document Download Frontend. See: alphagov/document-download-frontend#114 Signed-off-by: Richard Baker <richard.baker@digital.cabinet-office.gov.uk> 2022-04-05 12:00:26 +01:00			`### NodeJS & NPM`

			`If you don't have NodeJS on your system, install it with homebrew.`
Updated Readme.md project setup steps 2020-05-16 16:00:38 -07:00
node requires brew to install 2017-04-18 14:04:10 +01:00			```shell
Further improvements to readme 2020-05-20 10:52:55 +01:00			`brew install node`
node requires brew to install 2017-04-18 14:04:10 +01:00			```

Add .nvmrc & use NVM to manage installed Node version We have decided to use NVM to manage installed Node versions locally and in CI to ensure they match and produce consistent builds. Running `nvm install` will install the Node version specified in the `.nvmrc` file. This is now consistent with Document Download Frontend. See: alphagov/document-download-frontend#114 Signed-off-by: Richard Baker <richard.baker@digital.cabinet-office.gov.uk> 2022-04-05 12:00:26 +01:00			`nvm` is a tool for managing different versions of NodeJS. Follow [the guidance on nvm's github repository](https://github.com/nvm-sh/nvm#installing-and-updating) to install it.

			`Once installed, run the following to switch to the version of NodeJS for this project. If you don't`
			`have that version, it should tell you how to install it.`
Updated Readme.md project setup steps 2020-05-16 16:00:38 -07:00
			```shell
Add .nvmrc & use NVM to manage installed Node version We have decided to use NVM to manage installed Node versions locally and in CI to ensure they match and produce consistent builds. Running `nvm install` will install the Node version specified in the `.nvmrc` file. This is now consistent with Document Download Frontend. See: alphagov/document-download-frontend#114 Signed-off-by: Richard Baker <richard.baker@digital.cabinet-office.gov.uk> 2022-04-05 12:00:26 +01:00			`nvm use`
Update README No longer need to do init the submodules when first using the app. 2016-01-14 16:26:56 +00:00			```
Fix flakiness with Gulp + Travis Gulp was failing silently on Travis. I tracked this down to the task that builds a custom, slimmed-down version of jQuery from source. To fix this I’ve removed the task and replaced it with just `src`ing the minified version of jQuery from `node_modules`. Cons: - A few more kb of JS Pros: - Less random, afternoon-chewing complexity 2016-01-12 13:37:50 +00:00
Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			### `environment.sh`
Update README.md Co-authored-by: Chris Hill-Scott <me@quis.cc> 2020-05-22 09:48:04 +01:00
			`In the root directory of the application, run:`
Clean up config a bit. Get values for config from environment. Removed some old redundant config. 2016-03-23 14:09:07 +00:00
			```
			`echo "`
handle if user doesn't provide name/email also clean up usage of DESKPRO_PERSON_EMAIL and put it in the conf rather than env 2016-08-04 18:01:08 +01:00			`export NOTIFY_ENVIRONMENT='development'`
remove flask-script flask-script has been deprecated by the internal flask.cli module, but making this carries a few changes with it * you should add FLASK_APP=application.py and FLASK_DEBUG=1 to your environment.sh. * instead of using `python app.py runserver`, now you must run `flask run -p 6012`. The -p command is important - the port must be set before the config is loaded, so that it can live reload nicely. (https://github.com/pallets/flask/issues/2113#issuecomment-268014481) * find available commands by just running `flask`. * run them using flask. eg `flask list_routes` * define new tasks by giving them the decorator `@app.cli.command('task-name')`. Task name isn't needed if it's just the same as the function name. Alternatively, if app isn't available in the current scope, you can invoke the decorator directly, as seen in app/commands.py 2017-11-06 13:07:21 +00:00			`export FLASK_APP=application.py`
Swap FLASK_DEBUG for FLASK_ENV This achieves the same thing and gets rid of the warning about being in a production environment when the app starts up. 2021-02-22 16:54:56 +00:00			`export FLASK_ENV=development`
remove flask-script flask-script has been deprecated by the internal flask.cli module, but making this carries a few changes with it * you should add FLASK_APP=application.py and FLASK_DEBUG=1 to your environment.sh. * instead of using `python app.py runserver`, now you must run `flask run -p 6012`. The -p command is important - the port must be set before the config is loaded, so that it can live reload nicely. (https://github.com/pallets/flask/issues/2113#issuecomment-268014481) * find available commands by just running `flask`. * run them using flask. eg `flask list_routes` * define new tasks by giving them the decorator `@app.cli.command('task-name')`. Task name isn't needed if it's just the same as the function name. Alternatively, if app isn't available in the current scope, you can invoke the decorator directly, as seen in app/commands.py 2017-11-06 13:07:21 +00:00			`export WERKZEUG_DEBUG_PIN=off`
Clean up config a bit. Get values for config from environment. Removed some old redundant config. 2016-03-23 14:09:07 +00:00			`"> environment.sh`
			```

Revise section on setup This is now closer to the recently revised README for the API repo. 2021-02-22 16:56:09 +00:00			`### AWS credentials`
Update README.md 2016-08-17 15:59:16 +01:00
Revise section about AWS setup This is covered in Wiki in more detail. Note that only parts of the app itself (vs the API app) require these credentials. 2021-02-22 16:44:13 +00:00			`To run parts of the app, such as uploading letters, you will need appropriate AWS credentials. See the [Wiki](https://github.com/alphagov/notifications-manuals/wiki/aws-accounts#how-to-set-up-local-development) for more details.`
Clean up config a bit. Get values for config from environment. Removed some old redundant config. 2016-03-23 14:09:07 +00:00
Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			`## To run the application`
Tidy up README 2016-02-03 15:18:57 +00:00
			```shell
Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			`# install dependencies, etc.`
			`make bootstrap`

			`# run the web app`
Switch to 'make' for running app processes These are simple enough that they don't need their own scripts. 2021-02-22 16:41:30 +00:00			`make run-flask`
Tidy up README 2016-02-03 15:18:57 +00:00			```
108536234: created users and roles data and domain model. You will need to run the /scripts/bootstrap.sh to create the database for test and the app. 2015-11-25 15:29:12 +00:00
Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			`Then visit [localhost:6012](http://localhost:6012).`

Rewrite and expand docs on auto-JS scripts This adds a note about automatically re-running JavaScript tests. I've moved and rewritten the old content about re-building JS code to match the new style. 2021-05-11 18:20:40 +01:00			Any Python code changes you make should be picked up automatically in development. If you're developing JavaScript code, run `npm run watch` to achieve the same.

Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			`## To test the application`

			```
			`# install dependencies, etc.`
			`make bootstrap`

Rewrite and expand docs on auto-JS scripts This adds a note about automatically re-running JavaScript tests. I've moved and rewritten the old content about re-building JS code to match the new style. 2021-05-11 18:20:40 +01:00			`# run all the tests`
Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			`make test`
Rewrite and expand docs on auto-JS scripts This adds a note about automatically re-running JavaScript tests. I've moved and rewritten the old content about re-building JS code to match the new style. 2021-05-11 18:20:40 +01:00
			`# continuously run js tests`
			`npm run test-watch`
Revise README to be similar to API app This restructures the sections based on what we agreed for the API repo. 2021-02-22 17:12:03 +00:00			```
Pin all requirements in requirements.txt The list of top-level dependencies is moved to requirements-app.txt, which is used by `make freeze-requirements` to generate the full list of requirements in requirements.txt. (See alphagov/notifications-api#1938 for details.) 2018-07-10 15:16:14 +01:00
Rewrite and expand docs on auto-JS scripts This adds a note about automatically re-running JavaScript tests. I've moved and rewritten the old content about re-building JS code to match the new style. 2021-05-11 18:20:40 +01:00			To run a specific JavaScript test, you'll need to copy the full command from `package.json`.

Revise final sections of the README This makes a few additional changes to curb the length of this file, by moving length documentation (the picture is large) into a separate file, where other documentation could go. It also corrects the section on requirements, and attempts to make it more concise. 2021-02-22 17:15:09 +00:00			`## Further docs`
Add information about how static assets are served This should help developers new to Notify understand how it works. 2018-12-14 16:25:31 +00:00
Revise final sections of the README This makes a few additional changes to curb the length of this file, by moving length documentation (the picture is large) into a separate file, where other documentation could go. It also corrects the section on requirements, and attempts to make it more concise. 2021-02-22 17:15:09 +00:00			`- [Working with static assets](docs/static-assets.md)`
Add .nvmrc & use NVM to manage installed Node version We have decided to use NVM to manage installed Node versions locally and in CI to ensure they match and produce consistent builds. Running `nvm install` will install the Node version specified in the `.nvmrc` file. This is now consistent with Document Download Frontend. See: alphagov/document-download-frontend#114 Signed-off-by: Richard Baker <richard.baker@digital.cabinet-office.gov.uk> 2022-04-05 12:00:26 +01:00			`- [JavaScript documentation](https://github.com/alphagov/notifications-manuals/wiki/JavaScript-Documentation)`
Centralise documentation for updating dependencies This follows the convention established in [1]. [1]: https://github.com/alphagov/notifications-antivirus/pull/83 2021-12-29 15:01:21 +00:00			`- [Updating dependencies](https://github.com/alphagov/notifications-manuals/wiki/Dependencies)`