Giter Club home page Giter Club logo

notifications-local's Introduction

notifications-local

A docker compose file, and associated configuration, to run GOV.UK Notify locally in development mode.

This README needs some love and may not be in an intuitive order. Please read the entire document top-to-bottom before trying to set up your environment. Please update this README if you think something is missing, in the wrong place, or poorly described =)

Initial setup

  1. Clone this repository alongside your existing Notify repositories (if any).

    [email protected]:alphagov/notifications-local.git
    cd notifications-local
    
  2. We need to have quite a few repositories checked out to run a full copy of GOV.UK Notify. A helper script is provided to make sure these are checked out locally (and check them out if they're not), then do some initial setup.

    Run this script:

    ./clone-repos.sh

    Manually make sure that each of those repositories are on the main branch and on the latest commit.

  3. Each of the services needs to have some environment variables defined. We have template .env files in the root of the repository a helper script automates generating real .env into the ./private directory files from those templates, prompting for input as required. These should obviously never be committed and is excluded in .gitignore.

    You will need the full path of your checked-out credentials repository (cd to it and run pwd), your SQS queue prefix from notifications-api/environment.sh, and your AWS access key/secret key from ~/.aws/credentials

    Run this script and follow the instructions:

    ./generate-env-files.sh
  4. Update your /etc/hosts file to handle DNS resolution for our local hostnames:

    echo "127.0.0.1       notify.localhost notify-api.localhost api.document-download.localhost frontend.document-download.localhost template-preview-api.localhost antivirus-api.localhost" | sudo tee -a /etc/hosts
  5. This step is only required if you are switching to running GOV.UK Notify via docker compose from the old way, where things were all run natively. To keep your local DB data, we need to copy it across to the docker DB service.

    1. Make sure local postgres service is running (on standard port 5432)
    2. Run docker compose up -d db to start docker postgres.
    3. Connect to docker's postgres with psql postgresql://notify:notify@localhost:5433/postgres and run:
      1. drop database notification_api;
      2. create database notification_api;
    4. Run pg_dump -d notification_api | psql postgresql://notify:notify@localhost:5433/notification_api to copy local postgres to docker postgres
    5. If you login locally with yubikey, update your user's auth_type to email_auth temporarily: psql postgresql://notify:notify@localhost:5433/notification_api -c "update users set auth_type='email_auth' where email_address='EMAIL_ADDRESS'"
    6. Run docker compose down
  6. Run docker compose build to make sure all the containers have been built and are up-to-date.

Running/accessing services

The default way to bring up a local version of GOV.UK Notify, after following setup, is to run make up from the root of this repository. This will start notify-api, notify-api-celery, notify-admin, template-preview-api, template-preview-celery, document-download-api, and document-download-preview, which will cover 95%+ of the things you need.

To also run and enable antivirus scanning, run make antivirus up. To run and enable celery-beat for regularly-scheduled tasks, run make beat up. To run and enable the sms-provider-stub, run make sms-provider-stub up. These can be combined to make beat antivirus sms-provider-stub up to run everything.

Accessing your local Notify services

Your GOV.UK Notify services are available at the following URLs:

  • notify-api: http://notify-api.localhost:6011
  • notify-admin: http://notify.localhost:6012
  • template-preview-api: http://template-preview-api.localhost:6013
  • antivirus-api: http://antivirus-api.localhost:6016
  • document-download-frontend: http://frontend.document-download.localhost:7001
  • document-download-api: http://api.document-download.localhost:7000

Debugging containers

When running, the applications should all hot reload on code changes. This means you can add breakpoints into the code anywhere, and when that line is executed, the application will pause and start a debugger. To attach to the debugger you will need to open a separate terminal and run docker attach <container>, eg docker attach notify-api.

Importantly, to detach you should enter the control sequence Ctrl-P Ctrl-Q, not Ctrl-C which will kill the Flask app.

Updating dependencies in the containers

There is two ways you can update dependencies for a container.

  1. If the container is up and running, you can go into it and update dependencies from inside of it, like:
docker exec -it <container-name> make bootstrap
  1. If the container is crashing, or you want to update dependencies while it's not running, you can use docker compose for it, like so:
docker compose build <container-name>

Useful docker aliases

When using docker compose to run GOV.UK Notify, you may fairly frequently need to interact with the docker containers, and so typing out standard docker commands in full every time can get a bit repetitive. These may be some useful aliases to set up:

alias dc='docker compose'
alias da='docker attach'
alias de='docker exec -it'

For example, if you've added a breakpoint into one of the apps and you've triggered it, instead of typing docker attach notify-admin you can type da notify-admin. Or if you want a shell inside of one of the app containers to run arbitrary commands - eg install local utils, re-build frontend assets, etc - you can run de notify-admin bash instead of docker exec -it notify-admin bash.

Todo

  • Investigate antivirus-api slow startups
  • Get frontend assets hot rebuilding for notify-admin and document-download-frontend. Until then, you can run docker exec -it notify-admin npm run build for an ad-hoc recompile, or docker exec -it notify-admin npm run watch to spin up a long-lived watcher process. Optionally add a -d flag to detach from the process and leave it running it the background.
  • Investigate amd/arm docker images for antivirus and template-preview
    • antivirus-celery The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
    • template-preview-api The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
    • antivirus-api The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
    • template-preview-celery The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s

notifications-local's People

Contributors

corlettb avatar crystalpea avatar idavidmcdonald avatar leohemsted avatar risicle avatar rjbaker avatar robbrazil avatar sakisv avatar samuelhwilliams avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Forkers

worth-nl

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.