Project Structure
Core Repos
- https://github.com/renalreg/ukrdc-fastapi
- API interface to data
- Python, FastAPI, Pydantic
- https://github.com/renalreg/ukrdc-nuxt
- Frontend client app
- Nuxt (Vue.js), Typescript, Tailwind
- https://github.com/renalreg/ukrdc-compose
- Reference Docker Compose for deployment
Auxiliary repos
- https://github.com/renalreg/python-mirth-client
- Async client for Mirth API
- https://github.com/renalreg/ukrdc-sqla
- Minimal SQLAlchemy models for the UKRDC
Auth management
- https://renalregistry-admin.okta.com/admin/dashboard
- Non-admins can manage accounts at https://renalregistry.okta.com
Issue trackers
- https://jira.ukrdc.org/projects/UI/summary
- Project-wide issue trackers
Sentry
UKRDC-FastAPI
- See ARCHITECTURE.md
Pydantic and Type Hints
- Familiar with MyPy and Python type-hints?
- Our data goes through 2 “conversions”:
- SQLAlchemy ORM turns database rows into Python objects
- Pydantic (via FastAPI response_model) turns Python objects into JSON
UKRDC-Nuxt
- See ARCHITECTURE.md
TypeScript
- Have others used TS before?
- Initially it often just looks like a source of frustration, but it does a tonne of good for catching errors early on
- Interfaces are roughly equivalent to Pydantic models. They give the expected fields and types for objects (JS dictionaries)
Tailwind
- One of the most divisive web dev libraries I’ve ever come across
- I’ve found it excellent for rapidly developing new components
- We abstract a lot of styling away at the component level
- E.g. we have a “TextH1” component which acts a lot like html “h1” but with extra styling
- This means we can easily bulk-change styles across the whole application without a web of CSS files
Docker-Compose
- We use Docker images to deploy the applications
- I’m assuming everyone is familiar with Docker but if not let me know and I’ll run through why we use it
- Docker images can have tags, so we use these to separate environments (dev, staging, production etc)
- Our Docker-Compose file pulls and configures all images required to run the whole stack
- Runtime configuration is handled by .env files or environment variables
Devops Flow
Branches
- Main
- Current "snapshot" branch
- Code here should be as stable as possible
- Code should not be committed directly
- Base for feature/fix branches
- Feature branches
- When working on a specific feature/fix, create a new branch for that work item
- Either submit a PR when ready, or create a draft PR whenever
- PRs should pass all tests and code-quality checks before merging
- PRs should be reviewed by someone else on the project before merging
GitHub Actions
- All testing and build automation is handled by GitHub Actions
- If you’ve used Bamboo it’s the same thing but with a sensible configuration system
- Example config file:
How to deploy a new release
Build and publish Docker images
This guide is broadly applicable to both "ukrdc-fastapi" and "ukrdc-nuxt"
- Create a new GitHub Release, or push a tag
- The tag and release should be named as the approximate release datetime, in the format YYYY-MM-DD-HHMM
- E.g. 2021-11-22-1410 for a release made on November 22nd 2021 at 14:10
- A docker image will be published with 2 tags, the version number, and 'latest'
Update containers on the app server
- Once the image has been published, connect to the app server via SSH
- Run:
cd /srv/ukrdc-compose
docker-compose pull
docker-compose down
docker-compose up -d
- Ideally also run
docker system prune
- You can view real-time logs from the entire stack with:
docker-compose log -f
Reverting/redeploying an old version
- Modify your docker-compose file, and instead of pointing to the image tag 'latest', point to a specific version tag.
Active Instances
- staging-app and live-app both include new UKRDC instances
- /srv/ukrdc-compose/
- In both cases, the host nginx config needs to be set up to forward to the Docker stack
- E.g. /etc/nginx/conf.d/staging-app.ukrdc.nhs.uk.conf
- This should not need to be changed unless we want to change the new stack base URL