Content Picker installation
[]
The Content Picker itself is distributed in the form of sources files. It's a Typescript application and compiles to several (minified) JavaScript files, which are then served as static resources by any HTTP server. This means that before installation, it needs to be built first from the sources in this repository.
Build
Prerequisites
- nodejs version 14 or higher (both 14 and 16 are tested)
- yarn 1 (note that yarn 2 is a very different, incompatible tool)
Hint: the official docker image node:14 contains both the correct version of nodejs and the correct yarn tool
Build itself
Run in the root directory of this repository:
yarn install
yarn run build
The results are in the web/ directory.
Artifacts
- production: web/app.min.js
- development: web/app.js
- usage example: web/index.html
- This HTML file is not intended to be used in production, it's just a demonstration of the Asset 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 basically just samples and are not technically needed. They are, however, a good starting point for the application integration (see below).
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:
- Build the application as described above (yarn install && yarn run build)
- Build the Docker image via docker command: docker build -t hcms-content-picker:latest .
- Please 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.
- Please 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.
- (Optional) Push the image to the repository via docker push
Default HTTP port is 80, and it needs to be exposed when creating the Docker container. The sample index.html is also available and its configuration can be changed via a Docker environment variable API_URL (the apiUrl property, see below).
The configuration is actually created dynamically and controlled by the following environmental variables.
- PREFIX is an optional prefix for all the files served
- By default, it's an empty string; in this case, the paths served are /index.html, /app.min.js and /picker-config.json
- When changed to a value xxx (for example), the paths will be /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 either relative or absolute - anything handled by the JavaScript fetch function.
- It must always end with the version (for example /hcms/v2.0)
- Warning! When using the absolute URL, the requests might be actually blocked by the browser security settings. CORS headers are needed to prevent that.
- MIDDLEWARE_URL is an optional URL (relative or absolute) of the HCMS Client for compatible configuration, i.e., for theming.
- TODO: Theming should be documented
All configuration is handled by two entrypoint scripts:
- 30-prefix.sh moves static files to a directory served by nginx
- 40-picker-config-json.sh creates the picker-config.json
This image is based on the official nginx image, which means that full documentation is available at the Docker hub and official nginx pages.
Remember As mentioned above, this HTTP server needs to be either configured for HTTPS, or it needs to be put behind SSL-terminating reverse proxy ("balancer"). This is out of scope of this document.