Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/manage-environments

manage-environments

Verified

Manage workspace environment configurations (local/dev/uat/prod), promote changes between environments, export object data models, and capture a running site as a reusable site initializer CET. Use when the user asks to promote to UAT, export this site, migrate object data, or set up environment specific properties.

FileKindSize
SKILL.mdskill md7.8 KB
---

description: Manage workspace environment configurations (local/dev/uat/prod), promote changes between environments, export object data models, and capture a running site as a reusable site initializer CET. Use when the user asks to promote to UAT, export this site, migrate object data, or set up environment specific properties.
name: manage-environments

---

# Manage Environments

Switch portal configurations per deployment target, promote property changes between environments, export data models, and capture a live site as a site initializer.

## When to Invoke

- "Promote to UAT", "add a UAT environment config"
- "Export the object definitions so we can import them to production"
- "Capture the current site as a site initializer for version control"
- "Set up a database connection for dev"
- Called by `build-site` after runtime iteration when the user wants to commit the site to source control

## Workspace Environment Model

The `configs` directory holds one directory per environment. Each directory may contain a `portal-ext.properties` that overrides the common config.

```
configs/
  common/          # Applied to every environment
  local/           # Developer workstation (default)
  dev/             # Shared dev server
  uat/             # User acceptance testing
  prod/            # Production
  docker/          # Docker / container deployments
```

The active environment is set by `liferay.workspace.environment` in `gradle.properties`. Default is `local`.

Blade merges properties in order: `common/portal-ext.properties` then `<env>/portal-ext.properties`. The merge result lands in `bundles/portal-ext.properties`.

## Workflow

### Declare the Target Environment

Check `gradle.properties`:

```bash
grep "liferay.workspace.environment" gradle.properties
```

To switch environments:

```bash
# Edit gradle.properties

liferay.workspace.environment=uat
```

Then run `blade gw initBundle` to merge and push configs (applies to remote/UAT server initialization only — do not use for local dev bundles; see `deploy-and-verify`). Alternatively, set the environment at deploy time:

```bash
blade gw deploy -Pliferay.workspace.environment=uat
```

### Add or Update Environment Properties

Edit `configs/<env>/portal-ext.properties` with the target environment's values. Common properties per environment:

```properties
# Database (dev example)

jdbc.default.driverClassName=org.mariadb.jdbc.Driver
jdbc.default.url=jdbc:mariadb://localhost:3306/liferay_dev
jdbc.default.username=liferay
jdbc.default.password=liferay

# Elasticsearch

com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.operationMode=REMOTE
com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.networkHostAddresses=["https://elasticsearch-dev:9200"]

# Mail (disable for dev)

mail.send.blacklist=*
```

### Export Object Definitions

There is **no** `/object-definitions/{id}/export` or `/object-definitions/import` endpoint. Migrate object **definitions** through the Batch Engine endpoints on `object-admin`:

```bash
# Export object definitions

curl \
	--data '{"callbackURL": "", "fieldNames": ["name", "label", "pluralLabel", "scope", "objectFields"], "taskItemDelegateName": "DEFAULT"}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions/export-batch" \
	--user "test@liferay.com:test"

# Import on the target environment (batch create/update)

curl \
	--data @object-definitions.json \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/object-admin/v1.0/object-definitions/batch" \
	--user "test@liferay.com:test"
```

Confirm the exact request bodies against the OpenAPI spec (`get-openapi` MCP tool, or fetch `GET /o/object-admin/v1.0/openapi.json` with curl). For source controlled migration, prefer the site initializer's `object-definitions` and `list-type-definitions` directories (see `rules/site-initializer-format.md`), or a separate `type: batch` CET for bulk data (see `manage-objects` → the batch CET section). A `batch` directory **inside** a site initializer is packaged and then never read — no initializer handler looks for it.

### Export Object Data (Batch)

Export entries from a live environment for bulk import elsewhere:

```bash
# Request an export task

curl \
	--data '{
		"fieldNames": ["<field1>", "<field2>"],
		"taskItemDelegateName": "<pluralLabel>"
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/headless-batch-engine/v1.0/export-task/com.liferay.object.rest.dto.v1_0.ObjectEntry/JSON" \
	--user "test@liferay.com:test"
```

Poll the task until `"executeStatus": "COMPLETED"`, then download the content from the returned `contentURL`.

#### Batch Engine — Silent Field Skipping

BatchEngine silently skips unrecognized fields during import — it logs a `Cannot invoke` warning to `catalina.out` rather than failing the task. The import reports success and the task transitions to `COMPLETED` even when entire fields were dropped.

Ensure JSON field names exactly match the target Object Definition's field names before importing. Treat any `Cannot invoke` warning in `catalina.out` during an import as a hard error and cross check field names before retrying. After every import, GET a sample entry and confirm the imported fields actually persisted.

### Capture a Site as a Site Initializer

The `siteInitializer` CET pattern stores the site in source control so any environment can recreate it.

**Step 1 — Scaffold the CET structure** via `scaffold-client-extension` with type `siteInitializer`.

**Step 2 — Capture pages**: For each live page, call the Headless Admin Site API and write the result to `site-initializer/layouts/<NN-page-name>/page.json` and `page-definition.json`:

```bash
curl \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>/site-pages/<page-erc>?nestedFields=pageSpecifications" \
	--user "test@liferay.com:test" \
	| jq '{friendlyURL: .friendlyUrlPath_i18n.en_US, name: .name_i18n.en_US, type: .type}' \
	> site-initializer/layouts/01_home/page.json

# Note: there is no /site-pages/{id}/page-definition subresource. The page composition lives in
# the page's pageSpecifications (fetched via ?nestedFields=pageSpecifications above) and must be
# reshaped into the initializer's page-definition.json format. Confirm the shape via the OpenAPI
# spec (get-openapi MCP tool, or GET /o/headless-admin-site/v1.0/openapi.json).
```

**Step 3 — Capture object definitions**: Export definitions and place them under `site-initializer/batch/02-object-definition.batch-engine-data.json` using the batch engine data format (see `rules/site-initializer-format.md`).

**Step 4 — Capture fragments**: Copy the deployed fragment source directories into `site-initializer/fragments/group`.

**Step 5 — Capture picklists**: Export list type definitions to `site-initializer/batch/00-list-type-definition.batch-engine-data.json`.

**Step 6 — Commit and deploy to the target environment** via `deploy-and-verify`.

### Promote a Config Change to UAT

1. Edit `configs/uat/portal-ext.properties` with the new value.

1. Commit the change.

1. Trigger the deployment pipeline (CI/CD), or push to the UAT server and run `blade gw initBundle`.

1. Bounce Tomcat on the UAT server to pick up the new properties, only after the user confirms — a restart on a Cloud environment always needs confirmation (`liferay-rules.md` → "Server Restarts").

## Success Signal

TODO / inferred — verify against a running bundle. Confirm (per the steps above) that the merged config reaches `bundles/portal-ext.properties`, the batch export task reaches `"executeStatus": "COMPLETED"`, and an entry fetched again shows the imported fields persisted.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall