Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/workspace-init

workspace-init

Verified

Bootstrap a Liferay Workspace, download and verify the bundle, set up auth verifiers, and complete first login bootstrap. Use when the user is starting fresh, when the server appears down or unreachable, when gradle.properties or bundles/ is missing, or when the user asks to set up, initialize, or scaffold a workspace.

FileKindSize
SKILL.mdskill md14.7 KB
---

description: Bootstrap a Liferay Workspace, download and verify the bundle, set up auth verifiers, and complete first login bootstrap. Use when the user is starting fresh, when the server appears down or unreachable, when gradle.properties or bundles/ is missing, or when the user asks to set up, initialize, or scaffold a workspace.
name: workspace-init

---

# Workspace Init

Stand up a working Liferay Workspace from zero, or diagnose a workspace that looks uninitialized. Covers `blade init`, bundle download, license setup, BasicAuth verifier, server start, and first login bootstrap.

## When to Invoke

- The user asks to set up, initialize, or scaffold a workspace, or asks for setup help.
- The server appears down or unreachable.
- The workspace looks uninitialized — missing the `bundles` directory, or missing `gradle.properties`.
- Do not run through all steps for a returning user whose server is already running.

> **Note:** These rules apply to local workspace initialization and must not be used to configure higher environments (UAT/Prod).

## Workflow

### Version and Tooling Check

- **Check version**: read `liferay.workspace.product` in `gradle.properties`.
- **Verify tooling**: check that `blade` (`blade --version`) and Java (`javac -version`) are installed. If missing, provide installation steps.
- **DXP License**: if `liferay.workspace.product` contains `dxp`, a license file is required. Liferay identifies license files by XML content, not filename — check `bundles/deploy` for any `.xml` file whose root element is `<license>` or `<licenses>`. If none is found, stop and ask the user to place their license file in `bundles/deploy` before continuing. For Docker, apply the same check to the directory mounted to the container's deploy path. Community Edition and free tier products do not require a license — skip this check for those.
- **License is consumed on boot**: Liferay registers the key into the database and deletes the file, so an empty `bundles/deploy` directory on an already booted instance is the normal licensed state, not a missing license. Confirm activation from the log instead — `grep --extended-regexp --ignore-case 'license validation passed|License registered' bundles/tomcat*/logs/catalina.out`. Because the license now lives in the database, **clearing `bundles/data` also discards it**; copy a key again into `bundles/deploy` as part of any such reset.
- **Keep an environment directory in Git**: the workspace plugin refuses to configure unless the `configs` directory holds at least one directory besides `common` and `docker`, and Git does not keep an empty directory. A workspace whose `configs/local` is empty therefore works where it was made, but a fresh clone fails on every Gradle call, `blade gw deploy` included, with `The 'configs' directory must contain one directory not named: common, docker` (verified on a 2026.Q3.5 workspace). Commit a file in it: a `portal-ext.properties`, or an empty `.gitkeep`.

### Environment Readiness and State Sync

#### Configure MCP Before Starting the Server

If the Liferay MCP server is supported in your DXP version (see `skills/mcp-server/SKILL.md`), set it up **now**, before starting Liferay. CLI agents load MCP settings at startup only, and the portal reads its feature flags at boot — getting either half wrong after the server is running costs another full server boot. Do it in this order:

1. Load `skills/mcp-server/SKILL.md` and run its "Audit the Current State First" table. Do not skip it because an MCP entry already appears in the agent's server list — that entry is only the client half and proves nothing about the portal's `LPD-63311` flag, which a fresh bundle never has.

1. Complete only the steps the audit shows missing. Enable the flag in the configuration the bundle will boot with. Fix or add the client entry if needed.

1. If the client configuration changed, prompt the user to exit and restart their CLI session, then verify the MCP server entry appears in the client's server list. A disconnected or failed status is expected — the server is not running yet. If the entry is absent, recheck the MCP configuration before proceeding.

1. Then continue below to start the Liferay server.

Skip this block if MCP is not supported in your DXP version.

#### Tomcat

- **Initialize**: run `blade server init` if the `bundles` directory does not exist.

- **Clear the seeded database (Hypersonic, before the first start)**: a downloaded bundle ships with a seeded Hypersonic database in which `test@liferay.com` already exists with the first login flags set. Boot it as is and every `/o/*` call returns 403 no matter what `portal-ext.properties` contains, because those properties are read only when the admin is created.

  Delete `bundles/data` and `bundles/osgi/state`.

  Only for a bundle that has never been started — `bundles/logs` is empty and nothing answers on `http://localhost:${PORT}`. Otherwise skip this and use the manual login in First Login Bootstrap.

