OpenConext-Access

Coverage report

Getting started

System Requirements

• Java 21
• Maven 3
• Node (nvm)
• Yarn
• Mailpit
• Mariadb / MySql

First install Java 21 with a package manager and then export the correct the JAVA_HOME. For example, on macOS:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-21.jdk/Contents/Home/

Building and running

Database and Maipit

The docker-compose.yaml file in this project is meant for local development and contains a MariaDB and Mailpit instance

You can run docker run -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address ":9001" for a local minio. Note that there is no compatible minio version for the latest mac chip.

docker compose up -d

Then create the MySQL database:

DROP DATABASE IF EXISTS access;
CREATE DATABASE access CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
CREATE USER 'access'@'%' IDENTIFIED BY 'secret';
GRANT ALL privileges ON `access`.* TO 'access'@'%';

Note: in case of an error about COLLATE, omit COLLATE utf8mb4_0900_ai_ci from script above

Access Server

The access server uses Spring Boot and Maven. To run locally, type:

cd server
mvn spring-boot:run

Access Client

The access client uses ReactJS. To run locally, type:

cd client
nvm use
yarn install
yarn dev

Mail

In the default application.properties the mail host is localhost and the port is 1025. Run mailpit to capture mails. See https://github.com/axllent/mailpit

Local endpoints

Login with Mujina IdP and user admin to become superuser in the local environment.

To become an institution admin in access, add the following values as urn:mace:surf.nl:attribute-def:surf-autorisaties using Mujina:

• urn:mace:surfnet.nl:surfnet.nl:sab:organizationGUID:ad93daef-0911-e511-80d0-005056956c1a
• urn:mace:surfnet.nl:surfnet.nl:sab:role:SURFconextverantwoordelijke

Add attribute

If the GUI for maintaining a connection, needs any additional attributes, then the following source files need to be altered:

• access.manage.ConnectionProviderConverter.java#convert
• access.model.Connection.java#mergeMetaData
• utils/Connection.js#convertClientConnectionToServer

Upgrade

To check the pom.xml with the latest versions, run

cd server
mvn versions:display-dependency-updates -DprocessDependencyManagement=false -DdependencyIncludes=*:*

To see the latest versions report for the client run

cd client
nvm use
yarn outdated

Commits, Pull Requests & Changelog

Changelog.md is generated automatically from commit history using git-cliff, so commit messages need to follow the Conventional Commits format:

<type>: <description>

with type one of feat, fix, perf, refactor, docs, chore, ci, build, test, revert. Only feat, fix, perf and refactor end up in the changelog (as Features, Bug Fixes and Improvements respectively); the rest are intentionally left out to keep it user-facing.

For Pull Requests:

• The PR title must follow the same format — it's checked automatically by the PR title lint workflow, e.g. feat: add organization-level contracts.
• Merge with "Squash and merge", using the PR title as the commit message. This keeps the history on main as a clean, one-line-per-change log that the changelog generator can parse, regardless of how messy the commits inside the branch were.
• Reference an issue with #123 in the title or body to have it turned into a link automatically.

Releases are cut via the Prepare Release GitHub Actions workflow (workflow_dispatch, pick a version), which generates the new Changelog.md section, bumps the Maven versions, commits and tags in one go. Changelog.md shouldn't be hand-edited for a release — fix the source commit message instead if an entry is wrong.

Designs

https://www.figma.com/design/81StIVqfOKfwhWVjx7Ew81/SURF-Access?node-id=1916-18441&t=gmckiSapuONmLn5u-4

Minio

exec -it minio bash
mc alias set local http://localhost:9000 minioadmin minioadmin
mc ls local
mc rb --force --dangerous local/s3-images