Quick Start

Get Kestros running

Stand up a local Kestros instance with Docker, scaffold a new project with the Maven archetype (a project scaffold generator), then build and deploy it to your instance. From an empty folder to a running site in a few commands.

1Prerequisites

You will need the following installed before you begin:

Java (JDK) 11 or higher
Apache Maven 3.x
Docker and Docker Compose, and on an Apple-silicon Mac, OrbStack works well

Any Java IDE works for development. In IntelliJ IDEA you can attach a debugger using the JVM arguments shown in the Debug Mode note below.

2Run Kestros with Docker

Create an empty folder and add a Docker Compose file named kestros.yaml with the following contents:

kestros.yaml

services:
  kestros:
    image: kestros/kestros-pro-dev:0.9.0   # or latest version
    container_name: kestros-pro-dev       # or desired tier
    restart: unless-stopped
    volumes:
      - ./launcher:/opt/kestros/launcher  # optional
      - ./logs:/opt/kestros/launcher/logs
    ports:
      - 8080:8080

Then start the instance:

bash: start Kestros

$ docker compose -f kestros.yaml up

First boot can take a minute or two while the instance warms up.

To run in debug mode (and, on Apple silicon, to avoid a platform mismatch), add these to the kestros service in kestros.yaml:

kestros.yaml (debug options)

services:
  kestros:
    # ...existing image, volumes, etc.
    platform: linux/amd64        # only if you hit a platform mismatch
    environment:
      JAVA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:30303"
    ports:
      - 8080:8080
      - 30303:30303     # debugger port

3Create a project

Scaffold a new Kestros project with the Maven archetype. Run non-interactively, it requires every parameter shown below, including the easy-to-miss artifactIdNoSpecialCharacters and artifactIdShorthand:

bash: scaffold a new project

$ mvn -B archetype:generate \
    -DarchetypeGroupId=io.kestros.cms \
    -DarchetypeArtifactId=kestros-project-archetype \
    -DarchetypeVersion=0.9.0 \
    -DgroupId=com.example \
    -DartifactId=mysite \
    -Dversion=0.0.1-SNAPSHOT \
    -DartifactName=mysite \
    -DartifactDescription=mysite \
    -DorganizationName=Example \
    -DartifactIdNoSpecialCharacters=mysite \
    -DartifactIdShorthand=ms \
    -DhasParentProject=n \
    -DhashSymbol="#"

The archetype generates four modules: api (Java interfaces and exceptions), core (services and general-purpose Sling Models), application (UI frameworks, UI libraries, and components with their Sling Models), and content (sample site content).

4Build & deploy

From your project root, build and deploy every module to the running instance with the install profiles:

bash: build & deploy

$ cd mysite
$ mvn clean install -PinstallBundle,installPackage,installContent

[INFO] Building mysite
[INFO] BUILD SUCCESS

The install profiles map to the project modules. A bundle is compiled Java (an OSGi module), while a package is JCR content nodes, so installBundle deploys the api and core bundles, while installPackage and installContent deploy content packages, with installPackage also carrying the application bundle:

installBundle: installs the api and core bundles
installPackage: installs the application package and bundle
installContent: installs the content package

Plain mvn clean install only builds. Nothing reaches the instance without the install profiles. Content package installs are asynchronous, so check your content a few seconds after BUILD SUCCESS. Deploy targets default to localhost / 8080; override with -Dsling.host=, -Dsling.port=, -Dsling.username= and -Dsling.password=.

5Verify it's running

Your instance is running at http://localhost:8080 with default credentials admin / admin. After login you land on the sites list. Your generated site renders directly at http://localhost:8080/content/sites/<artifactId>.html (for the mysite example above, that is http://localhost:8080/content/sites/mysite.html). That content URL is also the simplest way to confirm the deploy from a script (a plain curl returns the rendered HTML; the sites list itself is loaded by JavaScript). If a node looks missing right after BUILD SUCCESS, wait a few seconds and refresh: content package installs run asynchronously after the build reports success.

Not seeing the login page? Give the instance a moment: first boot warms up caches before the UI responds. Check the container logs (./logs in your Docker folder) if it stays unresponsive.

6Next steps

You have a running instance and a deployed project. From here, the Developer Guide walks through how Kestros is put together and how to build your own components, frameworks and dialogs:

Architecture & Concepts: how Apache Sling, JCR and HTL fit together, and the Kestros component model built on top of them.
Components: the building blocks of every page, with definition resources, Sling Models, dialogs and views.