darkhelm/notifications-admin
1
0
Fork 0
mirror of https://github.com/GSA/notifications-admin.git synced 2026-09-10 01:55:41 -04:00
Code Issues Packages Projects Releases Wiki Activity

Further improvements to readme

Browse Source
This commit is contained in:
David McDonald
2020-05-20 10:52:55 +01:00
parent e57641f992
commit d14510c98c
1 changed files with 54 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
README.md
View File

@@ -1,6 +1,6 @@
# notifications-admin # notifications-admin
GOV.UK Notify admin application. GOV.UK Notify admin application - https://www.notifications.service.gov.uk/
## Features of this application ## Features of this application
@@ -13,126 +13,98 @@ GOV.UK Notify admin application.
### 1. Install Homebrew ### 1. Install Homebrew
Brew is a package manager for OSX. The following command installs brew: Install [Homebrew](https://brew.sh), a package manager for OSX:
```shell ```shell
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
``` ```
This command changes occasionally. You can find the most recent command at [Homebrew](https://brew.sh) ### 2. Make sure you're using correct language versions
### 2. Make Sure You're Using Correct Language Versions
Languages needed Languages needed
- Python 3.6.x - Python 3.6.x
- [Node](https://nodejs.org/) 10.15.3 or greater - [Node](https://nodejs.org/) 10.15.3 or greater
- [npm](https://www.npmjs.com/) 6.4.1 or greater - [npm](https://www.npmjs.com/) 6.4.1 or greater
Need to get node? Run: Need to install node? Run:
```shell ```shell
brew install node brew install node
``` ```
#### 2.1. `n` For Node Version Management #### 2.1. `pyenv` For Python version management
[pyenv](https://github.com/pyenv/pyenv) is a program to manage and swap between different versions of Python. To install:
```shell
brew install pyenv
```
And then follow the further installation instructions in https://github.com/pyenv/pyenv#installation to configure it.
#### 2.2. `n` For Node version management
[NPM](npmjs.org) is Node's package management tool. `n` is a tool for managing [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 long term support (LTS) different versions of Node. The following installs `n` and uses the long term support (LTS)
version of Node. version of Node.
```shell ```shell
npm install -g n npm install -g n
n lts n lts
``` ```
#### 2.2. `nvm` For Node Version Management ### 3. Install NPM dependencies
NVM is also a popular tool for node verison managmement. Install it with Homebrew (instructions can be found with a simple Google search), and make sure you have a Node version installed higher than 10.15.3, and use it. I have arbitrarily chosen version `12.16.2` for this example.
```shell ```shell
nvm use 12.16.2 npm install
npm rebuild node-sass
``` ```
### 3. Install NPM Dependencies ### 4. Install and use `virtualenvwrapper` (optional)
We suggest using a virtualenv to separate the python dependencies for this project from python dependencies for other projects.
Install [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/install.html):
```shell ```shell
npm install pip install virtualenvwrapper
npm rebuild node-sass
``` ```
### 4. Install `virtualenvwrapper` Then follow the [virtualenvwrapper installation instructions](https://virtualenvwrapper.readthedocs.io/en/latest/install.html) docs to configure virtualenvwrapper for your terminal.
You'll need the `pip` package [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/install.html) installed. Installation is pretty easy; run this command for the 3.6.x version of Python you're using for this project: Set up your virtualenv:
```shell ```shell
pip install virtualenvwrapper mkvirtualenv notifications-admin
``` ```
...However, you'll need to configure it to run in your `bash` terminal. Add the following lines to your `~/.bash_profile` **if** you're using `pyenv` to manage your python versions: If you need to specify a certain version of python you can do this using `-p`, for example:
*Note: Python version 3.6.3 is the 3.6.x version arbitrarily chosen for this example.*
```bash
export WORKON_HOME=~/virtualenvs
export VIRTUALENVWRAPPER_HOOK_DIR=$WORKON_HOME/hooks
source ~/.pyenv/versions/3.6.3/bin/virtualenvwrapper.sh
```
If no `~/virtualenvs` directory exists, make one.
If you're using the main system Python version on an OSX machine, your final `~/.bash_profile` line will look more like this:
```bash
source /usr/local/bin/virtualenvwrapper.sh
```
Please see the [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/index.html) website for more installation and configuration info. This step gives you access to `mkvirtualenv` on the command line.
### 5. Setup Virtual Environment
The app runs within a virtual environment. We use `mkvirtualenv` for easier working with `venvs`
**Using Your Machine's System Python:**
```shell
mkvirtualenv -p /usr/local/bin/python3 notifications-admin
```
**Using pyenv:**
*Note: Python version 3.6.3 is the 3.6.x version arbitrarily chosen for this example.*
```shell ```shell
mkvirtualenv -p ~/.pyenv/versions/3.6.3/bin/python notifications-admin mkvirtualenv -p ~/.pyenv/versions/3.6.3/bin/python notifications-admin
``` ```
### 6. Install Python Dependencies Activate your virtualenv:
```shell
workon notifications-admin
```
### 5. Install Python dependencies
Install dependencies and build the frontend assets: Install dependencies and build the frontend assets:
```shell ```shell
workon notifications-admin ./scripts/bootstrap.sh
./scripts/bootstrap.sh
``` ```
**Note:** You may need versions of both Python 3 and Python 2 accessible to build the python dependencies. `pyenv` is great for that, and making both Python versions accessible can be done like so: **Note:** You may need versions of both Python 3 and Python 2 accessible to build the python dependencies. `pyenv` is great for that, and making both Python versions accessible can be done like so:
```shell ```shell
pyenv global 3.6.3 2.7.15 pyenv global 3.6.3 2.7.15
``` ```
### 7. Rebuilding the frontend assets ### 6. Create a local `environment.sh` file containing the following:
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
```
### 8. Create a local `environment.sh` file containing the following:
``` ```
echo " echo "
@@ -143,23 +115,21 @@ export WERKZEUG_DEBUG_PIN=off
"> environment.sh "> environment.sh
``` ```
### 9. AWS credentials ### 7. 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 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
### 10. Running the application ### 8. Running the application
In the root directory of the application, run: In the root directory of the application, run:
```shell ```shell
workon notifications-admin ./scripts/run_app.sh
./scripts/run_app.sh
``` ```
Then visit [localhost:6012](http://localhost:6012) Then visit [localhost:6012](http://localhost:6012)
## Updating application dependencies ## Updating application dependencies
`requirements.txt` file is generated from the `requirements-app.txt` in order to pin `requirements.txt` file is generated from the `requirements-app.txt` in order to pin
@@ -174,6 +144,15 @@ make freeze-requirements
`requirements.txt` should be committed alongside `requirements-app.txt` changes. `requirements.txt` should be committed alongside `requirements-app.txt` changes.
## Automatically rebuild 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
```
## Working with static assets ## Working with static assets
When running locally static assets are served by Flask at http://localhost:6012/static/… When running locally static assets are served by Flask at http://localhost:6012/static/…