Installation

Advanced Installer Functionality

Complete Installer Functionality

This Appendix covers all the information about the possible configurations and utilities not covered in the main tab of the document.

Preflight

Before running a full installation or a Platform Setup, the installer runs a Preflight phase: a set of automatic checks on the configuration and on each host of the environment, designed to detect problems (busy ports, lack of space, incorrect users or permissions, connectivity, etc.) before starting to deploy services.

When and how it runs

Preflight is launched manually from the Deploy page panel, with the Run button, or via the REST API. While it runs, a log viewer shows live progress.

The checks run in three phases, with an early cutoff if the configuration is not valid:

  • Configuration (12 checks, global scope): validate the configuration file before touching any host. If any fails, the phase stops there and the environment checks are not run.

    • Required fields, version format, installation folder format, and service user format

    • Host and port topology

    • Consistency of enabled services

    • Validity of the IP access control configuration

    • At least one active authentication method

    • Complete persistence configuration

    • Opt-in for release candidate and development versions.

  • Environment, global scope (4 checks):

    • Connectivity with the Nexus repository

    • Reachability of the monitoring OTLP endpoint (if enabled)

    • Resolution of the version map to install

    • Connectivity with the custom S3 endpoint (if configured).

  • Environment, per host (16 checks): repeated on each host in the environment.

    • Supported operating system

    • SSH connection

    • Passwordless sudo

    • Service user

    • Installation directory permissions

    • Disk space and memory

    • Free ports

    • Hostname resolution

    • System packages, Java 17, AWS CLI, nginx modules

    • Prior installation

    • Sufficient space for the mandatory upgrade backup

    • Free ports for the new engines in 26.1.

In the interface, results are grouped into two blocks: Configuration (the 12 configuration checks) and Environment (the remaining 20 environment checks, both global and per host).

Severity and remediation

Each check produces a PASS, WARN, or FAIL result:

  • A FAIL blocks progress to Install/Platform Setup.

  • A WARN does not block the Preflight result, but the interface requires checking a confirmation checkbox ("acknowledge the warnings") before allowing progress with pending warnings.

In summary: a FAIL must always be resolved; a WARN can be consciously accepted to move forward.

7 of the 32 checks are remediable: the panel shows a Fix button next to the check, which applies the correction automatically. The rest (25 checks) are diagnostic only and require manual correction of the environment.

Check

Scope

What it validates

Remediable

config-required-fields

Configuration

Required fields present

No

config-version-format

Configuration

Anjana version format

No

config-install-folder-format

Configuration

Installation folder format

No

config-service-user-format

Configuration

Service user format

No

config-topology-hosts

Configuration

Host topology declared correctly

No

config-ports-valid

Configuration

Configured ports valid and without collisions

No

config-toggles-coherent

Configuration

Consistency between enabled services

No

config-access-control

Configuration

Valid IP access control configuration

No

config-auth-method

Configuration

At least one authentication method is active

No

config-persistence-complete

Configuration

Complete persistence configuration

No

config-rc-allowed

Configuration

Release candidate version opt-in

No

config-snapshot-versions

Configuration

Development versions (SNAPSHOT)

No

nexus-connectivity

Environment (global)

Nexus repository reachable

No

otlp-endpoint

Environment (global)

OTLP endpoint reachable

No

version-map

Environment (global)

Version map to install resolvable

No

custom-s3-connectivity

Environment (global)

Custom S3 endpoint reachable (if configured)

No

os-supported

Environment (host)

Supported operating system

No

ssh-reachability

Environment (host)

Working SSH connection

No

sudo-nopasswd

Environment (host)

Passwordless sudo available

Yes

service-user

Environment (host)

Service user exists

Yes

install-dir-writable

Environment (host)

Installation directory exists and is writable

Yes

disk-space

Environment (host)

Sufficient free disk space

No

memory

Environment (host)

Sufficient RAM for the selected environment profile

No

ports-free

Environment (host)

Required ports free

No

hostname-resolves

Environment (host)

Hostname resolved in the hosts file

Yes

required-packages

Environment (host)

Required system packages present

Yes

java-runtime

Environment (host)

OpenJDK 17 present

Yes

aws-cli

Environment (host)

AWS CLI v2 present

Yes

prior-install

Environment (host)

No prior installation detected

No

realip-module

Environment (host)

nginx realip module available

No

upgrade-backup-space

Environment (host)

Sufficient space for the mandatory upgrade backup

No

upgrade-ports-free

Environment (host)

Free ports for the new persistence engines in 26.1

No

Report validity

The Preflight result stays linked to the configuration it was generated with. Install and Platform Setup remain blocked until there is a report:

  • Generated within the last 15 minutes (TTL configurable via anjana.installer.preflight-report-ttl-minutes).

  • With no changes to the configuration since it was generated: any modification invalidates the report.

  • With no check in FAIL state.

If the report expires or the configuration changes, the panel marks it as "(expired)" and Preflight must be run again. From the CLI/TUI, if an attempt is made to launch an installation without a valid Preflight, the installer reports the reason for the block and indicates that it must be run from the web interface or the API before retrying.

REST API

Endpoint

Description

POST /api/preflight

Launches a run of all checks

GET /api/preflight/latest

Status of the latest report, including its validity

GET /api/preflight/{jobId}

Detail of a preflight or remediation job

GET /api/preflight/{jobId}/logs

Live log of the job

POST /api/preflight/{checkId}/remediate?host=X

Applies the automatic correction of a remediable check

Relevant responses: 409 (JOB_ACTIVE) if a Preflight is already running; 409 with reason NO_REPORT, STALE_REPORT, CONFIG_CHANGED or FAILED_CHECKS if an attempt is made to proceed without a valid report; 400 if remediation is requested for a non-remediable check or a non-existent host.

Secrets Management

The installer includes an encrypted secrets management system for persistence credentials and other sensitive information, with several management modes available:

AWS Secrets Manager

When the installer runs in an environment with access to AWS Secrets Manager, credentials are retrieved directly from the managed service, leveraging AWS's native encryption and rotation.

This is the recommended backend in cloud environments.

Configuration

The backend is selected in the wizard (Secrets Backend section) or directly in the installation.yaml file:

YAML
secretsBackend:
  installerBackend: AWS_SECRETS_MANAGER
  awsRegion: eu-central-1
  awsSecretsPrefix: /secret/<env>

Parameter

Description

Default value

awsRegion

AWS region where Secrets Manager resides

None (required)

awsSecretsPrefix

Prefix of the secret in SM. Must match the environment's HORUS_SM_PREFIX

/secret/dev

awsRoleArn

ARN of the IAM role to assume (cross-account). If null, uses default credentials (instance profile or environment credentials)

null

JSON Blob Format

The installer reads a single JSON secret ("blob") at the path {awsSecretsPrefix}/application_default. This is the same format used by Horus via Spring Cloud Config (a convention shared by all microservices of the platform).

The blob contains a flat JSON with the secret keys:

JSON
{
  "NEXUS_USER": "admin",
  "NEXUS_PASS": "...",
  "DB_PASS": "...",
  "S3_ACCESS_KEY": "...",
  "S3_SECRET_KEY": "...",
  "INDEX_PASS": "...",
  "MONGO_URI": "mongodb://user:pass@host:27017/db?tls=true&replicaSet=rs0",
  "VALKEY_PASS": "...",
  "RABBITMQ_PASS": "...",
  "LICENSE_INSTALLATION_CODE": "...",
  "LICENSE_PRIVATE_KEY": "...",
  "LICENSE_PUBLIC_KEY": "...",
  "INSTALLER_ADMIN_PASSWORD": "...",
  "INSTALLER_DEV_PASSWORD": "...",
  "INSTALLER_BUNDLE_SIGNING_KEY": "..."
}

Key mapping (SM blob to installer):

Key in SM

Installer internal key

Usage

NEXUS_USER

nexus.user

Nexus username

NEXUS_PASS

nexus.password

Nexus password

DB_PASS

persistence.db.password

PostgreSQL

S3_ACCESS_KEY

persistence.s3.accessKey

SeaweedFS / S3

S3_SECRET_KEY

persistence.s3.secretKey

SeaweedFS / S3

INDEX_PASS

persistence.solr.password / persistence.opensearch.password

Indexing engine (Solr or OpenSearch)

MONGO_URI

persistence.mongodb.uri

Full MongoDB URI (includes TLS and replicaSet)

VALKEY_PASS

persistence.valkey.password

Valkey

RABBITMQ_PASS

persistence.rabbitmq.password

RabbitMQ

LICENSE_INSTALLATION_CODE

license.installationCode

License installation code

LICENSE_PRIVATE_KEY

license.privateKey

License private key

LICENSE_PUBLIC_KEY

license.anjanaPublicKey

Anjana public key

INSTALLER_ADMIN_PASSWORD

bootstrap admin password

Initial password of the installer's admin user

INSTALLER_DEV_PASSWORD

bootstrap dev password

Initial password of the installer's dev user

INSTALLER_BUNDLE_SIGNING_KEY

