Developers · Installation¶

What you get¶

One JAR — com.habito1:h1-sites — containing:

• 1 light module: h1-sites-light-module, with the content type, the app, the REST endpoint registration, the MCP tool registration and the i18n bundle (default, en, es).
• 3 singleton components registered in the module descriptor: SiteRepository (implemented by JcrSiteRepository), SiteMapper and SiteService.
• 1 REST resource — SiteController — under /.rest/v1/sites, with six operations (list, get by id, resolve, create, update, delete).
• 1 content app (h1-sites-app) over 1 content type (h1-site) and 1 JCR workspace (h1-sites, created on first start by autoCreate: true).
• 1 MCP tool (site), active only when h1-mcp-api is present.

Maven coordinates¶

<dependency>
  <groupId>com.habito1</groupId>
  <artifactId>h1-sites</artifactId>
  <version>1.0.1-SNAPSHOT</version>
</dependency>

Deploy¶

1. Add the dependency to your webapp POM. h1-helpers travels with it as a compile dependency; you do not declare it yourself unless you want to pin its version.
2. Build and deploy the WAR as usual.
3. Start the instance. On first start the module creates the h1-sites workspace and the version handler grants the superuser role full access to it (see Upgrading).
4. Check Tools › Modules for h1-sites and confirm the version.
5. Place the app in a launcher group of your own. The module registers h1-sites-app and ships the group label (app-launcher.h1sites.label), but it does not add the group, so on a fresh instance the app installs correctly and still does not appear in AdminCentral.

Wiring you have to do¶

The module ships the content type, the app, the REST resource and the MCP tool. It cannot guess where in your project they belong.

1. Decide how the front end authenticates¶

The resolution call runs on every page request of a headless front end. Either call it with Basic Auth credentials, or grant the anonymous user read access to the workspace — see Permissions. There is no third option built into the module: it does not expose a public URL of its own.

2. Create the first site¶

Nothing resolves until at least one site exists with a Root Page and at least one row in Domains (regex). A site with no domain rows is never matched.

Permissions¶

The REST resource is read by whoever the front end authenticates as. When the front end calls it anonymously — and on a public instance it usually does — grant anonymous read access to:

Warning — a missing ACL does not surface as an error. GET /v1/sites returns an empty array, getSite returns 404, and h1-seo quietly drops the site globals from its structured data rather than failing. If something is silently empty in production but fine on author, suspect the ACL before suspecting the code.

Verify the installation¶

# Every site
curl -s http://localhost:8080/magnoliaAuthor/.rest/v1/sites

# Resolve by domain
curl -s "http://localhost:8080/magnoliaAuthor/.rest/v1/sites/getSite?domain=www.habito1.com"

# Resolve by root page, the fallback a front end uses when the host matches nothing
curl -s "http://localhost:8080/magnoliaAuthor/.rest/v1/sites/getSite?rootWebsite=/h1"

[] from the first call is a valid answer: the module is installed and the workspace is readable, there are simply no sites yet. A 404 from getSite means no site claimed that domain — check the patterns and the order before assuming the module is broken. A 400 means neither domain nor rootWebsite was sent.

Upgrading¶

The version handler applies these deltas: