Configuration

ldev resolves configuration from these sources, highest priority first:

1. shell environment variables
2. .liferay-cli.local.yml
3. docker/.env as a legacy fallback for runtime and some connection values
4. .liferay-cli.yml

Main files

docker/.env

Local runtime values such as:

• LIFERAY_HTTP_PORT
• COMPOSE_PROJECT_NAME
• ENV_DATA_ROOT
• POSTGRES_DATA_MODE
• LIFERAY_DATA_MODE
• LIFERAY_OSGI_STATE_MODE
• LCP_PROJECT
• LCP_ENVIRONMENT
• GLOWROOT_PORT — port for the Glowroot APM UI (default 4000; worktrees get a unique port automatically)

Glowroot

The default docker-compose.yml ships with Glowroot enabled out of the box via LIFERAY_JVM_OPTS. Once the container is running, the APM UI is available at:

http://127.0.0.1:4000

For worktrees, the port is assigned automatically from GLOWROOT_PORT in each worktree's docker/.env. Use it to inspect heap usage, slow transactions, and GC activity without any extra setup.

ldev may also read LIFERAY_CLI_URL and OAuth variables from here as a legacy fallback, but this is not the preferred destination for ldev oauth install --write-env.

.liferay-cli.yml

Version-controlled project defaults such as resource paths and shared non-secret defaults.

Keep secrets out of this file.

.liferay-cli.local.yml

Local credentials and local-only overrides written by:

ldev oauth install --write-env

Do not commit it.

This is the preferred file for local OAuth credentials.

Useful environment variables

export LDEV_ACTIVATION_KEY_FILE=/path/to/activation-key.xml
export REPO_ROOT=/path/to/project

Remote execution with connection overrides

When you run ldev from automation hosts, CI jobs, or jumpboxes, you can override Liferay connection values per command instead of changing project files.

These are namespace options on ldev portal and ldev resource, not root options:

• --liferay-url <url>
• --liferay-client-id <clientId>
• --liferay-client-secret <clientSecret>
• --liferay-client-secret-env <envVar>
• --liferay-scope-aliases <aliases>
• --liferay-timeout-seconds <seconds>

Place them on the namespace before the concrete subcommand.

ldev portal --liferay-url https://portal.example.com check --json
ldev portal --liferay-url https://portal.example.com inventory sites --json

For secrets, prefer environment-variable indirection:

export LIFERAY_REMOTE_SECRET='***'
ldev portal \
	--liferay-url https://portal.example.com \
	--liferay-client-id remote-client \
	--liferay-client-secret-env LIFERAY_REMOTE_SECRET \
	inventory page --url /home --json

If both --liferay-client-secret and --liferay-client-secret-env are provided, --liferay-client-secret wins.

If your environment cannot run ldev oauth install --write-env, see the manual app setup guide in OAuth.

Runtime Storage Modes

ldev supports three persistence modes for selected runtime directories:

• auto: use the platform default
• bind: always use bind mounts under ENV_DATA_ROOT
• volume: always use Docker volumes

Supported storages:

• POSTGRES_DATA_MODE
• LIFERAY_DATA_MODE
• LIFERAY_OSGI_STATE_MODE
• ELASTICSEARCH_DATA_MODE

Default behavior:

• Windows: auto resolves to Docker volumes for PostgreSQL, Liferay runtime state, and Elasticsearch data
• Linux/macOS: auto resolves to bind mounts for these storages

This means Linux/macOS keep the classic filesystem-based workflow by default, but you can opt into Docker volumes explicitly if you prefer that tradeoff.

Example:

POSTGRES_DATA_MODE=volume
LIFERAY_DATA_MODE=volume
LIFERAY_OSGI_STATE_MODE=volume
ELASTICSEARCH_DATA_MODE=volume

Use bind when you want direct host visibility under ENV_DATA_ROOT. Use volume when you want Docker-managed persistence and, on some hosts, faster I/O.

liferay-deploy-cache is always kept as a bind mount under ENV_DATA_ROOT/liferay-deploy-cache. It is a host/container exchange area for auto-deploy artifacts, so ldev does not support Docker volumes there.

Platform Guide

Recommended starting point:

• Windows: keep auto for PostgreSQL, Liferay runtime state, deploy cache, and Elasticsearch data
• Linux/macOS: keep auto if you prefer the classic bind-mount workflow under ENV_DATA_ROOT
• Linux/macOS: switch selected storages to volume if you want Docker-managed persistence or better I/O on your host

Typical setups:

# Default cross-platform setup
POSTGRES_DATA_MODE=auto
LIFERAY_DATA_MODE=auto
LIFERAY_OSGI_STATE_MODE=auto
ELASTICSEARCH_DATA_MODE=auto

# Opt into Docker volumes everywhere
POSTGRES_DATA_MODE=volume
LIFERAY_DATA_MODE=volume
LIFERAY_OSGI_STATE_MODE=volume
ELASTICSEARCH_DATA_MODE=volume

# Force the classic host-visible layout everywhere
POSTGRES_DATA_MODE=bind
LIFERAY_DATA_MODE=bind
LIFERAY_OSGI_STATE_MODE=bind
ELASTICSEARCH_DATA_MODE=bind

For existing projects, make sure the corresponding Compose overrides are present in docker/ when you use volume or auto on Windows:

• docker-compose.postgres.volume.yml
• docker-compose.liferay.volume.yml
• docker-compose.elasticsearch.volume.yml

Secret handling

Keep OAuth credentials and other secrets in .liferay-cli.local.yml or your shell environment. Do not store them in committed project config.

See OAuth for the user-facing OAuth model.