ARON management scripts

Scripts that install, update, run and back up ARON — the public portal presenting archival records (Archiv online, new generation), fed with data by the separate Transfagent application — on a Linux host. They are built on the shared LightComp deployment engine; one config file (aron-env) holds everything environment-specific, so the same scripts serve TEST and PROD.

Before you start

• Java 21 (a JRE is enough), unzip and curl on the host.
• PostgreSQL with a database owned by a dedicated role. The schema itself is created and upgraded by the application at startup:

  create user aron with password '…';
  create database aron owner = aron;

• Elasticsearch — optional. It is the production search engine; without it the portal runs its embedded Lucene engine (search.engine: lucene in application.yml), which serves the current portal API fully and the frozen legacy search API in reduced quality. No Elasticsearch plugins are needed either way.
• A service account the portal runs as (default aron):

  sudo useradd --system --home-dir /opt/aron --no-create-home --shell /sbin/nologin aron

Install

On the target host, as a user with sudo:

curl -fsSL https://get.lightcomp.com/aron/aron-bootstrap.sh | bash -s -- --home /opt/aron

This downloads the script bundle (checksum-verified) into /opt/aron/scripts, renders the product-named commands and systemd units, and seeds the configuration file. Then:

1. Edit /opt/aron/scripts/aron-env — uncomment only the values that differ from the defaults (database, HEALTH_URL, CSC account …). Recommended: HEALTH_URL=http://127.0.0.1:8080/actuator/health, so a deploy waits until the new version really serves before it reports success.
2. If the file holds the CSC secret, restrict it — but keep it readable for the app user (the backup and health services read it as aron through the file's group; do not use chmod 600):

   sudo chgrp aron /opt/aron/scripts/aron-env
   sudo chmod 640 /opt/aron/scripts/aron-env

3. Check the resolved configuration: /opt/aron/scripts/aron-deploy --show-config
4. Install the application unit (rendered for your install path and user — no editing). Enable it; there is nothing to start yet:

   sudo cp /opt/aron/scripts/systemd/aron.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable aron.service

5. Deploy the first release:

   sudo /opt/aron/scripts/aron-deploy --auto

   (or a specific version: aron-deploy 2.0.0). The release is downloaded into /opt/aron/releases/<version> and its default configuration is copied into /opt/aron/config; the deploy then stops on purpose: the application's own application.yml does not exist yet.
6. Create it from the template and edit it — at a minimum the database connection (spring.datasource), the data directories (files.storage, files.transfer.path, tile.folder) and the search engine (search.engine); every key is described in the template. It holds the database password, so restrict it like aron-env:

   sudo cp /opt/aron/config/application.yml.template /opt/aron/config/application.yml
   sudo vi /opt/aron/config/application.yml
   sudo chgrp aron /opt/aron/config/application.yml && sudo chmod 640 /opt/aron/config/application.yml

7. Run the deploy again — it continues where it stopped, activates the release and starts the service:

   sudo /opt/aron/scripts/aron-deploy --auto

   Verify: systemctl status aron, journalctl -u aron -f (the portal logs to its journal) and curl http://localhost:8080/actuator/health.

Add --channel main to the install command for the latest (snapshot) scripts instead of stable; the choice is remembered for updates.

Layout on the host

/opt/aron/
  scripts/          the management scripts (aron-deploy, aron-backup, …) + aron-env
  releases/<ver>/   one unpacked release: aron.jar + the default config/ it shipped
  current ->        the active release (symlink flipped by aron-deploy)
  config/           THIS deployment's configuration — application.yml and the files
                    it names (types.yaml, searchConfig.yaml, pageTemplate.yaml, images/ …)
  data/             file storage, tiles, transfer directory, embedded search index
                    (wherever application.yml points; the template's ./data/… lands here)
  backup/           database dumps and pre-update configuration archives

The service runs current/aron.jar with /opt/aron as its working directory, which is how the relative ./config/… and ./data/… paths of the template resolve outside any release — a deploy replaces the jar and never touches your configuration or data.

Application configuration

Separate from the deploy config above, the portal is configured by the files in /opt/aron/config. A release ships a complete default set for a Czech archive — the display model (types.yaml), the search facets (searchConfig.yaml), the structured result layout with its icons, the page template, citation forms, news and favourite queries, and placeholder branding — and the first deploy copies it there. It works as it stands, so this is editing, not authoring. Make it your own:

• pageTemplate.yaml — the portal name, the menu, the footer links (a public-sector body publishes its accessibility statement there; the shipped links point at example.org).
• logo.svg, topImage.png — neutral placeholders, replace them with your branding.
• help-url in application.yml — the target of the HELP menu item.
• types.yaml, searchConfig.yaml — the display model and the facets follow the Czech national description standard and usually need no change, but they must match the description items the source system actually delivers.

How a new release treats your configuration

Before every activation aron-deploy compares the configuration the new release ships with the one the previously active release shipped, and applies the rule Debian uses for configuration files:

• a file that changed upstream follows the release if you never modified your copy — a fixed icon or an improved facet reaches you without any action;
• a file you modified is kept and reported (WARN … kept (modified here; merge …)), so you merge the upstream change by hand from releases/<version>/config;
• a file new in the release is added; a file you deleted is not restored; a file removed upstream stays.

Before anything is replaced, the whole config/ is archived into /opt/aron/backup/config-<timestamp>-preupdate-…tar.gz. Set SHIPPED_CONFIG_UPDATE=off in aron-env to get the report only and copy nothing. The rule never touches application.yml — no release ships one — and a fresh application.yml.template arrives next to yours to diff against.

Reverse proxy

The same jar serves the portal at the root of a URL and under a subpath without a rebuild: set server.servlet.context-path, or send X-Forwarded-Prefix from the proxy. Two rules for a public deployment:

• Never forward /cxf/** — the internal SOAP interfaces Transfagent uses for data ingest and withdrawal. Optionally set soap.port (and soap.address) in application.yml to move them to their own, internal listener.
• Decide explicitly whether /actuator/** is reachable from the outside; usually it is restricted to the monitoring network.

The full administrator guide (configuration reference, search engines, index lifecycle, operations) is part of the ARON sources, see the footer.

Upgrading

1. Updating the scripts themselves

Re-run the installed bootstrap — no arguments needed. It locates the installation from its own path, keeps the channel it was installed from and never overwrites your aron-env. When the published build is unchanged nothing is downloaded (safe to run as often as you like):

/opt/aron/scripts/aron-bootstrap.sh

2. Updating the application

sudo /opt/aron/scripts/aron-deploy --auto

The flow is: download + verify the release → configuration check (above) → stop service → pre-update DB backup → activate the new release (atomic symlink switch) → start → wait until healthy. The result is reported to the LightComp Customer Service Center (CSC) when an account is configured.

• With a CSC account (CUSTOMER_ID + CUSTOMER_SERVICE_SECRET in aron-env), --auto installs the version confirmed for this instance in the CSC portal — confirming there is how you control the rollout.
• Without an account, --auto follows the public stable channel.
• The pre-update dump (…-preupdate-…dump in /opt/aron/backup) is the rollback anchor; the newest ones are kept regardless of age.
• After the start, the portal upgrades its database schema and, when the indexed-fields configuration changed, rebuilds the search index from the database on its own — expected, logged, and harmless (the index is derived data).

Downgrade warning: switching back to an older release is not a safe rollback by itself — the database schema is migrated forward on startup. Restore the matching pre-update dump first (and the matching configuration archive, if the deploy replaced any shipped file).

3. Unattended updates

Install the aron-update service (below), then enable per instance in aron-env:

AUTOUPDATE=on

The timer checks hourly and applies a newly confirmed version outside working hours (default Mo-Fr 06:00-18:00, configurable via AUTOUPDATE_WORKHOURS; set it empty to update any hour — typical for TEST instances, see the preset in aron-env).

Setting up the services (systemd)

The bundle ships unit files in /opt/aron/scripts/systemd/, already rendered at install with your install path and the aron service account filled in — copy and enable, no editing. Each service is a separate decision; install only what the instance needs.

Application — aron.service

Required on every instance; installed in Install, step 4. The heap is -Xmx2G; change it — like anything else in the unit — with a drop-in rather than by editing the file, so a re-rendered unit never overwrites your choice:

sudo systemctl edit aron.service    # opens an override; e.g.
[Service]
ExecStart=
ExecStart=java -Xmx4G -jar /opt/aron/current/aron.jar

With Elasticsearch on the same host, order the portal after it: the search index is checked at startup and the portal does not start while Elasticsearch is unreachable.

sudo systemctl edit aron.service
[Unit]
After=elasticsearch.service
Wants=elasticsearch.service

Verify: systemctl status aron; application log: journalctl -u aron.

Database backup — aron-backup

Recommended on production. Runs weekly as the app user (BACKUP_AS=dbuser — the DB password is read from application.yml), so aron-env and application.yml must be readable by that user (the chgrp/chmod 640 steps in Install). Retention is configured in aron-env (BACKUP_KEEP_DAYS, default 14 days). The database is the only component that needs a backup: the search index is rebuilt by the portal, and the binary data in data/ can be archived with aron-backup --with-files (DATA_DIR in aron-env).

sudo cp /opt/aron/scripts/systemd/aron-backup.{service,timer} /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now aron-backup.timer
sudo systemctl start aron-backup.service   # run one backup now to verify

Verify: a fresh *.dump + .sha512 appears in /opt/aron/backup.

Health heartbeat — aron-health

Install when the instance has a CSC account; without one the service is a harmless no-op. Set HEALTH_URL in aron-env (the Actuator health endpoint, see Install) so the heartbeat distinguishes "process up" from "really serving".

sudo cp /opt/aron/scripts/systemd/aron-health.{service,timer} /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now aron-health.timer
sudo systemctl start aron-health.service   # send one heartbeat now to verify

Verify locally without sending: /opt/aron/scripts/aron-health --check.

Unattended updates — aron-update

Opt-in. The unit runs as root (it stops/starts the service; no sudo setup) and stays inert until you set AUTOUPDATE=on in aron-env.

sudo cp /opt/aron/scripts/systemd/aron-update.{service,timer} /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now aron-update.timer

Verify: systemctl list-timers 'aron-*' shows the next run; activity: journalctl -u aron-update.service -n 50.

Files

The application releases themselves (aron-bundle-<version>.zip: the executable jar, the default configuration and an installation readme) are published to the LightComp Maven repository; aron-deploy downloads and verifies them from there.