Packaging Client Extensions

Liferay Self-Hosted Liferay SaaS Liferay PaaS

Liferay 7.4

Client extension projects are built as deployable archives called Liferay Universal File Format Archives (LUFFAs) with a .zip extension. Each LUFFA has a particular structure and defines specific component files, which are generated automatically if not provided by your project. Liferay workspace packages client extension projects when you build them. Understanding how packaging works is important for assembling client extensions or creating LUFFAs with a different process.

This is a LUFFA’s structure:

.
├── batch
│   └── **/*.batch-engine-data.json
├── *.client-extension-config.json
├── Dockerfile
├── LCP.json
├── static
│   └── **/*
├── WEB-INF
│   └── liferay-plugin-package.properties
└── [microservice resources]

`batch`

Note

The batch folder is only required by batch client extension projects.

The data entities in a batch client extension are *.batch-engine-data.json files inside a batch/ folder in the built LUFFA. These files can be in any folder structure within the batch/ folder.

You can place any number of *.batch-engine-data.json files under the root level batch/ directory, using a directory structure of unlimited depth. If you fail to define a batch extension in your project’s client-extension.yaml file, Liferay ignores these files.

`*.client-extension-config.json`

Note

At least one *.client-extension-config.json file is required in each LUFFA.

At the root of the LUFFA are one or more *.client-extension-config.json (OSGi Configuration Resource Format) files. They define how your client extensions are structured in the archive. Usually these files are produced during the build process based on your client-extension.yaml file’s contents. The conversion from YAML to JSON is specified by the Liferay workspace plugin, and is not a 1:1 mapping.

`Dockerfile`

Note

At least one Dockerfile is required in each LUFFA.

The build process automatically generates and packages a Dockerfile for batch, configuration, and frontend client extensions.

You must provide a Dockerfile in your project for microservice client extensions. Add it to the root of your project, and it’s copied into the LUFFA when you build the project.

Make sure your Dockerfile can execute the microservice client extensions in your project. For example, your Dockerfile may require installing specific tools that your microservice’s code requires.

You can also configure the Docker container in other ways, such as with environment variables. For example, you can configure the container’s JVM (which may be necessary for client extensions running in a cloud environment) with the LIFERAY_JAR_RUNNER_JAVA_OPTS variable.

Packaging a Client Extension Manually

If packaging the LUFFA yourself, batch, configuration, and frontend client extensions requires certain Dockerfile conventions. Liferay provides them for you in the images below.

For batch client extensions, use the liferay/batch:latest image:

FROM liferay/batch:latest
COPY /batch /batch

For configuration client extensions, use the liferay/noop:latest image:

FROM liferay/noop:latest

For frontend client extensions, use the liferay/caddy:latest image:

FROM liferay/caddy:latest
COPY static/ /public_html/

A microservice client extension’s Dockerfile depends entirely on your specific context, so a pre-configured image cannot be provided.

`LCP.json`

note

An LCP.json file is required in each LUFFA.

The build process automatically generates and packages an LCP.json file for batch, configuration, and frontend.

You must provide an LCP.json file in your project for microservice client extensions. Add it to the root of your project, and it’s copied into the LUFFA when your project is built. This LCP.json file configures the container used for the microservice when it’s deployed in Liferay Cloud.

If packaging the LUFFA yourself, each client extension comes with different specification suggestions for its LCP.json:

Client Extension	Requires Significant Resources	Kind	Notes
Batch	✘	Job	The environment variable `LIFERAY_BATCH_OAUTH_APP_ERC` must be set to the value of your batch client extension’s `oAuthApplicationHeadlessServer` property. This can be provided through interpolation. You can specify small values for `cpu`, `memory` and `scale`.
Configuration	✘	Job	Even less memory intensive than batch extensions. You can specify very small values for `cpu`, `memory` and `scale`.
Frontend	✘	Deployment	Must specify the `loadBalancer` property with `targetPort` set to `80`. Should specify `livenessProbe` and `readinessProbe` properties for self-healing. You can specify small values for `cpu`, `memory` and `scale`.

Example Batch Client Extension LCP.json

{
   "cpu": 0.2,
   "env": {
       "LIFERAY_BATCH_OAUTH_APP_ERC": "__batch.oAuthApplicationHeadlessServer__"
   },
   "id": "__CLIENT_EXTENSION_ID__",
   "kind": "Job",
   "memory": 50,
   "scale": 1
}

Example Configuration Client Extension LCP.json

{
    "cpu": 0.1,
    "id": "__CLIENT_EXTENSION_ID__",
    "kind": "Job",
    "memory": 10,
    "scale": 1
}

Example Frontend Client Extension LCP.json

{
    "cpu": 0.2,
    "id": "__CLIENT_EXTENSION_ID__",
    "kind": "Deployment",
    "livenessProbe": {
        "httpGet": {
            "path": "/",
            "port": 80
        }
    },
    "loadBalancer": {
        "cdn": true,
        "targetPort": 80
    },
    "memory": 50,
    "readinessProbe": {
        "httpGet": {
            "path": "/",
            "port": 80
        }
    },
    "scale": 1
}

See Configuration via LCP.json for more information.

`static`

Note

The static directory is only required by frontend client extension projects.

You can place any number of static resource files into the root level static/ directory in the built LUFFA. Use any folder structure you like within the static/ folder. These files are ignored if there is no frontend client extension defined in your project’s client-extension.yaml file.

Microservice Resources

You can include additional resources in the built LUFFA for your microservice client extension projects, as long as they do not conflict with other required files.

Capability: