Breadcrumbs

Content Picker installation

About Content Picker installation

Content Picker is distributed as source files. It is a TypeScript application that compiles to several minified JavaScript files, which any HTTP server can serve as static resources. Before installation, build it from the sources in the Content Picker repository.

Build

Prerequisites

  • Node.js 24 is the build platform.

  • Yarn 1 is the package manager. Yarn 2 is a different tool and is not compatible.

Build the application

Run the following commands in the root directory of the Content Picker repository:

Bash
yarn install
yarn run build

The results are in the web/ directory.

Mock mode

Mock mode is available through the package scripts. Use "yarn start:mock" for local development. Use "yarn build:mock" to create a mock build.

Bash
yarn start:mock
yarn build:mock

Technology stack

The frontend uses React 18, MobX 6, webpack 5, TypeScript 5, RMWC 14, styled-components 6, and Dart Sass. Node.js 24 is the build platform.

Artifacts

  • Production: web/app.min.js

  • Development: web/app.js

  • Usage example: web/index.html

    • This HTML file is not intended for production. It only demonstrates the Content Picker integration.

  • Sample configuration file: web/picker-config.json

Deployment

Via a custom server

All the web/*.js files need to be served by an HTTP server. The files with .gz suffix might be useful if the server has direct support for pre-compressed files. The remaining files (index.html and picker-config.json) are samples and are not required. They are a good starting point for the application integration, see Integration.

The recommended way to serve these files is to add them to the already existing HTTP server that serves the main application (the one that embeds the Content Picker). That way, no additional process is needed (which means no additional costs) and also no extra reverse proxy is needed.

As a standalone Docker container

If the existing HTTP server cannot be used for any reason, it is also possible to build a special Docker image with an HTTP server (such as nginx) and then run a container with it. This option is available directly in this repository, with both Dockerfile and all entrypoint scripts. For this, use the following commands:

  1. Build the application as described above (yarn install && yarn run build).

  2. Build the Docker image with the docker command: docker build -t hcms-content-picker:latest .
    Note that the image name (hcms-content-picker:latest) is just an example. In most real-world cases, the image name must contain a correct repository name.

  3. (Optional) Push the image to the repository with docker push.

The default HTTP port is 80. Expose it when you create the Docker container. The sample index.html is also available. You can change its configuration with the Docker environment variable API_URL (the apiUrl property, see below).

The configuration is created dynamically and controlled by the following environment variables:

  • PREFIX is an optional prefix for all the files served:

    • By default, it is an empty string. In this case, the paths served are /index.html, /app.min.js and /picker-config.json.

    • If you set it to a value, for example xxx, the paths are /xxx/index.html, /xxx/app.min.js and /xxx/picker-config.json.

  • API_URL is the base URL of the HCMS API. It can be relative or absolute. Any URL that the JavaScript fetch function handles is valid.

    • It must always end with the version (for example /hcms/v2.0).

    • Warning: If you use an absolute URL, the browser security settings might block the requests. CORS headers are needed to prevent that.

  • MIDDLEWARE_URL is an optional URL (relative or absolute) of the HCMS Client for compatible configuration, that is, for theming.

  • LANGUAGE is the optional default language. Supported values are en, de, fr, it, and es.

    • If it is set, picker-config.json contains this language.

    • If it is empty, no language is written to picker-config.json. Content Picker then follows the preferred languages of the browser and falls back to English.

    • The sample index.html reads this value. The setting does not affect the Marmind picker. For details, see Content Picker.

All configuration is handled by two entrypoint scripts:

This image is based on the official nginx image, which means that full documentation is available on Docker Hub and the official nginx pages.

Remember: Configure this HTTP server for HTTPS, or put it behind a TLS-terminating reverse proxy ("balancer"). This setup is out of the scope of this document.