Integration Guide

Integrate with Oak Chain's decentralized content repository. This guide covers architecture options, API access, and deployment considerations.

Important Distinction: Oak ≠ AEM. Oak is the open-source content repository. AEM is Adobe's product built on Oak. This project builds on Oak directly—AEM integration depends on Adobe's acceptance of custom Oak bundles.

Why This Matters

Integration choices determine whether you can adopt Oak Chain without replatforming existing authoring and delivery workflows.

What You'll Prove

You can pick the right integration path for your current stack.
You can keep JCR-centric authoring while adding validator-backed trust signals.
You can separate structured content truth from binary delivery concerns.

Next Action

Read the integration path table below, then choose either Connector (AEM-first) or SDK (app-first) before moving to implementation.

Overview

Oak Chain exposes content via multiple integration paths:

Integration Path	Availability	Use Case
REST API	✅ Available	Any client (web, mobile, headless)
SSE Streaming	✅ Available	Real-time content updates, EDS delivery
Oak Chain Connector	✅ Available	AEM integration (composite mount via `oak-chain-connector`)
Oak Chain SDK	✅ Available	JavaScript/TypeScript applications (React, Next.js, Node.js)

AEM Integration via Connector

AEM customers integrate via Oak Chain Connector - an AEM-compatible add-on that uses Oak's public SPI layer. The connector:

Uses only public Oak APIs (no fork required)
Follows Adobe AEM Project Archetype structure
Works with AEM 6.5 LTS and AEM as a Cloud Service
Provides composite mount for read-only oak-chain content
Includes wallet services for write proposals

For non-AEM applications, use the validator HTTP API directly today, or adopt the Oak Chain SDK once its write-side contract realignment lands.

Architecture: JCR is Truth

Oak Chain follows the same principle as traditional AEM: JCR is the source of truth. All content authoring happens via JCR API (AEM Connector) or the validator REST API. EDS is a delivery optimization layer that consumes content changes via SSE.

Layer	Role	Technology	What's Stored
Authoring	Content creation via JCR API	AEM Connector / direct validator clients / SDK clients-in-progress → Validators	—
Storage (Structured)	Consensus-replicated Oak segments	Validator cluster (Raft)	Content nodes + CIDs (46 bytes)
Storage (Binaries)	IPFS binary hosting	Author-owned or Validator-hosted IPFS	Actual binary files
Delivery	Edge-optimized content serving	EDS (aem.live) via SSE subscription	Cached content + binaries

Binary Storage: IPFS

Validators store CIDs only (content-addressed hashes, 46 bytes each), not the binaries themselves. Binaries are stored in IPFS.

Two hosting models:

Model	Who Hosts IPFS	Best For
Author-owned	Author runs/pins their own IPFS node	Full control, existing IPFS infrastructure
Validator-hosted	Validators offer IPFS hosting as a service	Convenience, CDN-optimized placement

┌─────────────────────────────────────────────────────────────────────────────┐
│  BINARY FLOW: Truth → Provenance → Edge                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Author uploads binary to IPFS                                              │
│         │                                                                   │
│         ▼                                                                   │
│  ┌─────────────────┐     CID (46 bytes)      ┌─────────────────┐            │
│  │ IPFS            │ ──────────────────────► │   Validators    │            │
│  │ (author-owned   │                         │   (Oak segments)│            │
│  │  or validator-  │                         │   Store: CIDs   │            │
│  │  hosted)        │                         │   NOT binaries  │            │
│  └────────┬────────┘                         └─────────────────┘            │
│           │                                                                 │
│           │ Served via IPFS gateway / edge                                  │
│           ▼                                                                 │
│  ┌─────────────────┐                                                        │
│  │ Edge CDN        │  CID = perfect cache key (immutable)                   │
│  │                 │  User can verify: hash(binary) === CID                 │
│  └─────────────────┘                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

See Binary Storage Guide for implementation details.

The SSE Integration

Validators emit Server-Sent Events when content changes. EDS (or any delivery tier) subscribes to these events for cache invalidation:

Author writes → Validators consensus → SSE event emitted → EDS invalidates → Fresh content at edge

This guide focuses on API-based integration — the path that works today for any consumer.

Planning & Prerequisites

Technical Requirements

Requirement	Version	Notes
Oak	1.22+ on AEM 6.5, 1.40+ on AEMaaCS	Check `oak-core` bundle version
Java	11+	JDK, not JRE
AEM	6.5 SP15+ or AEMaaCS	Earlier versions require assessment
Network	HTTPS outbound	Firewall rules for validator endpoints

Supported Platforms

Adobe Experience Manager (on-prem, AMS, AEMaaCS)
Apache Sling
Other Oak-based CMS/CRM systems

Project Planning

Phase	Duration	Activities
Assessment	1-2 weeks	Architecture review, network planning, security assessment
Development	2-4 weeks	Bundle deployment, configuration, local testing
Staging	2-4 weeks	Integration testing, performance validation, UAT
Production	1-2 weeks	Phased rollout, monitoring, stabilization

Implementation

Phase 1: Connector Deployment

Deploy Oak Chain Connector to your AEM instance. The connector is an AEM package that can be installed via Package Manager.

On-Premises AEM:

bash

# Upload connector package via Package Manager
# Navigate to: http://localhost:4502/crx/packmgr
# Upload: oak-chain-connector.all-1.0.0-SNAPSHOT.zip
# Install and activate

AEMaaCS / Cloud Manager:

bash

# Add connector to your AEM project
# Install via Cloud Manager pipeline
# Configure via OSGi configuration files

Quick Install:

bash

# Clone connector repository
git clone https://github.com/somarc/oak-chain-connector.git
cd oak-chain-connector

# Build connector package
mvn clean install

# Install to local AEM instance
mvn clean install -PautoInstallPackage

See Oak Chain Connector README for complete installation instructions.

Phase 2: OSGi Configuration

Configure the connector via OSGi configuration. The connector uses standard AEM configuration patterns.

HTTP Persistence Service (com.oakchain.connector.persistence.HttpPersistenceService.cfg.json):

json

{
  "globalStoreUrl": "$[env:OAK_CHAIN_VALIDATOR_URL;default=http://localhost:8090]",
  "lazyMount": true,
  "healthCheckIntervalSeconds": 10,
  "connectionTimeoutMs": 3000
}

Wallet Service (com.oakchain.connector.wallet.SlingAuthorWalletService.cfg.json):

json

{
  "enabled": true,
  "keystorePath": "$[env:OAK_CHAIN_KEYSTORE_PATH]"
}

Environment Variables:

bash

export OAK_CHAIN_VALIDATOR_URL="http://localhost:8090"
export OAK_CHAIN_KEYSTORE_PATH="/path/to/wallet.properties"

Point OAK_CHAIN_VALIDATOR_URL at a validator you operate or can reach on your network. This doc does not assume a shared public hosted validator endpoint.

Phase 3: Validation

After deployment, verify the mount is active:

Via JCR API:

java

Session session = resourceResolver.adaptTo(Session.class);
if (session.nodeExists("/oak-chain")) {
    Node oakChainRoot = session.getNode("/oak-chain");
    log.info("Oak Chain mount active: {}", oakChainRoot.getPath());
} else {
    log.error("Oak Chain mount not available - check configuration");
}

Via Sling ResourceResolver:

java

Resource oakChainContent = resourceResolver.getResource("/oak-chain/0x742d.../content/page");
if (oakChainContent != null) {
    ValueMap props = oakChainContent.getValueMap();
    String title = props.get("jcr:title", String.class);
    log.info("Oak Chain content accessible: {}", title);
}

Via curl (for quick checks):

bash

curl -u admin:admin http://localhost:4502/oak-chain.json

Configuration Reference

Environment Variables

Variable	Description	Default
`OAK_CHAIN_ENDPOINT`	Validator cluster URL	`http://localhost:8090`
`OAK_CHAIN_TIMEOUT`	HTTP timeout (ms)	`30000`
`OAK_CHAIN_CACHE_SIZE`	Segment cache size (MB)	`256`
`OAK_CHAIN_RETRY_COUNT`	Retry attempts	`3`

OSGi Configuration

Full configuration (org.apache.jackrabbit.oak.segment.http.HttpPersistence.cfg.json):

json

{
  "endpoint": "http://localhost:8090",
  "timeout": 30000,
  "cacheSize": 268435456,
  "retryCount": 3,
  "retryDelay": 1000,
  "connectionPoolSize": 10,
  "validateCertificates": true
}

Binary Storage

Oak Chain stores CIDs only (46 bytes), not binaries. Binaries live at the author's source.

How It Works

Oak Chain stores the CID (content-addressed hash)
Author hosts the binary (IPFS, Azure Blob, or pinning service)
Edge CDN caches the binary globally
User can verify binary integrity against the CID

Retrieving Binaries

java

// Binary stored as CID reference in Oak Chain
Property dataProp = node.getProperty("jcr:data");
String cidUri = dataProp.getString(); // "ipfs://QmXyz..."