- **BasicAuth verifier (dev only — required for headless REST and MCP)**: add to `configs/local/portal-ext.properties` BEFORE first boot:

  ```
  auth.verifier.BasicAuthHeaderAuthVerifier.urls.includes=/api/*,/xmlrpc/*,/o/*
  ```

  Every headless REST endpoint hits `/o/*`, and so does every MCP `call-http-endpoint` call on 2026.Q1 and 2026.Q2. Without this, those calls return 403. Adding it reactively costs an extra edit + sync + restart cycle.

  **Security note**: this is for local development only. BasicAuth sends credentials in every request. For production, use OAuth2 with `OAuth2HeaderAuthVerifier` instead. Never enable BasicAuth on `/o/*` in production.

- **Instance and admin properties (dev only)**: a new workspace ships `configs/local/portal-ext.properties` with nothing but JDBC lines that are commented out, so add every line below rather than assuming any of them is already there:

  ```
  admin.email.from.address=test@liferay.com
  admin.email.from.name=Test Test
  company.default.time.zone=UTC
  company.default.web.id=liferay.com
  default.admin.email.address.prefix=test
  passwords.default.policy.change.required=false
  setup.wizard.enabled=false
  terms.of.use.required=false
  users.reminder.queries.enabled=false
  ```

  `setup.wizard.enabled=false`, `terms.of.use.required=false`, and `passwords.default.policy.change.required=false` remove the setup wizard, the Terms of Use screen, and the forced password change, and `users.reminder.queries.enabled=false` disables the password recovery security question prompt that otherwise follows that password change. `default.admin.email.address.prefix` and `company.default.web.id` combine into the admin login — `test` plus `liferay.com` is what makes the documented `test@liferay.com` / `test` credentials work. `admin.email.from.address` and `admin.email.from.name` set the sender on portal notifications. `company.default.time.zone=UTC` keeps portal timestamps aligned with the UTC timestamps in `catalina.out`, which otherwise disagree with the local shell and make log correlation misleading.

  Only some of these are read while the default company and its admin user are created: `admin.email.from.address`, `admin.email.from.name`, `company.default.time.zone`, `company.default.web.id`, `default.admin.email.address.prefix`, and `passwords.default.policy.change.required`. Those must be in place before the bundle has ever booted, because `PasswordPolicyLocalServiceImpl.checkDefaultPasswordPolicy` builds the default policy once and a later edit cannot rename an existing admin or clear a `passwordReset` flag already written to the database. `setup.wizard.enabled`, `terms.of.use.required`, and `users.reminder.queries.enabled` are read on each boot or login instead — `UserImpl` resolves the last two through `PrefsPropsUtil` every time — so adding them later still takes effect after a restart.

- **Configuration sync — before the first start**: copy the local config into the bundle: `cp configs/local/portal-ext.properties bundles/portal-ext.properties`. (This copy is destructive — see `skills/deploy-and-verify/SKILL.md` for the diff before sync rule.)

  The properties above are what skip the manual first login, but they only take effect if this copy happens before the bundle has ever booted. See First Login Bootstrap below.

- **Free port 8080 first**: every Liferay workspace defaults to 8080, so another workspace left running holds it. Run `ss -ltnp | grep ':8080 '` and **wait for the result before launching** — do not batch the check with the start command. If the port is taken, **ask the user** whether to stop that instance (with its own `bundles/tomcat*/bin/shutdown.sh`) or move this workspace to another port — it is a process this session did not start, so the restart permission in `liferay-rules.md` → "Server Restarts" does not cover it. A bind conflict is easy to misread: Tomcat still logs `Server startup in [N] milliseconds` even though the connector never came up, so the boot looks fine while every request is served by the *other* instance and its separate database — which surfaces as inexplicable login or data failures. Treat `Address already in use` in `catalina.out` as a failed boot regardless of the startup line, and confirm the listening pid belongs to this bundle.

- **Start server**: `blade server run` (foreground, recommended for debugging) or `blade server start` (background). These commands are Tomcat only — do not use them for Docker.

- **Login**: use `test@liferay.com` / `test` (or credentials found in `portal-ext.properties`).

#### Docker

- **Locate compose file**: search the workspace for `docker-compose.yaml` or `docker-compose.yml` — its location varies by project.
- **Database**: verify the compose file defines a database service (MySQL). Docker has no embedded database; both the database and Liferay containers must be running.
- **Configuration**: check whether the compose file uses `image:` (prebuilt) or `build:` (custom image):
  - `image: liferay/dxp:...` (prebuilt) → configuration is in `liferay.env` (env vars). See `skills/feature-flags/SKILL.md` for the env var encoding.
  - `build: ...` → configuration is baked into the image via `configs/docker`. Rebuild the image to apply changes.
- **Initial build**: before the first `docker compose up`, build and output client extensions to the volume mounted directory: `./gradlew deploy`.
- **Start**: `docker compose up` (foreground) or `docker compose up --detach` (background). Run from the directory containing the compose file.
- **Login**: use credentials defined in `liferay.env` (default: `test@liferay.com` / `test`).

### Server Verification

- **Tomcat**: watch `bundles/tomcat*/logs/catalina.out` for `Server startup in [X] ms`. Then verify `http://localhost:${PORT}` is reachable.
- **Docker**: poll the health check endpoint until it returns `200`: `curl --fail http://localhost:${PORT}/c/portal/status`. Then verify `http://localhost:${PORT}` is reachable. (Port may differ if the compose file maps a different host port.)

### First Login Bootstrap (Mandatory Before API/MCP Calls)

On a fresh Liferay instance, the default admin `test@liferay.com` is created with `passwordReset=true` and `agreedToTermsOfUse=false` in the database. Until the portal stops enforcing both, every authenticated API call (REST, or an MCP tool call) returns 403 — including for the Omni Admin user. `terms.of.use.required=false` and `users.reminder.queries.enabled=false` lift their half of that enforcement on any boot, but `passwordReset` is written when the admin is created, so only `passwords.default.policy.change.required=false` already in effect at that point avoids it.

- **Cleared and synced before its first start**: nothing to do. The admin was created with the properties in effect, so `passwordReset` was never set.

- **Already started**: the manual login is the only way through — syncing the properties now will not clear a `passwordReset` flag already in the database.

Prompt the user to log in to `http://localhost:${PORT}` as `test@liferay.com` / `test`, accept the Terms of Use if they appear, and complete the password change. Liferay rejects a new password that matches the current one, so tell the user to choose a different password and send it back to you. Wait for their reply before making any API or MCP calls, then use the new password in place of `test` for every call that follows.

Do not automate the browser login flow — Liferay's login form structure varies across versions and automation is brittle.

### MCP Connection Check (When MCP Is Supported)

With the server running, first run the endpoint probe in `skills/mcp-server/SKILL.md` → "Audit the Current State First". A `404` means `LPD-63311` is not in effect on the portal, whatever the agent's server list shows — enable it and restart Liferay before going further. On 2026.Q3, a `404` with the flag in effect means the `MCPServerConfiguration` switch is off; enable it per `skills/mcp-server/SKILL.md`, which needs no restart. On 2026.Q1 and 2026.Q2, the probe does not check credentials; only a tool call does (see `skills/mcp-server/SKILL.md` → "Audit the Current State First"). Then run the tool call in `skills/mcp-server/SKILL.md` → "Connection Check". If it reports `Status code: 401` or `403`, or the probe returns HTTP `401` on 2026.Q3, stop and ask the user for updated credentials. If MCP tools are not visible, ensure the CLI session was restarted after configuration.

Only fall back to direct REST APIs if MCP has been configured correctly and is still returning errors. "Not yet configured" is not a valid fallback condition — configure it first.

> **Feature flags**: before starting a task, check `skills/feature-flags/SKILL.md` for any flags required by the operation.

## Guiding the User

If the user prompts for setup assistance, guide them through these steps one by one. Do not skip ahead. Explain what you are checking (e.g., "I am verifying that your Liferay server is up") and wait for processes to complete before writing code.

## Success Signal

- `gradle.properties` and `settings.gradle` present
- `bundles/tomcat*` directory present
- HTTP request to `http://localhost:${PORT}` returns 200
- User can sign in with the default credentials
- BasicAuth verifier configured (if doing local REST/MCP work)
- MCP endpoint probe returns 200 and the MCP server is connected in the agent (when MCP is supported)
- First login bootstrap complete (or skipped via preboot flag settings)

## References

- Workspace docs: `https://learn.liferay.com/w/dxp/development/tooling/liferay-workspace`
- Creating a workspace: `https://learn.liferay.com/w/dxp/development/tooling/liferay-workspace/creating-a-liferay-workspace`
- Blade CLI: `https://learn.liferay.com/w/dxp/development/tooling/blade-cli`
- Course: `https://learn.liferay.com/course/mastering-liferay-workspaces-and-tooling/w-t-introduction/w-t-introduction`
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall