On-prem installation

AppArch can run entirely on your own infrastructure. The installation package and the licence are delivered by the AppArch team as part of your contract.

What you need before installing

Item	What it does
Licence	Defines the limits and the term of your installation, and works on one installation only. Online installations collect it automatically at first boot using your installation credentials; air-gapped installations receive an `apparch.lic` file bound to their installation code - see One licence, one installation.
Installation ID	The username for signing in to the AppArch image registry.
Installation key	The password for the same sign-in. Delivered once.
Installation package	The configuration files that bring the services up, plus the step-by-step guide.

The installation ID and key belong to your licence: the images are not publicly listed and can only be pulled with these credentials.

docker login hub.apparch.io -u <installation-id> -p <installation-key>

Once the login succeeds, follow the steps in your installation package to start the services.

One licence, one installation

There is no key file to place: the key that proves a licence was issued by AppArch is built into the images.

A licence works on one installation. The first installation that collects it online (installation ID + installation key) binds it to itself; another installation asking for the same licence is refused with “This licence is already in use by another installation”.

An installation is everything that shares one database: every pod or replica reads the same installation code, so scaling the Api or the UI out to several pods runs on the same licence and needs nothing from AppArch.

Air-gapped installations receive a licence file bound to their installation code:

Start the services.
Open the setup wizard’s licence step and choose Paste a licence file, or, on an installation that is already set up, go to Management → Settings → Licence.
Copy the installation code shown there and send it to AppArch.
Place the .lic file you receive at ./license/apparch.lic, or paste its content in the wizard.

That file works on that installation only.

Moving to a new server: ask AppArch to release the licence, then collect it again from the new server.

Staying licensed

An online installation checks in with AppArch every hour (https://gateway.apparch.io, outbound HTTPS). Each check-in renews its licence; nothing has to be done by hand, but the server must be able to reach that address.

A licence with an end date keeps working for two weeks without a successful check-in, so a firewall change or an outage does not stop anything at once. If two weeks pass without one, the installation stops until it can reach AppArch again.
A licence without an end date does not depend on the check-in.
Air-gapped installations never check in: their licence file works until its end date.

When the installation stops - the licence was revoked, the check-in failed for two weeks, or the licence expired more than 14 days ago - every screen except Administration shows “This installation is stopped” with the reason, and nothing is analysed or recorded. CI steps are not failed: the collector prints a warning and passes, so a licence never blocks your merge requests. Installing a valid licence under Management → Settings → Licence lifts the stop at once, without a restart.

Monthly limits. Your licence may cap ArchScan reports, ArchSecurity runs and ArchPilot comments per calendar month, for the whole installation. A report beyond the limit is not stored and the collector passes with a warning; ArchPilot keeps recording reviews but stops posting comments to merge requests. Limits reset on the 1st of the month; current usage is shown under Management → Settings → Licence.

Licensed features. Three features depend on your licence: single sign-on (LDAP sign-in), the audit log (viewing Administration → Audit; actions are always recorded) and advanced reporting (report exports and scheduled report e-mails). The same licence page shows which ones yours includes.

Server requirements

Docker Engine 24+ with the compose plugin
PostgreSQL and Redis (included in the installation package)
An HTTP(S) address your users can reach
Online installations: outbound HTTPS to gateway.apparch.io (hourly licence check-in) and hub.apparch.io (images)

After installation

On first start you are greeted by the setup wizard, where you create the administrator account.
The database schema updates itself on every start - you never run SQL by hand.
E-mail (SMTP or Postmark), LDAP sign-in and licence renewal are managed from the Administration area inside the app - see the administration guide for everything that lives there, including the sign-up switch, the invitable e-mail domain allowlist and the installation-wide two-factor switch.

Watching a boot

The API narrates its startup in the container log (docker compose logs -f api): connecting to the database (host and port, never credentials), acquiring the bootstrap lock, applying pending migrations, seeding reference data, loading the licence, and finally Boot complete - accepting requests. If a boot fails, a single line above the stack trace names the phase that died.

Health endpoints

Both containers expose unauthenticated probes:

Endpoint	Meaning
`GET /health/live`	The process is serving HTTP. No dependency checks.
`GET /health/ready`	Ready for traffic - the API checks PostgreSQL and Redis, the UI checks the API.

The shipped docker-compose.yml wires them as container healthchecks (the UI waits for a healthy API, not merely a started one). On Kubernetes, point livenessProbe at /health/live and readinessProbe at /health/ready, and give the API a generous startup window - a first boot runs migrations and seeds reference data.

Report checks

Commit check. Every ArchScan, ArchSecurity and SmartScan report names its commit, and the API looks it up in the project’s repository with the project’s credential. A commit the repository definitely does not have is refused with 422 report_commit_not_found and the CI step fails: the project token is being used in another repository’s pipeline, or on work that was never pushed. When the commit cannot be checked (no credential, the provider unreachable) the report is stored. COMMIT_VERIFICATION=Record only logs, Off skips the check.
Compressed reports. Current collectors send report bodies gzip-compressed (a large report shrinks about eight times); there is nothing to configure.

Upgrades

Point the image tags at the new version and docker compose pull && docker compose up -d. Pending migrations apply in order, one by one, however many versions you skipped - a 1.0.0 installation moving to 1.0.12 applies all twelve on first boot, under a database lock that keeps multiple replicas from colliding. Take a database backup before upgrading; migrations only move forward.

Check the licence first. The new image can tell, before it replaces the running one, whether it will accept this installation’s licence. The check reads the database, changes nothing, and the current version keeps serving:

APPARCH_API_IMAGE=hub.apparch.io/apparch/api:<new-version> docker compose run --rm --no-deps api --check-license

It ends with Result: safe to upgrade. (exit code 0) or Result: do not upgrade yet. (exit code 1) and says what is missing: an online installation needs its installation id and key set and AppArch reachable; an air-gapped one needs a licence file bound to its installation code at license/apparch.lic. Upgrade only after a pass.

On-prem licensing and pricing are handled by the sales team: apparch.io.