// Option 1: Direct IPFS fetch
String cid = cidUri.replace("ipfs://", "");
String gatewayUrl = "https://ipfs.io/ipfs/" + cid;

// Option 2: Via IPFS client
InputStream binary = ipfsClient.cat(cid);

Storage Options

Option	SLA	Cost	Best For
Self-hosted IPFS	Best-effort	~$5/mo VPS	Dev/small scale
Pinata/Filebase	99.9%	~$20/mo/TB	Startups
Azure Blob + IPFS CID	99.99%	~$0.02/GB	Enterprise (AMS, AEMaaCS)

Platform-Specific Notes

⚠️ Important: Platform-specific deployment procedures are not yet documented. The connector has been tested on local AEM instances via Package Manager installation. For AMS, AEMaaCS, or other deployment scenarios, refer to the Oak Chain Connector README and consult with your AEM administrator or Adobe Support.

Currently Verified:

✅ Local AEM 6.5.x installation via Package Manager
✅ Local AEM instance via Maven autoInstallPackage profile

Not Yet Documented:

⚠️ Adobe Managed Services (AMS) deployment
⚠️ AEM as a Cloud Service (AEMaaCS) deployment
⚠️ Apache Sling standalone deployment

For the most current installation instructions, see the Oak Chain Connector repository.

Troubleshooting

Mount Not Appearing

Symptom: /oak-chain path returns 404

Solutions:

Verify connector bundle is active: /system/console/bundles → search "oak-chain-connector"
Check OSGi config is deployed: /system/console/configMgr → search "HttpPersistenceService"
Verify network connectivity to validator endpoint
Check AEM error logs for connection errors
Verify environment variables are set correctly

Slow Performance

Symptom: Oak Chain content loads slowly

Solutions:

Increase cache size: OAK_CHAIN_CACHE_SIZE=512
Check network latency to validators
Enable segment prefetching
Consider regional validator deployment

Certificate Errors

Symptom: SSL/TLS handshake failures

Solutions:

Ensure JVM trusts validator certificates
Add CA to Java truststore: keytool -import -trustcacerts -file ca.crt -keystore $JAVA_HOME/lib/security/cacerts
For testing only: validateCertificates: false (NOT for production)

Security Considerations

Read-Only Access

The Oak Chain mount is read-only by design. Your AEM instance cannot modify Oak Chain content—only read it.

Network Security

Use TLS for all connections to validators
Configure firewall rules to allow outbound HTTPS (443)
Consider VPN or private endpoints for sensitive deployments

Content Verification

Oak Chain content is cryptographically signed. You can verify authenticity:

java

// Get content signature
String signature = node.getProperty("oak:signature").getString();
String walletAddress = node.getProperty("oak:author").getString();

// Verify signature (using Web3j or similar)
boolean valid = verifySignature(content, signature, walletAddress);

Next Steps

Binary Storage Guide - Deep dive into IPFS integration
API Reference - Full API documentation
Run a Validator - Join the network
FAQ - Common questions answered

← Back to Guide

Integration Guide ​

Why This Matters ​

What You'll Prove ​

Next Action ​

Overview ​

AEM Integration via Connector ​

Architecture: JCR is Truth ​

Binary Storage: IPFS ​

The SSE Integration ​

Planning & Prerequisites ​

Technical Requirements ​

Supported Platforms ​

Project Planning ​

Implementation ​

Phase 1: Connector Deployment ​

Phase 2: OSGi Configuration ​

Phase 3: Validation ​

Configuration Reference ​

Environment Variables ​

OSGi Configuration ​

Binary Storage ​

How It Works ​

Retrieving Binaries ​

Storage Options ​

Platform-Specific Notes ​

Troubleshooting ​

Mount Not Appearing ​

Slow Performance ​

Certificate Errors ​

Security Considerations ​

Read-Only Access ​

Network Security ​

Content Verification ​

Next Steps ​

Integration Guide

Why This Matters

What You'll Prove

Next Action

Overview

AEM Integration via Connector

Architecture: JCR is Truth

Binary Storage: IPFS

The SSE Integration

Planning & Prerequisites

Technical Requirements

Supported Platforms

Project Planning

Implementation

Phase 1: Connector Deployment

Phase 2: OSGi Configuration

Phase 3: Validation

Configuration Reference

Environment Variables

OSGi Configuration

Binary Storage

How It Works

Retrieving Binaries

Storage Options

Platform-Specific Notes

Troubleshooting

Mount Not Appearing

Slow Performance

Certificate Errors

Security Considerations

Read-Only Access

Network Security

Content Verification

Next Steps