bundle.signingKey

HMAC signing key of the config bundle, used to verify its integrity when restoring it on a replacement VM

NOTE: This backend is read-only: credentials are managed externally (IaC, AWS console).

Write operations (credential rotation from the UI) are not available in this mode. For the same reason, the expiration policy of the interface's own administrator password (see "Password expiration policy" below) is also not evaluated with this backend: since the date of the last change cannot be recorded, the system never forces its renewal.

The IAM role or credentials used must have the secretsmanager:GetSecretValue permission on the secret {awsSecretsPrefix}/application_default.

Encrypted Local Storage

For environments without access to cloud secret management services (local VMs, WSL, isolated environments), the installer provides encrypted local storage (AES-256-GCM).

All credentials are encrypted at rest, eliminating the exposure of secrets in plain text files.

No environment file containing plaintext credentials should ever be generated; all sensitive information remains encrypted at all times.

TLS Keystore Password (ksPass)

The installer generates a random password for the TLS keystore on each deployment (platform setup).

This password (ksPass) is stored in the SecretsService and automatically rendered in the service descriptors (systemd) of all microservices. This way, the microservices' JVMs never use a predictable static password to protect the internal TLS communications keystore.

Horus Configuration Backend (horusConfigBackend)

The installer allows configuring the backend from which Horus Config Server reads the platform configuration. This setting is independent of the installer's own secrets backend and is defined in installation.yaml under the secretsBackend.horusConfigBackend key.

Option

Description

JDBC (default)

Horus reads the configuration from the app_configuration table in PostgreSQL. Requires no additional configuration.

GIT

Horus reads the configuration from a Git repository (Spring Cloud Config mode). Requires: gitUri, gitDefaultLabel (branch), gitSearchPaths. For SSH authentication: gitPrivateKeyBase64 (private key in base64) or gitPrivateKeyPath (path to the file on the server).

AWS_SECRETS_MANAGER

Horus obtains the configuration from AWS Secrets Manager. It uses the same JSON blob as the installer's secrets backend ({awsSecretsPrefix}/application_default).

Configuration example with the GIT backend:

YAML
secretsBackend:
  installerBackend: LOCAL_ENCRYPTED
  horusConfigBackend: GIT
  gitUri: git@github.com:ejemplo/config-repo.git
  gitDefaultLabel: main
  gitSearchPaths: anjana/{profile}
  gitPrivateKeyBase64: <SSH-private-key-in-base64>

Password Expiration Policy (Web UI Access)

The password of the installer's own interface admin user has a configurable expiration period, independent of the persistence credentials complexity policy (see "Credential security before deployment" in the Deployment Manual).

  • Default value: 60 days since the last password change.

  • Configuration: Settings > Web UI Access, Password Policy section (accepted range: 1 to 3650 days), or directly via API (GET/PUT /api/settings/password-policy).

  • Behavior on expiration: when logging in with an expired password, a mandatory password change modal is shown that blocks the rest of the interface until completed.

  • Advance notice: a few days before expiration, the interface shows a non-blocking notice so it can be changed with margin.

  • Reducing the window abruptly: if the expiration value is reduced and the age of the current password already exceeds the new limit, the interface detects this on save and offers to force an immediate password change.

  • Scope: this policy applies only to the admin user of the installer's own console. It does not apply to the development user (dev, only available in devMode) nor to persistence credentials (managed separately in Tools > Credentials).

  • AWS Secrets Manager backend: since it is a read-only backend, the date of the last password change cannot be recorded, so expiration is not evaluated (the change is never forced) when the installer uses this secrets backend.

Core Configuration Architecture

The installer generates and deploys the service descriptors (systemd) of each microservice with the parameters needed to connect to Horus Config Server on startup, including the sample data (sampledata) provided by Anjana during the initial installation. The profile used by all microservices is always 'default'.

No environment files of any kind are generated: credentials are managed exclusively through the installer's SecretsService, which stores them encrypted.

After operations that modify the database (RESET_ALL, RESTORE_ALL, LOAD_SAMPLE_DATA), the installer automatically repopulates the app_configuration table with the current credentials from the SecretsService, with no need for a manual restart.

MCP Service

MCP is treated like any other core service: enabled by default, deployed and exposed through the platform's proxy (route /mcp), both in cloud and on-premise deployments.

The product documentation explains how to use this service.

If it is not wanted, it can be unchecked during installation to prevent its deployment and activation.

Authentication Configuration (Zeus SSO)

The configuration wizard allows configuring the authentication providers that Zeus will use to manage user access to the Anjana platform. The installer supports the following methods, which can be combined with each other:

  • Local DB

  • LDAP

  • OIDC / OAuth2

  • SAML2

The wizard requires at least one of the four methods to remain active: it is not possible to save the configuration or proceed in the wizard if all are unchecked, since that would leave the platform with no possible way in.

Local DB

Enabled by default, requires no additional configuration.

LDAP

Fields to fill in the wizard:

Parameter

Description

URL

LDAP server address (e.g.: ldap://directory.example.com:389)

Base DN

Base search DN (e.g.: ou=users,dc=example,dc=com)

User Search Attribute

User identification attribute (e.g.: uid, sAMAccountName)

User Structural Class

LDAP class of the user object (e.g.: inetOrgPerson)

User Authentication

Authentication mode: USER_CONNECTION (direct bind) or SERVICE_ACCOUNT

Connection User DN

DN of the service user for searches (if SERVICE_ACCOUNT)

User Search Filter

LDAP user search filter

Name/Surname Attributes

Attributes for first and last name

The associated secret (LDAP connection password) is stored in the installer's secrets backend.

OIDC / OAuth2

Supports multiple simultaneous providers (Google, Azure AD, Keycloak, etc.). Fields to fill in per provider:

Parameter

Description

Registration ID

Unique identifier of the provider (e.g.: google, azure, keycloak)

Name

Display name of the provider

Type

Provider type: GOOGLE, AZURE, OTHER (Keycloak, ADFS, generic OIDC)

Issuer URI

Token issuer URI

Client ID

OAuth2 client ID

Scopes

Requested scopes (e.g.: openid, profile, email)

Username Attribute

Token claim used as username

Each provider's client secret is stored as oidcClientSecret.{registrationId} in the secrets backend.

SAML2

Supports multiple providers. Fields to fill in per provider:

Parameter

Description

Registration ID

Unique identifier of the provider

Name

Display name

Entity ID

Entity ID of the Identity Provider

IdP Metadata URI

Identity Provider metadata URI (required). Enables automatic negotiation of the IdP's endpoints and certificates.

SP Key/Cert (optional)

Server path to the private key file and the SP certificate for signing requests. If not configured, the installer automatically generates a key pair.

SAML2 certificates and keys (when configured) are stored as saml2SpSigningKey.{id} and saml2SpSigningCert.{id} in the secrets backend.

User Provisioning (Synchronization with External Directories)

In addition to the authentication providers above, the wizard includes a separate Provisioning step to automatically synchronize users and groups from an external directory into Anjana. Several providers are supported, and several instances of the same type can be configured (for example, two different Azure tenants), each identified with its own key:

Provider

Connection data

Azure Graph (Azure AD)

Tenant ID, Client ID, enterprise application ID

Google Workspace

Delegated user, application name, service account credentials, groups to synchronize

AWS IAM Identity Center

Region, access credentials, Identity Store ID, application ARN

AWS Cognito

Region, access credentials, User Pool ID

Auth0

Tenant domain, Client ID

Okta

Depending on availability for the client's tenant

Keycloak

Server URL, realm, Client ID

Each instance's connection secret (API token, client secret, or credentials, depending on the provider) is stored encrypted in the installer's secrets backend, just like the rest of the platform's credentials.

Secrets Status

The wizard's review step and the Secrets screen show a checklist with the initialization status of each secret (GET /api/wizard/secrets/status), indicating which are configured and which are missing. This includes the persistence, license, and authentication secrets, the dynamic secrets of each configured OIDC/SAML2 provider, and those of each configured provisioning provider.

IP Access Control

The installer allows restricting platform access by IP address through its proxy, managed from Settings > IP Access Control. Changes are applied live, without needing to restart services or perform a new deployment.

Three blocks are configured:

Block

Function

Default

General whitelist

Restricts access to the entire platform to the specified IPs/CIDRs

Disabled

Internal whitelist

Restricts access to internal administration and persistence routes

Enabled

Trusted proxies

If the installation is behind a load balancer, its CIDR is specified here so that access filtering and rate limiting use the client's real IP instead of the load balancer's IP

(no default value)

Each whitelist entry consists of a free-text label and an IP or CIDR range (IPv4 or IPv6). The installer validates the format on save and rejects malformed or inconsistent ranges.

Usage Flow

  1. Save: saves the configuration draft without applying it yet.

  2. Apply: validates the configuration, activates it on the proxy, and reloads the service. If validation fails, the active configuration is never touched; if something fails while already applying the change, the installer automatically restores the previous configuration.

  3. When activating the general whitelist, the screen shows the operator's own detected IP as a security notice, to prevent whoever activates it from locking themselves out by mistake.

The installer (port 8787) is independent of the proxy that manages this whitelist, so it is never blocked: if a change locks out the operator, it is always possible to enter directly through the installer's port to fix the configuration.

Note: this IP access control protects the platform's proxy (Anjana's business front-ends). It is a separate and independent mechanism from any access control on the installer's own console (port 8787).

