Skip to content

README.md

Latest commit

 

History

History
146 lines (100 loc) · 6.42 KB

README.md

File metadata and controls

146 lines (100 loc) · 6.42 KB

Squonk 2 Data Manager UI

build release

test

GitHub tag (latest by date)

Open in GitHub Codespaces

API Compatibility

The Data Manager UI will usually only work with specific API versions. A major version bump in the UI (E.g. 1.x to 2.y) will correspond to a major version change in either the data-manager API or the account-server API.

Compatibility Table

UI DM API AS API
1 1 1
2 1 2
3 2 2
4 3 3
5 4 4
6 5 4

Changes

Checkout the releases for the latest changes or look at CHANGELOG.md.

Development

This project uses pnpm.

Notable scripts:

  • pnpm install to install dependencies. This will also setup husky git hooks via the postinstall script.
  • pnpm dev starts the development server
  • pnpm dev:debug same as above but with the Node debugger running. Start the VSCode debugger to connect.
  • pnpm build will create a production build which includes type-checking and eslint
  • pnpm start starts the production server
  • pnpm tsc will run a one-off type check. This is also called pre-push to ensure no type errors are deployed.
  • pnpm lint will run the linter with the eslint config
  • pnpm format will format specified files with the eslint config
  • pnpm test will run the playwright tests
  • pnpm test:debug runs the tests with debug mode (headed)
  • pnpm test:ci runs the tests but configured for GitHub actions

See package.json for all available scripts.

Assets

The /assets folder is a Git subtree. Manage this with the following commands.

# Add the subtree
git subtree add --prefix assets git@github.com:InformaticsMatters/squonk-assets.git main --squash

# Update the subtree when needed
git subtree pull --prefix assets git@github.com:InformaticsMatters/squonk-assets.git main --squash

Testing

This project uses Playwright for integration and e2e testing. To get this setup install all dependencies:

pnpm i
pnpm exec playwright install-deps
pnpm exec playwright install

Then run:

  • pnpm t to run the tests in headless mode
  • pnpm test:debug to run the tests headed in debug mode

Code Quality

We use a combination of Husky, lint-staged and eslint to format code to a standard style (see the .eslintrc file). Changed lines/files are formatted by when a git commit is made.

Building

Official builds are handled by GitHub Actions and container images pushed to Docker-Hub. Refer to the .github/workflows files to see the official build commands, which can be run from the project clone to produce an nginx web-container: -

$ docker build . \
    --build-arg GIT_SHA=$(git rev-parse HEAD) \
    --tag informaticsmatters/squonk-data-manager-ui:latest

Deployment to Kubernetes is handled by our AWX-compliant Ansible playbook repo.

Local/alternative configuration

A .env file is injected by Kubernetes at run-time that provides values for numerous environment variables. The .env.* used at build time is .env.staging, but this can be changed by using the build-arg FLAVOUR. NextJS loads .env.* files different depending on the Node environment. Read more here. Build the image using

$ docker build . \
    --build-arg FLAVOUR=local.example \
    --build-arg GIT_SHA=$(git rev-parse HEAD) \
    --build-arg BASE_PATH="" \
    --tag informaticsmatters/squonk-data-manager-ui:latest

Which can then be started on http://localhost:8080/data-manager-ui with: -

$ docker run --rm --detach --publish 8080:3000 \
    informaticsmatters/squonk-data-manager-ui:latest

In local development the .env.* can be loaded by copying it into the container and committing it as a image.

  1. Crate the container: docker create --name foo-tmp <temp-tag-name>
  2. Copy the .env.* into the container: docker cp .env. foo-tmp:/app
  3. Commit the container as a new image: docker commit foo-tmp <new-tag-name>
  4. Run this image as above

Releases

We use semantic-release with conventional commits:

  • dev branch → prerelease tags X.Y.Z-dev.N (no v prefix), GitHub prereleases, changelog updates, Docker image push, AWX test deployment.
  • master branch → stable tags X.Y.Z (no v prefix), GitHub releases, changelog updates, Docker image push (including :stable), AWX production deployment.
  • package.json version is kept in sync by semantic-release; no manual bumping.

Workflow summary:

  • release.yml runs on pushes to dev and master, runs semantic-release, pushes tags, builds/pushes Docker images, and triggers AWX (test for prerelease, prod for stable).
  • build.yaml runs a non-pushing build on non-master branch pushes for sanity checks.

If you need a manual prerelease bump, use a conventional commit on dev; semantic-release will compute the next X.Y.Z-dev.N automatically.

Devcontainers

Due to the use of MDX and the node-dependent release mechanism, you will need a full development environment to verify changes by using the development server and to run tests. To aids in this, we provide a devcontainer config file that sets up the needed Node dependencies and allows you to run the tests and dev server. You may open this dev container in browser or inside a supported editor of your choice given you can run the container on your system. It's recommended you use the + New with options option (from the … menu) when starting your codespace so that you can enter the required secrets to get the app running against APIs.