Skip to content

DEVELOPERS.md

Latest commit

 

History

History
149 lines (100 loc) · 4.61 KB

DEVELOPERS.md

File metadata and controls

149 lines (100 loc) · 4.61 KB

Notes for developers

Deployment

Deployment uses dokku and requires the environment variables defined in dotenv-sample. It is deployed to our dokku3 instance (see dokku docs).

Local development

Prerequisites:

  • Python v3.12.x
  • Pip
  • Node.js v20.x (fnm is recommended)
  • Just

Install just

# macOS
brew install just

# Linux
# Install from https://github.com/casey/just/releases

# Add completion for your shell. E.g. for bash:
source <(just --completions bash)

# Show all available commands
just #  shortcut for just --list

Build the assets:

See the Compiling assets section.

Set up/update local dev environment

just dev-setup

Run local development server

The development server can be run locally, as described below, or in docker.

Run local django server

just run

Delete local database and cache and repopulate db

just dev-reset

Access at http://localhost:8000

Manually add a report

To add a report in local development:

  1. Log into the admin with username admin and password admin.
  2. Under Reports section, click Reports.
  3. Click Add Report and complete the form.
  4. In the Report file details section, enter a valid Job Server URL(example URL).
  5. Set the category to Reports for a standard report, or Archive for an archived report.
  6. If the Archive category does not exist, go to Categories in the Reports section and add it first.

Run tests

# all tests and coverage
just test

# run specific test with usual pytest syntax
just test <path/to/test>::<test name>

CSS and JS local development

This project uses Vite, a modern build tool and development server, to build the frontend assets. Vite integrates into the Django project using the django-vite package.

Vite works by compiling JavaScript files, and outputs a manifest file, the JavaScript files, and any included assets such as stylesheets or images.

Vite adds all JavaScript files to the page using ES6 Module syntax. For legacy browsers, this project is utilising the Vite Legacy Plugin to provide a fallback using the module/nomodule pattern.

Running the local asset server

Vite has a built-in development server which will serve the assets and reload them on save.

To run the Vite server locally, after completing the local dev env setup:

  1. Set ASSETS_DEV_MODE = True in reports/settings.py
  2. Open a terminal and run Django with just run
  3. Open a new terminal tab or window
  4. Run npm run dev to start the vite server
  5. Any changes you make in the assets/ folder will now be updated without requiring a page refresh

This will start the Vite dev server at localhost:3000 and inject the relevant scripts into the Django templates.

Compiling assets

To view the compiled assets:

  1. Update the .env file to ASSETS_DEV_MODE=False
  2. Run just assets-rebuild

Vite builds the assets and outputs them to the assets/dist folder.

Django Staticfiles app then collects the files and places them in the staticfiles/assets folder, with the manifest file located at staticfiles/manifest.json.

Using docker for development and tests

Run a local development server in docker:

just docker-serve

Run the tests in docker

just docker-test

To run named test(s) or pass additional args, pass paths and args as you normally would to pytest:

just docker-test tests/reports/test_models.py::test_report_model_validation -k some-mark --pdb

Run a command in the dev docker containter

just docker-run <command>

Rotating the GitHub token

  1. Log into the opensafely-readonly GitHub account (credentials are in Bitwarden).
  2. Got to the Personal access tokens (classic) page.
  3. Click on reports-private-repo-token.
  4. Click "Regenerate token".
  5. Set the expiry to 90 days.
  6. Copy the new token.
  7. ssh into dokku3.ebmdatalab.net
  8. Run: dokku config:set reports GITHUB_TOKEN=<the new token>