https://github.com/informaticsmatters/squonk2-data-manager-ui
Web UI for the Squonk Data Manager
https://github.com/informaticsmatters/squonk2-data-manager-ui
squonk2
Last synced: 25 days ago
JSON representation
Web UI for the Squonk Data Manager
- Host: GitHub
- URL: https://github.com/informaticsmatters/squonk2-data-manager-ui
- Owner: InformaticsMatters
- License: apache-2.0
- Created: 2020-08-17T14:34:44.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2026-05-19T13:31:00.000Z (25 days ago)
- Last Synced: 2026-05-19T13:58:27.333Z (25 days ago)
- Topics: squonk2
- Language: TypeScript
- Homepage: https://squonk.it/data-manager-ui
- Size: 13.7 MB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 71
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Squonk 2 Data Manager UI
[](https://github.com/InformaticsMatters/squonk2-data-manager-ui/actions/workflows/test.yaml)
[](https://codespaces.new/informaticsmatters/squonk2-data-manager-ui)
## 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](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.
```bash
# 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](https://playwright.dev/) for integration and e2e testing. To get this setup install all dependencies:
```bash
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](https://nextjs.org/docs/basic-features/environment-variables#default-environment-variables).
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 `
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 `
4. Run this image as above
## Releases
We use [semantic-release](https://semantic-release.gitbook.io/) 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](https://mdxjs.com/) 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](.devcontainer/devcontainer.json) 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.
---
[ansible playbook repo]: https://github.com/InformaticsMatters/squonk2-data-manager-ui-ansible
[nginx]: https://hub.docker.com/_/nginx