Restricted Public Exposure

A common use case is publishing the platform on the Internet but restricting access exclusively to the organization's network ranges. To configure it:

  1. Enable the general whitelist.

  2. Add the corporate outbound ranges as entries: the corporate browsing proxy, the offices' public IPs, the corporate VPN, etc.

Operational notes for this scenario:

  • If the platform's services call themselves through the public URL, it is also necessary to include the installation's own public outbound (NAT) IP in the whitelist; otherwise, those internal calls would be blocked by the filter.

  • If there is a load balancer or proxy in front of the platform, first configure Trusted proxies with the load balancer's range, so that filtering is evaluated on each client's real IP and not on the load balancer's IP.

Migration from the Ansible Kit

When importing the configuration from a previous Ansible kit (see "Import from Ansible Kit" below), it is also possible to attach the anjanauihosts.yaml file: the whitelists already defined in the kit are automatically carried over to the installer's general and internal whitelist.

Persistence Management

IaaS/PaaS Connection Configuration

The installer adapts its persistence configuration interface according to the selected deployment mode. In Single VM mode without cloud persistences, it is not necessary to fill in connection URLs, since they will always be localhost. In Single VM mode with cloud persistences, connection fields for managed services are enabled (AWS RDS, AWS S3, etc.). In Core + Persistences (Distributed) mode, full configuration of URLs, credentials, and connection parameters is required.

Persistence Dependencies

The installer establishes a mandatory dependency between the core and the persistences. The core cannot be installed without the persistences being previously deployed or, failing that, without the corresponding cloud persistences having been checked. A prior detection of the persistences' status is performed and a warning is shown on the checkboxes if a required prerequisite is not met.

Additionally, the wizard's services screen shows a non-blocking warning when any core microservice is unchecked: the entire core is necessary for the platform to work correctly, so disabling one of its components may leave the installation in a partial or inconsistent state.

OpenSearch will be available soon.

Configuration Import

Import from Installer YAML

Allows re-importing a YAML file previously exported by the installer (the "Export YAML" button on the Configuration page). This is the tab selected by default in the import dialog.

Import from Ansible Kit

Allows importing the all.yaml and hosts.yaml files from a previous Ansible kit. The process consists of two steps:

  1. Preview: all values are mapped, the topology is detected, warnings are shown along with the secrets found. The option to migrate to OpenSearch is offered (checked by default as the recommended option).

  2. Confirm: the configuration and secrets are persisted. If there are warnings (such as protected credentials), a results step is shown before closing.

Credential Protection During Import

When confirming any import, the installer checks which persistence services are already deployed (via systemctl is-enabled). For each deployed service, the imported credential is discarded from the saving process. A grouped warning is shown: "Credentials not overwritten for deployed services: PostgreSQL, SeaweedFS, RabbitMQ, MongoDB, OpenSearch, Valkey. Use Tools > Credentials to rotate them."

This prevents desynchronization between the password stored in the secrets store and the actual password configured in the service, which would prevent subsequent rotation and the microservices' connection.

Service Descriptors

The installer allows editing the parameters of each microservice's service descriptors (systemd units) directly from the graphical interface, in the Service Descriptors tab of the Configuration page.

Parameters Editable per Service

Parameter

Description

Xms (Pro/Pre/Dev)

Initial JVM memory per environment (production, pre-production, development)

Xmx (Pro/Pre/Dev)

Maximum JVM memory per environment

Port

Service port

RestartSec

Wait time before restarting after a failure (seconds)

Features

  • Per-service override: edited values are stored as overrides on top of the installer's built-in defaults

  • Preview: preview of the systemd unit file generated with the current parameters, before applying

  • Reset to defaults: restore a service to its default values, removing the overrides

  • Raw unit editor: direct editing of the systemd unit file content for advanced cases

  • Apply changes: apply all pending changes, which regenerates the unit files and restarts the affected services (equivalent to the Update Service Units operation)

Memory overrides are useful for tuning environment performance without touching the installer's templates. Changes are persisted to disk and survive installer updates. The preview allows validating the result before applying.

Plugin Configuration

The installer allows editing plugins' local configuration files when they operate in standalone mode (not using Horus Config Server).

