xorinstall

A small provisioner/installer for JVM services on EC2 / Linux.

It reproduces — in one idempotent command — the manual per-service deployment pattern: create the service's own Linux user, install/upgrade the runtime (Java + cronie, and Maven for the git path), lay down the Cantara semantic-update

• cron deploy machinery, wire the crontab, and do the first download + start. No per-service manifest is required — -group and -artifact are enough.

sudo xorinstall -group no.cantara.tools -artifact visuale
sudo xorinstall -group <groupId> -artifact <artifactId> -user <user>

Install

With npm (recommended):

sudo npm i -g @misterhuydo/xorinstall

Without Node (curl bootstrap → clones to /opt/xorinstall, symlinks /usr/local/bin/xorinstall):

curl -fsSL https://raw.githubusercontent.com/exoreaction/xorinstall/main/install.sh | sudo bash

One-time setup (credentials)

Two ways — pick one:

A. Local file (recommended) — drop a xorinstall.properties in the directory you run xorinstall from. No root needed to manage it, and it travels with your deploy scripts. It overrides the central config.

cp xorinstall.properties.example xorinstall.properties   # then edit

B. setup (interactive) — prompts for the four fields, writes /etc/xorinstall/config (root-only, 0600), and drops a convenience symlink ./xorinstall.properties → /etc/xorinstall/config in the current dir:

sudo xorinstall setup

Fields: RELEASE_REPO, SNAPSHOT_REPO, NEXUS_USERNAME, NEXUS_PASSWORD (blank = anonymous, fine for public release repos). Precedence: ./xorinstall.properties overrides /etc/xorinstall/config.

Install / upgrade a service

sudo xorinstall -group <groupId> -artifact <artifactId> [-user <user>]

• -user is optional; it defaults to the -artifact value.
• If the service user already exists, xorinstall refuses (it looks already installed and re-running would clobber the generated .properties/crontab). The JAR itself upgrades automatically via cron. To reconfigure/reinstall in place, pass --force.

What it does:

1. Install/upgrade Java (Amazon Corretto 21) and cronie (crond) — cronie is not present by default on Amazon Linux 2023, and without it nothing auto-updates.
2. Create the service user (useradd -m) if missing.
3. Drop the deploy scripts into ~user/scripts/, and a su_to_<user>.sh helper in the invoking user's home (quick switch to the service user).
4. Generate ~user/scripts/*.properties from central Nexus creds (+ an optional artifacts/<artifact>.conf), and set -Dapp.home=<home> so a service that reads external config from its home (e.g. Spring file:${app.home}/application.properties) works with no manifest — just drop that config file in ~user/.
5. Install the per-user crontab (@reboot start + update-if-new every 3 min).
6. First semantic_update (download jar) + start-service.

Reboot: the service auto-starts on boot — crond is enabled at boot, the crontab persists, and a @reboot entry starts it immediately (the 3-min job is the backstop).

Service config (-config): for a service that needs its own application.properties (DB creds, ports, …), pass -config <file> — xorinstall installs it into the service home (0600), picked up via -Dapp.home. Only applied when given, so a plain --force never overwrites a config you placed by hand.

Managing services

sudo xorinstall list                      # user · artifact · version-pattern · running version · up?
sudo xorinstall uninstall <user>          # stop + remove crontab & su_to helper (keeps the home)
sudo xorinstall uninstall <user> --purge  # also delete the user + home (jars, scripts, config)

Health reporting is off unless you pass -health <url> — see Health reporting below.

Install/upgrade just the runtimes:

sudo xorinstall prereqs --upgrade      # Java + Maven + cronie (crond)

Artifact manifests (optional)

Manifests are optional — -group/-artifact alone install a service. A manifest only adds extras: a health endpoint (HEALTH_URL), custom JVM_ARGS, or a VERSION_PATTERN. When present, per-service parameters are declarative, under artifacts/<artifact>.conf:

GROUP_ID=no.cantara.tools
ARTIFACT_ID=visuale
VERSION_PATTERN=*
HEALTH_URL=localhost:8080/health   # local endpoint the health report polls (only with -health)
JVM_ARGS=

HEALTH_URL is the local health endpoint the reporter polls — it does not set the service's listening port (that's the service's own application.properties → server.port).

Add a file here (or in the overlay) only if you need those extras. --version-pattern overrides at the CLI.

Private / site-specific manifests don't need a fork: drop <artifact>.conf files in the operator overlay /etc/xorinstall/artifacts/ (or $XORINSTALL_ARTIFACTS_DIR). Lookup order is overlay → built-in artifacts/, so the overlay wins. This keeps the published tool generic while your own services stay out of the repo.

The deploy model it reproduces

One Linux user per service. Each user's home holds the versioned jars, a <artifact>.jar symlink → newest, its application.properties, and scripts/:

| Script | Role | |---|---| | semantic_update_service.sh (+.properties) | Poll Nexus maven-metadata.xml, resolve latest matching VERSION_PATTERN, download jar if new, repoint symlink, keep 4 newest | | download_and_restart_if_new.sh | cron entry: update-if-new → kill + start; restart if down | | start-service.sh / kill-service.sh | nohup java $JVM_ARGS -jar <artifact>.jar & / pkill -9 java (per-user) | | reportServiceHealthToVisuale.sh (+.properties) | Health ping → visuale |

Cron (per user): update + health report every ~3 min; nightly cron.log cleanup.

Health reporting (optional)

Health reporting is off unless you pass -health <url>. The destination must be a Visuale instance you run — Visuale is an open-source real-time service dashboard (Cantara/visuale). Do not point it at someone else's Visuale server.

The robust path: install Visuale with xorinstall itself — it's just another Nexus artifact (no.cantara.tools:visuale) and ships as a built-in manifest:

sudo xorinstall -group no.cantara.tools -artifact visuale     # runs Visuale on :8080

Then enable reporting per service by PUT-ing to your Visuale's status API (/api/status/<env>/<service>/<node>?service_type=<T>&service_tag=<Tag>):

sudo xorinstall -group <groupId> -artifact <artifactId> \
     -health 'https://<your-visuale-host>/api/status/prod/<service>/node1?service_tag=MyGroup&service_type=ACS'

(v2 git equivalent, once implemented: xorinstall https://github.com/Cantara/visuale.)

Roadmap

• v1 (this release): install/upgrade from a Nexus Maven repo.
• v2 (planned): install/upgrade from a git repo — xorinstall [email protected]:<org>/<repo>.git / xorinstall https://github.com/<org>/<repo> → clone, Maven build, run, and auto-upgrade on new commits. Multiple git auth methods (SSH token, deploy keys, https token).

Upgrading xorinstall itself

xorinstall upgrades in place — including the v1 → v2 jump (v2 is just a newer release of this same package):

sudo xorinstall self-update          # auto-detects npm vs git install
# equivalent, explicit:
sudo npm i -g @misterhuydo/xorinstall@latest          # if installed via npm
sudo git -C /opt/xorinstall pull --ff-only            # if installed via the curl bootstrap

xorinstall --version prints the installed version. Already-installed services are unaffected — they keep auto-updating their own artifacts via cron.

Security notes

• Nexus creds live only in /etc/xorinstall/config (root 0600) and the generated semantic_update_service.properties (service-user 0600).
• Assumes one service per user so pkill -9 java stays scoped.
• Runs as root (creates users, installs packages, writes crontabs) — audit before use.