Institutional Authorization Platform (IAP)

IAP is a software tool for streamlining research proposal authorization.

It runs as an Apache Sling application (OSGi on Apache Felix, with an Apache Jackrabbit Oak content repository), assembled and launched through the Sling Feature Model. The user interface is a React single-page app.

How the platform works, mechanism by mechanism, is documented in docs/. This file covers building, running and deploying an instance.

Prerequisites

• Java 21
• Maven 3.9+
• Python 3 — the start process is implemented in Python (start.py). Installing the optional psutil module enables a more robust bind check (not used on WSL or macOS, where a simpler check is applied automatically).
• MongoDB — only if you run with --mongo (see below); the default storage needs nothing extra.
• PostgreSQL — only if you run with --postgres (see below); the default storage needs nothing extra.

One-time repository setup (optional)

The repository ships custom diff drivers (better hunk headers and word-diffs for TypeScript and CND files) in a committed .gitconfig. Git never loads in-repository configuration on its own, so enable it once per clone:

git config --local include.path ../.gitconfig

Building

mvn clean install

Tests are skipped by default for fast local builds. Useful Maven flags:

Flag	Effect
-DskipTests=false -Dmaven.test.skip=false	Run the test suites (Java via Surefire, and the frontend Vitest suite in the test phase). Run these before pushing.
-DwebpackArguments=--mode=production	Build the frontend in production mode (default is development).
-Dcheckstyle.skip=true	Skip the Checkstyle checks.
-Denforcer.skip=true	Skip the Maven Enforcer checks.
-Pclean-node	Have clean also delete the downloaded Node toolchain and node_modules, which it keeps by default because re-downloading them every build is slow. Reach for it when a package manager leaves those trees in a state the next install cannot repair.

Running

On Linux, macOS, or WSL:

./start.sh

On Windows (from cmd or PowerShell):

start.bat

Both are thin wrappers around start.py, where all of the start logic lives — they only locate a Python interpreter and delegate to it, so the two platforms cannot drift apart.

IAP will be available at http://localhost:8080 once it has started. Press Ctrl+C to stop it. Runtime state (repository, cache, logs) is written to .iap-data/.

Start options

Option	Description
-p, --port <PORT>	Port to bind to (default 8080).
--data <DIR>	Directory for the runtime state — repository, cache, logs (default .iap-data). Each concurrently running instance needs its own data directory and port; the repository takes an exclusive lock on its data directory, so a second instance pointed at the same one will hang waiting for the lock.
--mongo	Use a MongoDB document store for the repository instead of the default file-based (TAR/segment) store. Requires a running MongoDB instance.
--postgres	Use a PostgreSQL document store for the repository instead of the default file-based (TAR/segment) store. Requires a running PostgreSQL instance and a database the connecting user may create tables in — Oak creates its own tables and indexes on first start. The database must be created with C collation (CREATE DATABASE iap OWNER iap TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C';); with a locale collation the first start succeeds but every restart wedges, see docs/docker.md.
--jdbc <URL>	JDBC URL for --postgres (default jdbc:postgresql://localhost:5432/iap).
--db-user <USER>	Database user for --postgres.
--db-password <PASSWORD>	Database password for --postgres.
--debug	Enable Java remote debugging (JDWP) on port 5005. Startup pauses until a debugger attaches — connect with jdb -attach 5005 (or your IDE).
--test	Additionally load test content (the iap-test-data feature).
--permissions <MODE>	Permissions scheme to apply when resolving project features (used together with --project).
-P, --project <name[,name2,...]>	Launch one or more IAP projects. Each <name> resolves to the iap4<name> artifact and its dependency features (the iap4 prefix is optional).

Notes:

• Any other arguments are passed straight through to the Sling Feature Launcher. The literal token VERSION in an argument is replaced with the current platform version.
• The PROJECT_VERSION environment variable overrides the version used to resolve --project features (it defaults to the platform version).

Examples

./start.sh                 # default: file-based storage on port 8080
./start.sh -p 8888         # run on a custom port
./start.sh --mongo         # use a MongoDB-backed repository
./start.sh --postgres --db-user iap --db-password iap    # use a PostgreSQL-backed repository
./start.sh --debug         # wait for a debugger to attach on port 5005
./start.sh -P myproject    # launch the "iap4myproject" project

# A second instance next to a running one: separate port AND data directory
./start.sh --test -p 8089 --data .iap-data-test

(On Windows, replace ./start.sh with start.bat — the options are identical.)

Deploying to a running instance

Once an instance is up, you can rebuild and redeploy a single bundle in place — without a full restart — using the autoInstallBundle profile. Run it from the directory of the module you want to redeploy:

cd modules/<some-backend-module>
mvn clean install -PautoInstallBundle       # hot-deploys just that module's OSGi bundle

cd aggregated-frontend
mvn clean install -PautoInstallBundle       # rebuilds the frontend and redeploys the UI bundle

The profile uses the sling-maven-plugin to upload the freshly built bundle to the running instance. By default it targets http://localhost:8080 as admin:admin; override with:

Flag	Effect
-Dsling.url=https://host:8443/system/console	Target a different instance (the URL must end with /system/console).
-Dsling.password=<password>	Use a different admin password.

This redeploys code (Java bundles, the frontend JS). It does not re-run a bundle's initial content if that content already exists in the repository. To deploy a new content node — such as a new ext:Extension — into a running instance, post it directly with post-extension.sh, one of the extension-manager dev utilities.

Extending the UI

The user interface is composed of extensions plugged into extension points — the page shell (pinned frame bars and side rails, scrolling page regions), the application bar, the routed views, and the dashboard widgets are all extension points. See docs/ui-extensions.md for the catalogue of available points and recipes for contributing extensions or defining new points.