Notify has been around since 2015 and has quite a few repos. Most of the repos are Python and similar to each other, so you only need to setup one or two to get the gist. Here are some pointers if you want to get a bit more context:

• 👉 Take a look at the architecture of Notify.
• 👉 Read a few of the past blogs, like the first one and more recent ones.
• 👉 Try sending an email / SMS with the preview site.
• 👉 Watch a video of how a text message is sent

The generally-supported way of running Notify as a developer is now through the notifications-local repository. This provides a docker-compose file and assorted helper scripts to assist with getting set up quickly and reliably.

You should be able to use this to get bootstrapped quickly.

As a tech team we expect this to be the supported way forward for most development. However, see below for how to set up most apps to run natively on your machine, which may be useful for advanced use or some edge cases. Where this is required, please flag it within the tech team so that we can try to solve the use-case via the dockerised approach.

You will need the following (on a Mac):

• Homebrew to manage packages
• pyenv to manage Python versions (brew install pyenv)
• Docker for repos with fiddly dependencies
• Postgres for database management
• gds-cli to check your AWS access

You'll need to check the README for each repo to see if it has any other specific prerequisites e.g. Python version, database, NPM.

You should change your Docker settings so it has a generous proportion of system resources available to it, in case it needs them. Our suggestion is to give it 6 CPUs, 12GB RAM, 3GB swap.

Install Postgres.app.

The API (on notify) works with PostgreSQL 15. After installation, open the Postgres app, open the sidebar, and update or replace the default server with a compatible version.

Note: you may need to add the following directory to your PATH in order to bootstrap the app. If you want to have a specific version, then adjust the command, substituting 'latest' by the desired version

export PATH=${PATH}:/Applications/Postgres.app/Contents/Versions/latest/bin/

It's advisable to use a virtual environment for each project, to avoid dependency clashes where different repos are using different versions. There are several options here, but we prefer pyenv-virtualenv as it works seamlessly with pyenv.

• pyenv-virtualenv (recommended).

  • Make a new environment with e.g. pyenv virtualenv 3.11.7 notifications-admin and use it with pyenv local notifications-admin.
  • Setup a global .gitignore file and run echo .python-version >> ~/.gitignore to avoid the version lockfiles turning polluting your Git diffs.

• virtualenvwrapper.

  • Make a new environment with e.g. mkvirtualenv notifications-admin and use it with workon notifications-admin.

Example:

## navigate to the project directory
~ cd notifications-api 

## update the local repository with the latest changes from the main branch
~ git pull origin main 

## check to see if you have system python installed
~ python --version 

## check if pyenv-virtualenv is installed and set up
~ pyenv virtualenv 

## list all python versions and virtual environments managed by pyenv
~ pyenv versions 

## check if there is a file specifying the python version for this project
~ cat /path/to/your/project/notifications-api/.python-version 

## install the specified python version using pyenv
~ pyenv install 3.11.7 

## create a virtual environment for the specified python version
~ pyenv virtualenv 3.11.7 

## create a virtual environment named notifications-api-3.11.7 using python 3.11.7
~ pyenv virtualenv 3.11.7 notifications-api-3.11.7 

## activate the virtual environment named notifications-api-3.11.7
~ pyenv activate notifications-api-3.11.7 

## verify that the active python version is the one installed in the virtual environment
~ python --version 

## inside your virtual env set up pycurl
~ brew install curl [email protected]

~ PYCURL_SSL_LIBRARY="openssl" \
LDFLAGS="-L/opt/homebrew/opt/[email protected]/lib" \
CPPFLAGS="-I/opt/homebrew/opt/[email protected]/include" \
pip install --ignore-installed pycurl==<**VERSION_IN_REQUIREMENTS_TXT**> --global-option="--with-openssl" --global-option="--openssl-dir=/opt/homebrew/opt/[email protected]"

# check if it works - should not error
~ python -c "import pycurl; print(pycurl.version)"

Installing pycurl is a common problem in several of our repos.

When you setup a new virtualenv, you may need to install it separately (adapted from a gist):

brew install curl [email protected]

PYCURL_SSL_LIBRARY="openssl" \
LDFLAGS="-L/opt/homebrew/opt/[email protected]/lib" \
CPPFLAGS="-I/opt/homebrew/opt/[email protected]/include" \
pip install --ignore-installed pycurl==<VERSION_IN_REQUIREMENTS_TXT> --global-option="--with-openssl" --global-option="--openssl-dir=/opt/homebrew/opt/[email protected]"

# check if it works - should not error
python -c "import pycurl; print(pycurl.version)"

On older macbooks/brew versions/something, the openssl path may be different. You can check it with brew info [email protected]. In a previous version of this wiki page it was /usr/local/opt/curl/lib - so try substituting that in if the above doesn't work.

Here are a few suggested steps to get you familiar with the apps.

1. Clone the notifications-api and notifications-admin repos and follow the READMEs to get the tests passing locally. These are representative examples of other Notify projects.

2. Complete the joiners process. Some repos need access to remote APIs in development/test e.g. to send email. You will need:

   • 👉 Access to credentials to get various API keys
   • 👉 Access to AWS to run apps against AWS APIs

3. Follow the instructions in the Notifications API / Admin READMEs to get both apps running locally. Test this works by signing in to the Notifications Admin app (http://localhost:6012) and sending a test email / SMS.

   • You may want to make yourself a Platform Admin so you can access all the functionality. To do this, run: psql notification_api -c "update users set platform_admin = true where email_address = '<your email>'".

4. Clone the notifications-functional-tests repo and follow the instructions to get the tests passing with your local environment. This will lead you to set up a bunch of other apps and get more familiar with Notify as a whole.

5. Now that you have more apps running, you can also test sending a letter locally. Try creating a new letter template, viewing the preview, and sending it. Note: letters only actually send in production.

6. Clone the notifications-python-client repo and get the unit and integration tests passing. You'll need to do some additional setup for the integration tests, which run against the preview environment.