================================================================
Apinizer Cache (Hazelcast) - Standalone Distribution
================================================================

This package is self-contained; Java is NOT required on the target
machine. A bundled OpenJDK (Temurin) runtime ships inside runtime/.

Directory layout:
  bin/       Start/stop/install/encrypt scripts and systemd unit
  conf/      Configuration files (apinizer-cache.env, master.key)
  lib/       Cache Spring Boot fat jar (and lib/jasypt/ helper jar)
  runtime/   Bundled OpenJDK 25 (Temurin) JRE
  logs/      Runtime logs (created automatically on first start)

The Cache tier runs Hazelcast for shared state (quotas, rate-limit
counters, OIDC sessions, circuit-breaker state). Workers connect
to it over HTTP (port 8090) for cache reads/writes and over the
Hazelcast wire protocol (port 5701) for cluster membership.

------------------------------------------------------------
1. Installation (one-time, requires sudo)
------------------------------------------------------------
The installer creates a dedicated 'apinizer' system user, sets
correct permissions, generates a random Jasypt master key, and
registers a systemd service. It needs root privileges via sudo —
no interactive root login is required.

  sudo ./bin/apicache-install.sh

To delegate this to a non-root operator, add a sudoers entry:
  apinizer-admin ALL=(root) NOPASSWD: /opt/apinizer-cache/bin/apicache-install.sh

------------------------------------------------------------
2. Configuration
------------------------------------------------------------
Edit conf/apinizer-cache.env and set at least:
  - SPRING_DATA_MONGODB_URI
  - SPRING_DATA_MONGODB_DATABASE
  - CACHE_QUOTA_TIMEZONE (e.g. +03:00 — must match Worker/Manager)

Single-node deployments need nothing else; standalone mode is
auto-detected by the absence of the Kubernetes service-account
namespace file (/var/run/secrets/kubernetes.io/serviceaccount/namespace).

For multi-node clusters also set:
  - APINIZER_CACHE_CLUSTER_MEMBERS (comma-separated IPs of all
    cluster peers — every node sees the same list)

The Hazelcast cluster name (HAZELCAST_CLUSTER_NAME) ships with a
sensible default (apnz-hz-cluster) and should NOT be changed unless
multiple independent Apinizer installs share the same LAN — see the
"ADVANCED" section in apinizer-cache.env for the trade-offs.

Hazelcast tuning, MapStore options, observability and JVM flags
are documented inline in apinizer-cache.env.

------------------------------------------------------------
3. Encryption (recommended for credentials)
------------------------------------------------------------
After setting plaintext values, run:

  sudo -u apinizer ./bin/apicache-encrypt.sh

This wraps SPRING_DATA_MONGODB_URI and SPRING_DATA_MONGODB_DATABASE
with ENC(...) using the Jasypt master key in conf/master.key. The
JVM never sees the ciphertext — the start script decrypts each
ENC(...) entry to plain text BEFORE launching Java.

To encrypt an arbitrary value (e.g. an external secret):

  sudo -u apinizer ./bin/apicache-encrypt.sh '<plaintext>'

------------------------------------------------------------
4. Service control (systemd)
------------------------------------------------------------
  sudo systemctl start   apinizer-apicache
  sudo systemctl stop    apinizer-apicache
  sudo systemctl status  apinizer-apicache
  sudo journalctl -u apinizer-apicache -f

Manual control (without systemd):
  sudo -u apinizer ./bin/apicache-start.sh           # background
  sudo -u apinizer ./bin/apicache-start.sh -f        # foreground
  sudo -u apinizer ./bin/apicache-stop.sh

------------------------------------------------------------
5. Cluster ports (firewall checklist)
------------------------------------------------------------
Open the following on each cluster member to other peers and to
the Worker tier (defaults can be changed in apinizer-cache.env):

  5701/tcp   Hazelcast wire protocol (member-to-member, Worker
             clients). MANDATORY between Cache nodes.
  8090/tcp   Spring Boot HTTP (Worker REST calls into Cache).

The HTTP port is the only one the Worker speaks to directly; the
Hazelcast wire port is used by Cache nodes among themselves (and
by the Worker if it is configured as a Hazelcast client — default
in 2026.04.x is HTTP-only, but the option is available).

------------------------------------------------------------
6. Master key safekeeping
------------------------------------------------------------
conf/master.key is generated once during install and is mode 400
(readable only by the apinizer user). If the key is lost, every
ENC(...) value becomes unrecoverable. Back it up to your secrets
vault before changing anything in conf/.
