@jahia/agentic 0.4.1 → 0.5.1

package/dist/antigravity/.agents/skills/jahia-dev-ops/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: jahia-dev-ops
+description: >
+  Operational guidance for running Jahia in production: Docker Compose and
+  Kubernetes deployments, environment configuration, health monitoring,
+  log analysis, and provisioning via the Jahia Provisioning API. Use when
+  the user is deploying, maintaining, debugging, or scaling a Jahia instance
+  (DX, jCustomer, Augmented Search / Elasticsearch, Kibana, Unomi).
+allowed-tools: Read
+---
+
+# Jahia DevOps Skill
+
+This skill covers day-to-day operations of a Jahia platform environment.
+Detailed reference sheets are in `references/`.
+
+## Reference files
+
+| File | Content |
+|------|---------|
+| `references/docker.md` | Docker Compose stacks, environment variables, volume layout, networking, common run-commands |
+| `references/monitoring.md` | Health endpoints, log locations, JVM/GC tuning, Karaf console, alert patterns |
+| `references/provisioning.md` | Jahia Provisioning API (YAML scripts), module lifecycle, site import/export, JCR operations |
+
+## Quick orientation
+
+### Core components
+
+- **Jahia DX** (`jahia/jahia-ee` or `jahia/jahia`) — the main CMS node
+- **jCustomer / Apache Unomi** (`jahia/jcustomer`) — customer data platform
+- **Augmented Search** (`jahia/elasticsearch` wrapper) — search back-end
+- **Kibana** — Unomi analytics dashboard (optional)
+- **MariaDB / MySQL** — relational database for JCR metadata and Jackrabbit bundles
+
+### Typical task flow
+
+1. **Deploy** — pick the right Docker Compose file or Helm chart (see `references/docker.md`)
+2. **Configure** — set env vars for DB, cluster, mail, LDAP (see `references/docker.md`)
+3. **Provision** — push modules, create sites, seed content (see `references/provisioning.md`)
+4. **Monitor** — watch `/healthcheck`, logs, Karaf console (see `references/monitoring.md`)
+5. **Troubleshoot** — collect thread dump, heap dump, or GC log; check OSGi bundle state
+
+### Support escalation checklist
+
+When filing a Jahia Support ticket always attach:
+- `docker-compose.yml` (redact passwords)
+- `jahia.log` (last 500 lines minimum)
+- Output of `/healthcheck?includeDetails=true`
+- Output of `bundle:list` from Karaf console
+- JVM version: `java -version` inside the container

package/dist/antigravity/.agents/skills/jahia-dev-ops/references/docker.md

@@ -0,0 +1,151 @@
+# Jahia Docker Reference
+
+## Image tags
+
+| Image | Stable tag pattern | Notes |
+|-------|--------------------|-------|
+| `jahia/jahia-ee` | `8.2.x.x` | Enterprise Edition (most deployments) |
+| `jahia/jahia` | `8.2.x.x` | Community Edition |
+| `jahia/jcustomer` | `2.6.x` | Apache Unomi-based CDP |
+| `jahia/elasticsearch` | `7.17.x-jahia` | Patched ES image for Augmented Search |
+
+Always pin to an exact version in production. Avoid `latest`.
+
+## Minimal single-node docker-compose.yml
+
+```yaml
+version: "3.8"
+services:
+  jahia:
+    image: jahia/jahia-ee:8.2.4.0
+    ports:
+      - "8080:8080"
+      - "7770:7770"   # Karaf SSH
+    environment:
+      JAHIA_ROOT_PASSWORD: changeme
+      DB_HOST: mariadb
+      DB_NAME: jahia
+      DB_USER: jahia
+      DB_PASS: jahia
+      PROCESSING_SERVER: "true"
+    volumes:
+      - jahia-data:/var/jahia
+      - jahia-logs:/var/log/jahia
+    depends_on:
+      mariadb:
+        condition: service_healthy
+
+  mariadb:
+    image: mariadb:10.11
+    environment:
+      MYSQL_DATABASE: jahia
+      MYSQL_USER: jahia
+      MYSQL_PASSWORD: jahia
+      MYSQL_ROOT_PASSWORD: root
+    volumes:
+      - mariadb-data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  jahia-data:
+  jahia-logs:
+  mariadb-data:
+```
+
+## Key environment variables
+
+### Jahia DX
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `JAHIA_ROOT_PASSWORD` | *(required)* | `root` user password |
+| `DB_HOST` | `mariadb` | Database hostname |
+| `DB_PORT` | `3306` | Database port |
+| `DB_NAME` | `jahia` | Database name |
+| `DB_USER` | `jahia` | Database user |
+| `DB_PASS` | *(required)* | Database password |
+| `PROCESSING_SERVER` | `true` | Enable background processing (set false on non-primary cluster nodes) |
+| `CLUSTER_ENABLED` | `false` | Enable Hazelcast clustering |
+| `CLUSTER_NODES` | | Comma-separated `host:port` list of cluster peers |
+| `MAX_RAM_PERCENTAGE` | `70` | Heap ceiling as % of container RAM |
+| `EXTRA_JAVA_OPTS` | | Append arbitrary JVM flags |
+| `JAHIA_DEPLOY_ON_STARTUP` | | Comma-separated module JAR paths to deploy at first boot |
+| `OPERATING_MODE` | `development` | `development` or `production` |
+| `MAIL_SERVER` | | SMTP URI e.g. `smtp://mail.example.com:25` |
+| `MAIL_FROM` | | Sender address for system mail |
+| `MAIL_ADMIN` | | Admin notification address |
+
+### jCustomer / Unomi
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `UNOMI_ROOT_PASSWORD` | *(required)* | Admin password |
+| `UNOMI_ELASTICSEARCH_ADDRESSES` | `elasticsearch:9200` | ES cluster addresses |
+| `UNOMI_CLUSTER_KUBERNETES` | `false` | Enable K8s cluster discovery |
+| `UNOMI_THIRDPARTY_PROVIDER1_IPADDRESSES` | | Trusted IP ranges (for Jahia → Unomi calls) |
+| `EXTRA_JAVA_OPTS` | | Append JVM flags |
+
+### Elasticsearch (jahia image)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `discovery.type` | `single-node` | Use `zen` for multi-node |
+| `ES_JAVA_OPTS` | `-Xms512m -Xmx512m` | Heap; set both to the same value |
+| `xpack.security.enabled` | `false` | Enable TLS/auth |
+
+## Volume layout inside the Jahia container
+
+```
+/var/jahia/           ← JAHIA_DATA_DIR (repo, bundles, configuration)
+  jackrabbit/         ← JCR workspace
+  modules/            ← Hot-deploy OSGi bundles (.jar)
+  patches/            ← groovy/cfg/spring patches applied at startup
+  digital-factory-config/  ← override jahia.properties / OSGi .cfg
+/var/log/jahia/       ← log4j output files
+  jahia.log
+  access.log
+  errors.log
+```
+
+## Useful run-time commands
+
+```bash
+# Tail combined Jahia logs
+docker compose logs -f jahia
+
+# Enter the container
+docker compose exec jahia bash
+
+# Karaf SSH console (password = same as JAHIA_ROOT_PASSWORD)
+ssh -p 7770 karaf@localhost
+
+# Force redeploy a module (drop the jar into hot-deploy)
+docker compose cp my-module-1.0.jar jahia:/var/jahia/modules/
+
+# Check resource usage
+docker stats jahia mariadb
+
+# One-shot health check
+curl -u root:changeme http://localhost:8080/healthcheck?includeDetails=true
+```
+
+## Cluster (Hazelcast) quick checklist
+
+1. Set `CLUSTER_ENABLED=true` on all nodes.
+2. All nodes must share the same `DB_*` credentials pointing at the same DB.
+3. `PROCESSING_SERVER=true` on exactly **one** node (the processing node).
+4. Expose port `5900` between containers/pods for Hazelcast.
+5. Mount a shared NFS or object-store volume for `/var/jahia/jackrabbit/repository/datastore`.
+6. Verify membership: Karaf console → `cluster:info`.
+
+## Kubernetes notes
+
+- Use the official Jahia Helm chart (`jahia/jahia`) from `https://charts.jahia.com`.
+- Set `jahia.processingServer.replicas=1` and `jahia.browsing.replicas=N`.
+- Use a `ReadWriteMany` PVC (e.g. EFS / NFS) for the datastore.
+- Liveness probe: `GET /healthcheck` — expect HTTP 200.
+- Readiness probe: `GET /healthcheck?includeDetails=true` — parse `"status":"GREEN"`.

package/dist/antigravity/.agents/skills/jahia-dev-ops/references/monitoring.md

@@ -0,0 +1,195 @@
+# Jahia Monitoring Reference
+
+## Health endpoints
+
+| Endpoint | Auth | Returns |
+|----------|------|---------|
+| `GET /healthcheck` | None | `{"status":"GREEN"}` or non-200 |
+| `GET /healthcheck?includeDetails=true` | Basic (root) | Full JSON with per-probe status |
+| `GET /modules/healthcheck` | Basic (root) | Module-level detail |
+| `GET /live` | None | Kubernetes liveness (200 = alive) |
+| `GET /ready` | None | Kubernetes readiness (200 = ready to serve) |
+
+### Interpreting `/healthcheck?includeDetails=true`
+
+```json
+{
+  "status": "GREEN",      // GREEN | YELLOW | RED
+  "probes": {
+    "DatabaseProbe":    { "status": "GREEN" },
+    "ServerLoadProbe":  { "status": "YELLOW", "message": "Load: 3.4" },
+    "JCRProbe":         { "status": "GREEN" }
+  }
+}
+```
+
+A `RED` status means the instance should not receive traffic. A `YELLOW` means
+degraded but still functional. Common probe names: `DatabaseProbe`,
+`JCRProbe`, `ServerLoadProbe`, `ModulesProbe`, `ClusterProbe`.
+
+## Log files
+
+| File | Content |
+|------|---------|
+| `/var/log/jahia/jahia.log` | Main application log (INFO+) |
+| `/var/log/jahia/errors.log` | ERROR-only mirror of jahia.log |
+| `/var/log/jahia/access.log` | HTTP access log (Combined format) |
+| `/var/log/jahia/jahia_audit.log` | Security/audit events |
+| `/var/log/jahia/gc.log*` | GC log (if `-Xlog:gc*` enabled) |
+
+### Key log patterns to watch
+
+```
+# Module deployment failure
+ERROR.*BundleException
+ERROR.*Failed to deploy module
+
+# JCR / Jackrabbit errors
+ERROR.*RepositoryException
+ERROR.*ItemExistsException
+
+# DB connectivity
+ERROR.*Cannot get a connection
+ERROR.*Communications link failure
+
+# Out of memory / GC pressure
+java.lang.OutOfMemoryError
+GC overhead limit exceeded
+
+# Cluster split-brain
+WARN.*Hazelcast.*member.*left
+ERROR.*ClusterProbe
+
+# Session leaks / thread pool exhaustion
+WARN.*Maximum pool size reached
+WARN.*No active session
+```
+
+### Useful log grep commands
+
+```bash
+# All ERRORs in the last hour (adjust tail count)
+docker compose exec jahia grep "^[0-9].*ERROR" /var/log/jahia/jahia.log | tail -200
+
+# Module-related events today
+docker compose exec jahia grep -i "module\|bundle\|deploy" /var/log/jahia/jahia.log | grep "$(date +%Y-%m-%d)"
+
+# Slow queries (threshold 1000 ms is default)
+docker compose exec jahia grep "SlowQuery\|slow query" /var/log/jahia/jahia.log
+```
+
+## Karaf console
+
+Connect via SSH (port 7770 by default):
+
+```bash
+ssh -p 7770 karaf@localhost
+# Password = JAHIA_ROOT_PASSWORD
+```
+
+### Essential Karaf commands
+
+```
+# OSGi bundle state
+bundle:list                         # List all bundles + state
+bundle:list | grep -v Active        # Only non-Active bundles (problem candidates)
+bundle:diag <bundle-id>             # Diagnose a specific bundle (missing imports etc.)
+bundle:start <bundle-id>
+bundle:stop  <bundle-id>
+bundle:refresh <bundle-id>
+
+# Module management
+module:list                         # Jahia modules + version + state
+jahia:deploy <path-to-jar>          # Deploy a module from local path
+
+# Cluster
+cluster:info                        # Show Hazelcast cluster members
+cluster:manager-node                # Show which node is the manager
+
+# System info
+info                                # JVM / Karaf version summary
+threads                             # Thread count snapshot
+memory                              # Heap / non-heap usage
+
+# Log level (temporary, reverts on restart)
+log:set DEBUG org.jahia.services.content
+log:set INFO  org.jahia.services.content   # reset
+
+# Display live log tail inside Karaf
+log:tail
+```
+
+## JVM tuning
+
+### Heap sizing
+
+Set `MAX_RAM_PERCENTAGE` env var (e.g. `75`) to let the JVM auto-size to a
+percentage of container RAM. Alternatively set explicit flags via `EXTRA_JAVA_OPTS`:
+
+```
+EXTRA_JAVA_OPTS=-Xms2g -Xmx4g
+```
+
+Rule of thumb: 4 GB heap minimum for a single-node dev instance; 8–16 GB for
+production with content-heavy sites.
+
+### GC logging (add to EXTRA_JAVA_OPTS)
+
+```
+-Xlog:gc*:file=/var/log/jahia/gc.log:time,uptime,level,tags:filecount=5,filesize=20m
+```
+
+### Thread dump
+
+```bash
+# Get PID inside container
+docker compose exec jahia bash -c 'jps | grep Jahia'
+# Take dump (replace <PID>)
+docker compose exec jahia bash -c 'kill -3 <PID>'
+# Output goes to jahia.log
+```
+
+Or from Karaf: `threads --list` for a quick summary.
+
+### Heap dump on OOM (add to EXTRA_JAVA_OPTS)
+
+```
+-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/jahia/heapdump.hprof
+```
+
+## jCustomer (Unomi) monitoring
+
+```bash
+# Health
+curl http://localhost:8181/cxs/actuator/health
+
+# Cluster nodes (REST)
+curl -u karaf:karaf http://localhost:8181/cxs/cluster
+
+# Karaf console (port 8101)
+ssh -p 8101 karaf@localhost
+```
+
+## Elasticsearch monitoring
+
+```bash
+# Cluster health
+curl http://localhost:9200/_cluster/health?pretty
+
+# Index sizes
+curl http://localhost:9200/_cat/indices?v&h=index,docs.count,store.size
+
+# Pending tasks
+curl http://localhost:9200/_cluster/pending_tasks
+```
+
+## Alerting thresholds (suggested)
+
+| Metric | Warning | Critical |
+|--------|---------|---------|
+| Heap usage | 75 % | 90 % |
+| Jahia healthcheck status | YELLOW | RED |
+| DB connection pool | 80 % utilised | 95 % utilised |
+| Error log rate | > 10/min | > 50/min |
+| ES cluster health | YELLOW | RED |
+| GC pause (G1GC stop-the-world) | > 500 ms | > 2 s |