Standalone Mode vs Config Server

  • Config Server (default): plugins get their configuration from Horus on startup. The installer does not allow editing the local configuration in this mode

  • Standalone: plugins read a local application-default.yaml file. The installer enables editing of these files

Features

  • Plugin list: shows all enabled plugins with an indication of whether they have a local configuration file

  • YAML editor: text editor for each plugin's application-default.yaml file, with YAML syntax validation before saving

  • Save & Restart: save changes and optionally restart the plugin immediately

  • Individual restart: restart a plugin without modifying its configuration

File Path

Configuration files are stored at: /{installFolder}/data/config/{plugin}/application-default.yaml

Example: /opt/anjana/data/config/tot_plugin_jdbc/application-default.yaml

Cloud Vault for Standalone Plugins

When plugins operate in standalone mode (pluginsConfig.standalone: true), it is possible to configure a cloud vault that injects secrets at runtime. The vault is configured with the vaultType parameter:

VaultType

Description

NONE (default)

No cloud vault. Plugins read all their values from the application-default.yaml file generated by the installer.

AWS

AWS Secrets Manager. Requires awsRegion and optionally awsRoleArn (for cross-account access or with an explicit role).

AZURE

Azure Key Vault. Requires vaultHost (vault URL), vaultClientId, vaultClientSecret, and vaultTenantId.

GCP

GCP Secret Manager. Requires vaultHost (GCP project), vaultClientSecret (path to the credentials JSON) and vaultTenantId (project ID).

In standalone mode, totDomain must also be configured with the domain of the TOT server the plugins register with.

Data Tools

The installer includes a Tools side menu with four tabs, accessible both from the graphical interface and from the command line (CLI).

Credentials: Credential Management

Shows all enabled persistence credentials with their security status. The security policy requires: minimum 8 characters, at least one uppercase letter, one lowercase letter, one digit, and one special character.

Features:

  • Individual rotation: enter a password manually or generate a secure one, with a confirmation field and a visibility toggle

  • Bulk rotation ("Fix All Insecure"): generates and applies secure passwords to all insecure credentials in sequence

  • Deployed status detection: for deployed services, rotation changes the password in the service (ALTER USER, mongosh, valkey-cli, etc.) and updates the secrets store; for services that are not deployed, it only updates the secrets store

  • Update secret only: toggle available for deployed services that allows updating only the secrets store without connecting to the service. Use case: recovering from a desynchronization between the stored password and the service's actual password

  • External/cloud services: credentials for AWS S3, RDS, and other managed services are marked as "External" and are not rotatable; the user is told to manage them from the provider's console

  • Confirmation for deployed: when rotating credentials of running services, a confirmation modal is shown warning that the microservices will lose connection until restarted

If there are insecure credentials, deployment operations are blocked and the Deploy page shows a warning with a direct link to Tools > Credentials.

Persistence: Data Operations

Operations organized in cards by service, with buttons per operation:

Operations per service:

Service

Available operations

PostgreSQL

Backup (pg_dump per schema), Restore (from a previous backup), Restore from .sql (file upload), Delete (DROP SCHEMA CASCADE), Unlock Schemas (reset Liquibase locks)

S3 / SeaweedFS

Backup (aws s3 sync per bucket), Restore (from a previous backup), Restore from .tgz (file upload), Delete (recursive rm per bucket)

MongoDB

Backup (mongodump), Restore (mongorestore), Restore from .tar.gz (file upload), Delete (drop database)

Solr

Delete Collections (Collections API)

OpenSearch

Delete Indices (REST API)

Valkey

Flush Cache (FLUSHALL)

RabbitMQ

Purge Queues (purge of all queues)

Config (Horus)

Backup, Restore, Delete of the configlocal directory, Restore from .tar.gz

Composite operations:

Operation

Description

Backup All

Sequential backup of PostgreSQL + MongoDB + S3 + Config

Restore All

Restores the latest available backup of each service

Export Data

Runs Backup All and packages everything into a downloadable .tar.gz for migration

Import Data

Uploads an export .tar.gz and restores all the services it contains

Load Sample Data

Loads sample data from Nexus. Requires selecting a dataset (nativo, gob-ext, health-dcatap, pbi) and optionally a version

Reset All

Removes ALL data from all persistences, with optional restore modes (see detail below)

Connection Check

TCP connectivity test to all enabled persistences

Purge Local Persistence

Stops, uninstalls, and removes all local persistence services and their data

Uninstall Anjana Platform

Complete uninstall: backup, removes services, data, configuration, and system user

Reset All: restore modes:

The Reset All operation deletes all data from all persistences (PostgreSQL, MongoDB, S3, Solr/OpenSearch, Valkey, RabbitMQ, Config) and offers three modes via a modal with a selector:

Mode

Behavior

Empty (default)

Only deletes, leaves the environment empty. Compatible with previous behavior

Sample Data

Deletes and loads sample data from Nexus. Requires selecting a dataset and optionally a version

Latest Backup

Deletes and restores from the latest local backup of each service

The operation requires confirmation with a password. The confirmation button reflects the selected mode: "Reset All" / "Reset & Load" / "Reset & Restore". If the deletion phase succeeds but the restore fails, the logs indicate exactly which phase failed and suggest how to retry.

The microservices that are stopped to safely delete the data are automatically restarted when finished, respecting the order of dependencies between them to avoid startup failures due to unavailable dependencies.

Restore from file:

Restore-from-file operations allow uploading files directly from the browser via a native file picker. Files are uploaded to the server, processed, and removed after completing the operation.

  • Restore from .sql (PostgreSQL): accepts multiple .sql files, which are executed sequentially against the Anjana database

  • Restore from .tgz (S3/SeaweedFS): accepts a .tgz archive containing folders corresponding to the buckets (cdn, imports, textarea, etc.) with their content; they are extracted and synced via AWS CLI

  • Restore from .tar.gz (MongoDB, Config): accepts .tar.gz files with the data to restore

All destructive operations require explicit confirmation. The job history is collapsible and shows status, operation, timestamp, and result. Each row in the history also includes a diagnostic export icon scoped to that specific job (see "Diagnostic package export" below).

Backups: Inventory and Management

Inventory of all stored backups, grouped by service with functional name + technology badge:

  • Listing: shows all backups per service with name, size, and date

  • Download: individual download of any backup (directories are packaged as .tar.gz)

  • Delete: deletes individual backups (the last backup requires double confirmation with password)

  • Data Exports: dedicated section for .tar.gz files generated by Export Data

  • Retention: maximum number of backups per service (configurable, default 5). Applied automatically after each backup. The change is persisted to disk and survives restarts

Backups follow a standardized naming convention: anjana_{service}_{timestamp} (e.g.: anjana_postgresql_20260327_143025.sql). They are stored at /opt/backup/{service}/.

Logs: Real-Time Log Viewer

Allows viewing the logs of any enabled microservice, persistence, or plugin:

  • Service selector: dropdown grouped by category (Core / Persistence / Plugins)

  • Tail: loads the last N lines (configurable, 10-5000, default 100) via journalctl

  • Follow: real-time streaming via WebSocket/STOMP with an animated LIVE indicator

  • Color coding: error lines in red, success in green

Diagnostic Package Export

The installer allows downloading a plain-text diagnostic package for support, with credentials redacted using the same secret-redaction mechanism used by the rest of the application.

  • General export: Export Diagnostics button in Tools > Persistence, or GET /api/diagnostics/export. Includes the log of the latest deployment job, the latest Preflight report, a health status snapshot, the version inventory, and a non-sensitive environment summary.

  • Export by specific job: in the Tools > Persistence job history, each row includes an export icon that downloads the diagnostics scoped to that specific job (GET /api/diagnostics/export?jobId=...), instead of the generic latest job. Depending on the job's source log, the log section is labeled "TOOL JOB LOG" (backups, restores, resets, etc.) or "DEPLOYMENT JOB LOG" (Install, Upgrade, Platform Setup, etc.).

  • Format: downloadable plain-text file, named anjana-diagnostics-<timestamp>.txt.

  • Audit: each export is recorded in the audit log with the requested job.

Version Inventory

The installer provides a consolidated version inventory accessible from the Dashboard and the API (GET /api/versions):

  • Installer version: current version of the installer binary

  • Anjana version: version of the configured platform

  • Status per service: for each microservice, persistence, and plugin, shows the configured version, the running version (automatically detected), and the current status (UP, DOWN, DEGRADED, UNKNOWN)

Data is grouped by category (Core, Frontend, Persistence, Plugin) to make it easier to read.

Automatic Installer Update (Self-Update)

The installer includes a complete self-update mechanism with automatic rollback:

Version Detection

  • Manual check: from Settings, "Check for updates" button that queries Nexus

  • Automatic check: schedulable (every hour if enabled), configurable from Settings

  • Response: indicates whether an update is available, current version, and latest version

Update Process

  1. Downloads the new JAR version from Nexus and saves it as {current-jar}.new

  2. Generates an update script in a unique temporary file under /tmp/anjana-update-*.sh

  3. The script waits for the current process to end (max 30s)

  4. Creates a backup of the current JAR as {current-jar}.bak

  5. Performs an atomic swap: moves .new to the main JAR's location

  6. Restarts the service via systemd

  7. Waits 20 seconds and verifies the service is active

  8. If startup fails: automatically restores the backup and restarts the previous version

Configuration

The auto-update preference is persisted in {dataDir}/update-settings.json and is accessible via the API (GET/PUT /api/updates/settings).

Operational Robustness

Deployment Job Timeouts

Every deployment job (Install, Update, Platform Setup, Restart, Start, Stop, service descriptor update) has a maximum execution time automatically monitored by the installer. If a job gets stuck beyond that time, it is marked as failed and this is reflected in the log with the reason. Two categories are distinguished:

  • Long jobs (Install, Update, Platform Setup): 45 minutes by default, configurable.

  • Short jobs (Restart, Start, Stop, service descriptor update): 10 minutes by default, configurable.

Service Status Cache and Manual Refresh

To avoid overloading hosts with repeated checks, the installer caches the result of checking whether a service is installed on each host for 5 minutes (configurable). If the operator needs an instantly updated status, they can force the check from the interface or via the POST /api/status/refresh endpoint, which ignores the cache and repeats the check on the spot.

A one-off failure checking a service or plugin (for example, a temporarily unreachable host) does not interrupt the check of the rest of the platform.

Status Endpoint for External Load Balancers

The platform proxy's /_health/* route is designed for an external load balancer or monitoring system to check whether the instance is alive, without exposing the status detail of each microservice: it simply responds whether the platform is operational or not.

Loading Screen During Deployment

While the platform is being installed or started, the loading screen the user sees shows only the phase in progress (for example, "Installing services", "Configuring network") instead of a list of individual services, avoiding confusion if some status takes time to sync. The progress check is protected against empty or incomplete responses: in that case it is treated as "indeterminate progress" instead of being considered complete too early.

Extended Environment Status (Dashboard)

Microservice Status Detection

The installer's status functionality goes beyond a simple port check. Multiple sources of information are cross-referenced to determine the actual status of each microservice:

  • Service status at the operating system level (descriptor/systemd)

  • Verification of correct startup through log analysis

  • Registration status in the discovery service

Services that are not deployed are shown as NOT_INSTALLED instead of DOWN.

Version Detection and JSON Format

Each microservice's version is automatically detected by analyzing the startup logs, with no need to query additional endpoints or version files. All status data is standardized in JSON format, making it easier to consume by external tools and automation scripts. The overall environment status (HEALTHY, DEGRADED, DOWN, UNKNOWN) is calculated aligned with the backend's logic.

Logs and Auditing

The installer logs all its activity in two separate pipelines:

  • Operations log: record of deployments, updates, backups, and data operations.

  • Audit log: record of logins and authenticated operations, separated into an independent pipeline to facilitate integration with the client's SIEM systems.

Service Descriptors: Dependencies

Dependencies Between Microservices

Microservices are configured with dependencies at the service descriptor level. Each microservice waits for its dependencies to be started before starting, eliminating the need for the previous Ansible kit's manual ordered startup functionality.

Hosts File Management

The installer assigns names in the operating system's hosts file per machine instead of per microservice, as was the case in the previous Ansible kit. This prevents an incorrect DNS from being sent during the microservice's registration in the discovery service, resolving a known issue from the previous kit.

Command Line Interface (CLI)

All functionality available in the graphical interface is also accessible from the command line. The same installer binary connects via HTTPS to the running installer.

Tools Commands

Command

Description

tools list

Lists all available tool operations

tools run <operation> [--yes] [--param k=v]

Runs an operation. --yes skips the interactive confirmation (for scripting)

tools jobs

Lists recent jobs with their status

logs <service> [--follow] [--lines N]

Queries or follows a service's logs

Usage Examples

# Full backup
tools run BACKUP_ALL --yes

# Reset and load sample data
tools run RESET_ALL --param restore=sample --param dataset=nativo --param version=26.1 --yes

# Load sample data without reset
tools run LOAD_SAMPLE_DATA --param dataset=nativo --yes

# Follow horus logs in real time
logs horus --follow --lines 200

Credential rotation is not available as a tools run operation. To rotate credentials, use the Tools > Credentials screen in the graphical interface, or the API endpoint POST /api/tools/credentials/rotate/{service}.

This enables automation via scripts, integration with CI/CD pipelines, execution in environments without a graphical interface, and unattended batch operations.