liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/workspace-init
workspace-init
VerifiedBootstrap 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.
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
bundlesdirectory, or missinggradle.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.productingradle.properties. - Verify tooling: check that
blade(blade --version) and Java (javac -version) are installed. If missing, provide installation steps. - DXP License: if
liferay.workspace.productcontainsdxp, a license file is required. Liferay identifies license files by XML content, not filename — checkbundles/deployfor any.xmlfile whose root element is<license>or<licenses>. If none is found, stop and ask the user to place their license file inbundles/deploybefore 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/deploydirectory 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, clearingbundles/dataalso discards it; copy a key again intobundles/deployas part of any such reset. - Keep an environment directory in Git: the workspace plugin refuses to configure unless the
configsdirectory holds at least one directory besidescommonanddocker, and Git does not keep an empty directory. A workspace whoseconfigs/localis empty therefore works where it was made, but a fresh clone fails on every Gradle call,blade gw deployincluded, withThe 'configs' directory must contain one directory not named: common, docker(verified on a 2026.Q3.5 workspace). Commit a file in it: aportal-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:
-
Load
skills/mcp-server/SKILL.mdand 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'sLPD-63311flag, which a fresh bundle never has. -
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.
-
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.
-
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 initif thebundlesdirectory 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.comalready exists with the first login flags set. Boot it as is and every/o/*call returns 403 no matter whatportal-ext.propertiescontains, because those properties are read only when the admin is created.Delete
bundles/dataandbundles/osgi/state.Only for a bundle that has never been started —
bundles/logsis empty and nothing answers onhttp://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.propertiesBEFORE first boot:auth.verifier.BasicAuthHeaderAuthVerifier.urls.includes=/api/*,/xmlrpc/*,/o/*Every headless REST endpoint hits
/o/*, and so does every MCPcall-http-endpointcall 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
OAuth2HeaderAuthVerifierinstead. Never enable BasicAuth on/o/*in production. -
Instance and admin properties (dev only): a new workspace ships
configs/local/portal-ext.propertieswith 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=falsesetup.wizard.enabled=false,terms.of.use.required=false, andpasswords.default.policy.change.required=falseremove the setup wizard, the Terms of Use screen, and the forced password change, andusers.reminder.queries.enabled=falsedisables the password recovery security question prompt that otherwise follows that password change.default.admin.email.address.prefixandcompany.default.web.idcombine into the admin login —testplusliferay.comis what makes the documentedtest@liferay.com/testcredentials work.admin.email.from.addressandadmin.email.from.nameset the sender on portal notifications.company.default.time.zone=UTCkeeps portal timestamps aligned with the UTC timestamps incatalina.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, andpasswords.default.policy.change.required. Those must be in place before the bundle has ever booted, becausePasswordPolicyLocalServiceImpl.checkDefaultPasswordPolicybuilds the default policy once and a later edit cannot rename an existing admin or clear apasswordResetflag already written to the database.setup.wizard.enabled,terms.of.use.required, andusers.reminder.queries.enabledare read on each boot or login instead —UserImplresolves the last two throughPrefsPropsUtilevery 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 — seeskills/deploy-and-verify/SKILL.mdfor 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 ownbundles/tomcat*/bin/shutdown.sh) or move this workspace to another port — it is a process this session did not start, so the restart permission inliferay-rules.md→ "Server Restarts" does not cover it. A bind conflict is easy to misread: Tomcat still logsServer startup in [N] millisecondseven 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. TreatAddress already in useincatalina.outas 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) orblade server start(background). These commands are Tomcat only — do not use them for Docker. -
Login: use
test@liferay.com/test(or credentials found inportal-ext.properties).
Docker
- Locate compose file: search the workspace for
docker-compose.yamlordocker-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) orbuild:(custom image):image: liferay/dxp:...(prebuilt) → configuration is inliferay.env(env vars). Seeskills/feature-flags/SKILL.mdfor the env var encoding.build: ...→ configuration is baked into the image viaconfigs/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) ordocker 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.outforServer startup in [X] ms. Then verifyhttp://localhost:${PORT}is reachable. - Docker: poll the health check endpoint until it returns
200:curl --fail http://localhost:${PORT}/c/portal/status. Then verifyhttp://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
passwordResetwas never set. -
Already started: the manual login is the only way through — syncing the properties now will not clear a
passwordResetflag 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.mdfor 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.propertiesandsettings.gradlepresentbundles/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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |