Skip to content

development.md

Latest commit

 

History

History
89 lines (69 loc) · 4.18 KB

development.md

File metadata and controls

89 lines (69 loc) · 4.18 KB
Raw

The workstation install: from a checkout, and developing

The third of the three ways to run it: the server on your own machine, on DirXMLDev's class path, in its local mode — one tree on disk, no sign-in, no projects or branches (git is yours to run). It is how the server is developed and the quickest look at a tree. For one person in a container see quickstart.md; for a team, hosted-install.md.

Run it

Prerequisites: a built DirXMLDev at the version pom.xml names (dirxmldev.version, 0.11.0 now; its bin/idm doctor is green), JDK 21, Maven 3.9, Node 20 or newer.

# once, in the DirXMLDev checkout: make its jar available to this build
mvn -o install -DskipTests
# once, in the directory-console checkout: console-auth (OIDC sign-in, TLS trust), the version
# pom.xml names (console.version); its jar is also on every directory-console release
mvn install
# once, in this checkout: the server and the page
mvn -o package
cd web && npm ci && npm run build
# serve a tree (import one with `idm import-live`, `import` or `import-ldif`)
bin/idmweb serve /path/to/tree

The build also needs dirxml-simulator in ~/.m2 (mvn install in DirXMLSimulator), which a built DirXMLDev already has, and the DirXML Trace Viewer's library dirxml-trace-core (the version pom.xml names), which does the trace parsing and highlighting. Its jar is on every viewer release; install it with a flat pom, since the pom inside the 1.5.0 jar names a parent you do not have:

V=1.5.0; gh release download v$V --repo PointBlueTechnology/DirXMLTraceViewer -p dirxml-trace-core-$V.jar -D /tmp
printf '<project xmlns="http://maven.apache.org/POM/4.0.0"><modelVersion>4.0.0</modelVersion><groupId>com.pointbluetech</groupId><artifactId>dirxml-trace-core</artifactId><version>%s</version><dependencies><dependency><groupId>com.novell.ldap</groupId><artifactId>jldap</artifactId><version>4.3</version></dependency></dependencies></project>' $V > /tmp/trace-core.pom
mvn -q install:install-file -Dfile=/tmp/dirxml-trace-core-$V.jar -DpomFile=/tmp/trace-core.pom

(or mvn install in a DirXMLTraceViewer checkout at that tag). The launcher adds the jar to the class path; the LDAP classes it needs are JLDAP's, which the launcher takes from ~/.m2 (mvn install in DirXMLDev puts them there). Simulator cases are read from cases/ beside the tree; name another place with --cases DIR. The package catalog is --catalog DIR (or IDM_CATALOG); without one, installed packages are still listed from the tree but nothing can be installed, upgraded or built.

The server prints a URL and opens it. DirXMLDev is found at IDM_HOME, else at ../DirXMLDev. The server runs on that checkout's own classes, engine jars and simulator, so the page sees exactly what bin/idm sees.

Layout

bin/idmweb        launcher (runs on DirXMLDev's class path)
bin/smoke.sh      end-to-end check against a scratch tree
src/main/java     the server: Serve, Api, TreeService, Watcher, Security, StaticFiles
web/              the page: TypeScript, React, Monaco
docs/design.md    assessment and design; phases W0–W7

Tests

mvn -o test            # server unit tests
cd web && npm test     # page unit tests
bin/smoke.sh           # every endpoint, the security gates and the write path, on a real tree

Releasing

A release bumps pom.xml, Serve.VERSION (a test pins the two together) and the CHANGELOG heading, merges --no-ff, tags vX.Y.Z and publishes the jar, the page zip and THIRD-PARTY.md on GitHub. Before tagging, run bin/smoke.sh, bin/smoke-hosted.sh and bin/smoke-container.sh from main. Publishing the release runs .github/workflows/image.yml, which builds the image for amd64 and arm64 from the released jars and pushes it to GHCR. The image build also checks out DirXMLSimulator at the release the pom names, for the sim CLI and the dirxml-policy-testing skill in the agent kit (hosted/agent-kit, assembled by hosted/docker/build.sh).