package/dist/antigravity/.agents/skills/jahia-dev-ops/references/provisioning.md

@@ -0,0 +1,269 @@
+# Jahia Provisioning Reference
+
+## Provisioning API overview
+
+The Jahia Provisioning API (introduced in DX 8.x) executes YAML scripts that
+install modules, create sites, configure OSGi services, and seed JCR content.
+Scripts can be:
+
+- Placed in `/var/jahia/patches/` — executed automatically at startup.
+- POSTed to the REST endpoint: `POST /modules/api/provisioning`.
+
+## REST endpoint
+
+```
+POST /modules/api/provisioning
+Authorization: Basic <base64(root:password)>
+Content-Type: application/yaml   (or multipart/form-data)
+
+<provisioning script body>
+```
+
+### Upload via curl
+
+```bash
+curl -u root:changeme \
+     -X POST \
+     -H "Content-Type: application/yaml" \
+     --data-binary @my-script.yaml \
+     http://localhost:8080/modules/api/provisioning
+```
+
+### Upload via multipart (with file)
+
+```bash
+curl -u root:changeme \
+     -F "script=@my-script.yaml" \
+     http://localhost:8080/modules/api/provisioning
+```
+
+## Script structure
+
+```yaml
+# provisioning-script.yaml
+- installOrUpgradeModules:
+    - url: "mvn:org.jahia.modules/article/3.5.0"
+    - url: "file:///var/jahia/modules/my-custom-module-1.0.jar"
+
+- createSite: ""
+  siteKey: mySite
+  title: "My Site"
+  defaultLanguage: en
+  serverName: localhost
+  templateSet: my-template-set
+
+- importSite:
+    siteKey: mySite
+    uri: "file:///var/jahia/imports/mySite-export.zip"
+```
+
+## Common provisioning operations
+
+### Install / upgrade a module from Maven
+
+```yaml
+- installOrUpgradeModules:
+    - url: "mvn:org.jahia.modules/bootstrap4-core/4.0.0"
+    - url: "mvn:org.jahia.modules/bootstrap4-components/4.0.0"
+```
+
+### Install from a local file
+
+```yaml
+- installOrUpgradeModules:
+    - url: "file:///var/jahia/modules/my-module-1.0.jar"
+```
+
+### Enable / start a module
+
+```yaml
+- startModules:
+    - name: my-module
+```
+
+### Disable / stop a module
+
+```yaml
+- stopModules:
+    - name: my-module
+```
+
+### Uninstall a module
+
+```yaml
+- uninstallModules:
+    - name: my-module
+```
+
+### Create a virtual site
+
+> ⚠️ **CRITICAL — Jahia 8.2 syntax**: use `- createSite: ""` with properties at the **same indentation level**. There are **two common mistakes that both silently return HTTP 200 but create nothing**:
+> - ❌ `- createSite:` with nested properties (missing `""`)
+> - ❌ `- createVirtualSite:` (old name, no longer valid)
+> 
+> **Always use a file-based approach** to avoid shell quoting issues:
+
+```bash
+cat > /tmp/create-site.yaml <<'EOF'
+- createSite: ""
+  siteKey: acme
+  title: "ACME Corp"
+  defaultLanguage: en
+  serverName: localhost
+  templateSet: acme-template-set
+EOF
+
+curl -u root:root1234 -X POST -H "Content-Type: application/yaml" \
+  --data-binary @/tmp/create-site.yaml \
+  http://localhost:8080/modules/api/provisioning
+```
+
+The API returns `HTTP 200` with an empty body. **Always verify** the site was created — HTTP 200 is not sufficient confirmation:
+
+```bash
+curl -s -u root:root1234 \
+  -H "Content-Type: application/json" -H "Origin: http://localhost:8080" \
+  -X POST http://localhost:8080/modules/graphql \
+  -d '{"query":"{ jcr { nodeByPath(path: \"/sites/acme\") { name } } }"}'
+```
+
+If the response contains `"name": "acme"`, the site exists. If it returns `null`, the site was not created — recheck the YAML format.
+
+### Delete a virtual site
+
+```bash
+curl -u root:root1234 \
+     -X POST \
+     -H "Content-Type: application/yaml" \
+     --data-binary '- deleteSite: ""
+  siteKey: acme' \
+     http://localhost:8080/modules/api/provisioning
+```
+
+### Import a site export ZIP
+
+```yaml
+- importSite:
+    siteKey: acme
+    uri: "file:///var/jahia/imports/acme-export.zip"
+    rootUsersGroup: site-admins
+```
+
+### Execute a Groovy script
+
+```yaml
+- executeScript:
+    script: "file:///var/jahia/patches/migrate-content.groovy"
+```
+
+Or inline:
+
+```yaml
+- executeScript:
+    scriptContent: |
+      import org.jahia.services.content.*
+      def session = JCRSessionFactory.getInstance().getCurrentSystemSession("default", null, null)
+      // ... do work ...
+      session.save()
+```
+
+### Set a system property / OSGi configuration
+
+```yaml
+- setSystemProperty:
+    name: my.custom.property
+    value: "my-value"
+```
+
+```yaml
+- setOsgiConfiguration:
+    pid: "org.jahia.services.content.nodetypes.NodeTypeRegistry"
+    properties:
+      autoDeployBundles: "true"
+```
+
+### Add a user
+
+```yaml
+- addUser:
+    username: john.doe
+    password: secret123
+    email: john.doe@example.com
+    firstName: John
+    lastName: Doe
+    roles:
+      - site-administrator:acme
+```
+
+### Grant a role on a node
+
+```yaml
+- grantRoles:
+    path: /sites/acme
+    principal: "u:john.doe"
+    roles:
+      - site-administrator
+```
+
+## Patches directory
+
+Files placed in `/var/jahia/patches/` are executed **once** at startup
+(Jahia records which files have already been applied):
+
+```
+/var/jahia/patches/
+  cfg/               ← OSGi .cfg files
+  spring/            ← Spring XML context overrides
+  groovy/            ← Groovy scripts (executed once)
+  yaml/              ← Provisioning YAML scripts (executed once)
+```
+
+Mount a host directory here to inject patches without rebuilding the image:
+
+```yaml
+volumes:
+  - ./patches:/var/jahia/patches
+```
+
+## Execution order and idempotency
+
+- Provisioning YAML scripts in `patches/yaml/` are sorted alphabetically.
+  Prefix filenames with a two-digit index (`01-modules.yaml`, `02-sites.yaml`)
+  to control order.
+- Most operations are idempotent: `installOrUpgradeModules` skips if the exact
+  version is already installed; `createVirtualSite` skips if the site key exists.
+- Groovy scripts in `patches/groovy/` run exactly once; rename the file to
+  force re-execution.
+
+## Checking provisioning status
+
+```bash
+# View provisioning log output (appears in jahia.log)
+docker compose exec jahia grep -i "provisioning\|install.*module\|createVirtualSite" /var/log/jahia/jahia.log
+
+# List applied patches via Karaf
+ssh -p 7770 karaf@localhost
+# In Karaf:
+jahia:patches-list
+```
+
+## jCustomer (Unomi) provisioning
+
+Unomi uses its own REST API and YAML/JSON rules. Key endpoints:
+
+```bash
+# Import a scope
+curl -u karaf:karaf -X POST \
+     -H "Content-Type: application/json" \
+     -d '{"itemId":"mySite","itemType":"scope"}' \
+     http://localhost:8181/cxs/scopes
+
+# Import a rule
+curl -u karaf:karaf -X POST \
+     -H "Content-Type: application/json" \
+     -d @my-rule.json \
+     http://localhost:8181/cxs/rules
+
+# Reload rules from classpath
+curl -u karaf:karaf -X POST http://localhost:8181/cxs/rules/resetQueries
+```