README.md

[![Requirements Status](https://requires.io/github/alphagov/notifications-admin/requirements.svg?branch=master)](https://requires.io/github/alphagov/notifications-admin/requirements/?branch=master)
[![Coverage Status](https://coveralls.io/repos/alphagov/notifications-admin/badge.svg?branch=master&service=github)](https://coveralls.io/github/alphagov/notifications-admin?branch=master)


# notifications-admin

GOV.UK Notify admin application.

## Features of this application

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

## First-time setup

Brew is a package manager for OSX. The following command installs brew:
```shell
    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```

Languages needed
- Python 3.4
- [Node](https://nodejs.org/) 5.0.0 or greater
- [npm](https://www.npmjs.com/) 3.0.0 or greater
```shell
    brew install node
```


[NPM](npmjs.org) is Node's package management tool. `n` is a tool for managing
different versions of Node. The following installs `n` and uses the latest
version of Node.
```shell
    npm install -g n
    n latest
    npm rebuild node-sass
```

The app runs within a virtual environment. We use mkvirtualenv for easier working with venvs
```shell
    pip install virtualenvwrapper
    mkvirtualenv -p /usr/local/bin/python3 notifications-admin
```

Install dependencies and build the frontend assets:
```shell
    workon notifications-admin
    ./scripts/bootstrap.sh
```

## Rebuilding the frontend assets

If you want the front end assets to re-compile on changes, leave this running
in a separate terminal from the app
```shell
    npm run watch
```

## Create a local environment.sh file containing the following:

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

## AWS credentials

Your aws credentials should be stored in a folder located at `~/.aws`. Follow [Amazon's instructions](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) for storing them correctly


## Running the application

```shell
    workon notifications-admin
    ./scripts/run_app.sh
```

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


## Updating application dependencies

`requirements.txt` file is generated from the `requirements-app.txt` in order to pin
versions of all nested dependencies. If `requirements-app.txt` has been changed (or
we want to update the unpinned nested dependencies) `requirements.txt` should be
regenerated with

```
make freeze-requirements
```

`requirements.txt` should be committed alongside `requirements-app.txt` changes.
Add badges for requirements and code coverage 2016-01-12 09:38:55 +00:00			`[![Requirements Status](https://requires.io/github/alphagov/notifications-admin/requirements.svg?branch=master)](https://requires.io/github/alphagov/notifications-admin/requirements/?branch=master)`
Add code coverage - generates a code coverage report - triggers Coveralls on every Travis build - adds a badge to the README 2016-04-07 10:28:29 +01:00			`[![Coverage Status](https://coveralls.io/repos/alphagov/notifications-admin/badge.svg?branch=master&service=github)](https://coveralls.io/github/alphagov/notifications-admin?branch=master)`
Fix code style 2015-11-23 14:55:37 +00:00
Update README.md 2015-11-18 16:41:49 +00:00
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
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			`GOV.UK Notify admin application.`
Update README.md 2015-11-23 14:37:29 +00:00
Tidy up README 2016-02-03 15:18:57 +00:00			`## Features of this application`
Remove sass dir Update ReadMe with Getting Started directions 2015-11-23 14:31:14 +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
Tidy up README 2016-02-03 15:18:57 +00:00			`## First-time setup`
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
node requires brew to install 2017-04-18 14:04:10 +01:00			`Brew is a package manager for OSX. The following command installs brew:`
			```shell
			`/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
			```

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			`Languages needed`
Update README.md 2016-08-17 15:59:16 +01:00			`- Python 3.4`
Add npm (v3 or greater) as a README dependency Experienced an error to do with the way npm handles its dependency paths. [Basic idea is here](https://docs.npmjs.com/how-npm-works/npm3#npm-v3-dependency-resolution). My npm v2.x.x was failing because it couldn't find my Hogan library. Upgrading npm, nuking `node_modules` and reinstalling/rebuilding finally fixed everything. 2016-11-21 17:24:26 +00:00			`- [Node](https://nodejs.org/) 5.0.0 or greater`
			`- [npm](https://www.npmjs.com/) 3.0.0 or greater`
node requires brew to install 2017-04-18 14:04:10 +01:00			```shell
			`brew install node`
			```

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
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			[NPM](npmjs.org) is Node's package management tool. `n` is a tool for managing
			different versions of Node. The following installs `n` and uses the latest
			`version of Node.`
Update README No longer need to do init the submodules when first using the app. 2016-01-14 16:26:56 +00:00			```shell
Update README.md Added instructions to install n for node version management 2016-01-06 11:14:04 +00:00			`npm install -g n`
Revert "Job stats table" 2017-08-16 15:25:26 +01:00			`n latest`
Update README.md Added instructions to install n for node version management 2016-01-06 11:14:04 +00:00			`npm rebuild node-sass`
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
Update README.md 2016-08-17 15:59:16 +01:00			`The app runs within a virtual environment. We use mkvirtualenv for easier working with venvs`
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			```shell
Update README.md 2016-08-17 15:59:16 +01:00			`pip install virtualenvwrapper`
Tidy up README 2016-02-03 15:18:57 +00:00			`mkvirtualenv -p /usr/local/bin/python3 notifications-admin`
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			```

			`Install dependencies and build the frontend assets:`
			```shell
Update README.md 2016-08-17 15:59:16 +01:00			`workon notifications-admin`
Tidy up README 2016-02-03 15:18:57 +00:00			`./scripts/bootstrap.sh`
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			```

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			`## Rebuilding the frontend assets`
Remove sass dir Update ReadMe with Getting Started directions 2015-11-23 14:31:14 +00:00
Tidy up README 2016-02-03 15:18:57 +00:00			`If you want the front end assets to re-compile on changes, leave this running`
			`in a separate terminal from the app`
			```shell
			`npm run watch`
			```
Update README.md 2015-12-10 16:47:29 +00:00
Clean up config a bit. Get values for config from environment. Removed some old redundant config. 2016-03-23 14:09:07 +00:00			`## Create a local environment.sh file containing the following:`

			```
			`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`
			`export FLASK_DEBUG=1`
			`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`
			```

Update README to include additional installation instructions 2016-09-06 10:22:20 +01:00			`## AWS credentials`
Update README.md 2016-08-17 15:59:16 +01:00
			Your aws credentials should be stored in a folder located at `~/.aws`. Follow [Amazon's instructions](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) for storing them correctly

Clean up config a bit. Get values for config from environment. Removed some old redundant config. 2016-03-23 14:09:07 +00:00
Tidy up README 2016-02-03 15:18:57 +00:00			`## Running the application`

			```shell
			`workon notifications-admin`
			`./scripts/run_app.sh`
			```
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
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			`Then visit [localhost:6012](http://localhost:6012)`
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

			`## Updating application dependencies`

			`requirements.txt` file is generated from the `requirements-app.txt` in order to pin
			versions of all nested dependencies. If `requirements-app.txt` has been changed (or
			we want to update the unpinned nested dependencies) `requirements.txt` should be
			`regenerated with`

			```
			`make freeze-requirements`
			```

			`requirements.txt` should be committed alongside `requirements-app.txt` changes.