HCMS CLI managing configurations

An HCMS configuration is stored in the following assets on the Censhare Server:

HeadlessCMS.xml
DataStore.xml
WebServer.xml
satellite asset(s)
certificate asset(s)
optionally, Statistics.xml

The CLI tool can create them or make changes in them. However, not every setting/entry in the configuration file can be managed from the CLI. Any parameters/settings not listed in the sections below need to be updated directly in those files. It means that you will need to access the Censhare Server using the Java Client or Censhare Web.

Note Also keep in mind different naming of configuration parameters as CLI options and in their XML counterparts.

View commands

The view commands display

Command	Argument	Meaning
`hcms configuration list`	-	Displays all available configurations as a YAML output
`hcms configuration inspect`	configuration id	Displays information about the specified configuration as a YAML output
`hcms configuration status`	configuration id	List all groups in the given configuration and for each group, list all satellites currently connected. This command is basically the same as `group status` command, but for all groups in a single configuration.

Sample YAML output for list and inspect commands:

CODE

key: news-live
name: News feed live
write_channel: root.hcms.pwa.live.
read_channels:
  - root.hcms.pwa.live.
domain: root.
domain2: root.
no_new_masterdata: true
update_new_version: false
forwarded: false
storage:
    type: s3push
    defaults:
        bucket: asdfghjkl
        region: eu-central-1
        access_key: asdffhh
        secret_key: qwertyyre
    satellite_buckets: []
    server_buckets:
      - bucket: asdfghjkl
        region: eu-central-1
        access_key: asdffhh
        secret_key: qwertyyre
authorization_providers:
  - type: basic
    users:
      - name: admin
        password: F/~,+|GP}h
        roles:
          - '*'
groups:
  - id: news-live:default1
    name: news-live:default1
    certificate:
        subject: CN=news-live:default1
        valid:
            from: 2019-05-02T09:59:22Z
            until: 2119-05-02T09:59:22Z
        algorithm: SHA256WITHRSA
        issuer: CN=news-live:default1
        serial: 016a77fbf5df
        signature: 7d9660da404786ab6b286ea281bb4f33054414ca37e27bec2d79bfedf2d60bdd29ee75ba9c0c1891e83abf51d8b303eb439e738f25de2de1e706972cd0a6f2ecef4b2e620942390a929580514f1ae30cd82ed7995f70078943aba551fd175f82835506f1bdcb77bb0fda10d8fc13fd5913ddd8a322fc9e118ac1da59b45147677980cbf98562fc8f76b4b46bd5b5e6d688ed45a575cf544d494bd48eb40bcd0af9c6ca77877bd5294c3aaf0b2df632472e916a61a60fdd078c6fe7c1b042887194d26e81d69c0515f28069751f8e13597589966f8750a324588adb95e7216dab946e3b5bde45564828e611267dd2d6095f582c6ebea833da1a59e36966e72ecb
        pem: |
            -----BEGIN CERTIFICATE-----
            MIICujCCAaKgAwIBAgIGAWp3+/XfMA0GCSqGSIb3DQEBCwUAMB0xGzAZBgNVBAMT
            Em5ld3MtbGl2ZTpkZWZhdWx0MTAgFw0xOTA1MDIwOTU5MjJaGA8yMTE5MDUwMjA5
            NTkyMlowHTEbMBkGA1UEAxMSbmV3cy1saXZlOmRlZmF1bHQxMIIBIjANBgkqhkiG
            9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwklsXU5Ewt78dSPbs94ASQB4e5FTeMitHWxd
            i+xkDIY/OF84bFF5bzmi3SIHhVF71Q6IiPJe8RUlo/jz8EdsTtSp7/UKEqfkmE7e
            gn7YBdRNbU9shkJV+iy8YtobuAwH6lVwVTYolVPcUNCrJt9+eCSzOOwbV2CTrGJv
            ASdAE1+KWf2s/YWBgO4MyF2isdqBDlKwm4cXnckmfy7HhuEV6ucNxvQWmTHfDpfr
            a7qxYI0u5WXl+JqyZ7PmYtVRkC8Jgxv9W4hNKoLSephu8PlW7sT2VoNVlGjTXdjg
            GO0MoiQ94Wu7RppYAMZUVhFLwLnA5boWoJVv+jims6WtOw2F2wIDAQABMA0GCSqG
            SIb3DQEBCwUAA4IBAQB9lmDaQEeGq2sobqKBu08zBUQUyjfie+wteb/t8tYL3Snu
            dbqcDBiR6Dq/UdizA+tDnnOPJd4t4ecGlyzQpvLs70suYglCOQqSlYBRTxrjDNgu
            15lfcAeJQ6ulUf0XX4KDVQbxvct3uw/aENj8E/1ZE93YoyL8nhGKwdpZtFFHZ3mA
            y/mFYvyPdrS0a9W15taI7UWldc9UTUlL1I60C80K+cbKd4d71SlMOq8LLfYyRy6R
            amGmD90HjG/nwbBCiHGU0m6B1pwFFfKAaXUfjhNZdYmWb4dQoyRYituV5yFtq5Ru
            O1veRVZIKOYRJn3S1glfWCxuvqgz2hpZ42lm5y7L
            -----END CERTIFICATE-----

Sample YAML output for the status command:

CODE

connected_satellites:
    docker3:default1:
      - docker3:default1-7ede1c65921c
      - docker3:default1-ac6468dccf86
    docker3:default2: []
    test3: []

CRUD commands

As mentioned above, the CLI is limited to managing the most essential configuration parameters. For the full list of available configuration parameters and their meanings, please consult the corresponsing documentation listed above as well as in this article.

Create and update

Command	Argument	Meaning
`hcms configuration create`	configuration id	Creates a new HCMS configuration and outputs it as YAML
`hcms configuration update`	configuration id	Updates a specified HCMS configuration in the Censhare system

Upon creating or updating the configuration, some of the options can be supplied to one of the hcms configuration commands or to one of the other commands, including hcms authorization , shared-filesystem, or hcms group.

hcms configuration create will populate a generic configuration with a minimum input, including a satellite group and a basic HTTP authorization for you to manage it later.

Therefore, for your HCMS installation, you can decide between two scenarios:

create a default configuration quickly and fine-tune it later
create a very custom configuration straight away

For HCMS beginners, the first scenario may be more suitable. If you are already an experienced HCMS admin or developer, you can try the second scenario.

Configuration of the configuration

Using the following options, you can specify how the configuration itself is handled.

Option short	Option long	Default option value	Meaning
`-n`	`--name`	-	Configuration name as appears in any UIs
-	`--mgmt-domain`	`root.`	Domain where configuration assets will be stored
-	`--mgmt-domain2`	`root.`	Domain where configuration assets will be stored
-	`--schema-resource-key`	Constructed from the write channel	Specifies resource key of the asset that contains all schemas

Essential HCMS configuration

This configuration is part of the business logic implementation. It defines how HCMS and Censhare work together in terms of asset handling.

Option short	Option long	Default option value	Meaning
`-wc`	`--write-channel`	`root.hcms`	Specifies the output channel value that is automatically assigned to entities created or modified by HCMS, unless explicitly overwritten in the schema.
`-rc`	`--read-channels`	`root.hcms`	A comma-separated list of output channel values. It is allowed to append `.*` to output channel values to indicate that the value and all child values are allowed. No empty characters between values.
`-d`	`--domain`	`root.`	Specifies the `domain` attribute that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema.
`-d2`	`--domain2`	`root.`	Specifies the `domain2` attribute that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema.
`-nnm`	`--no-new-masterdata`	`true`	Enables or prevents automatic creation of master data definitions by schemas.
`-unv`	`--update-new-version`	`false`	Enables or prevents automatic creation of asset versions.

Example of a read channels list: --read-channels root.site1.*,root.site2.ugc

REST API configuration

This configuration defines the behaviour of the REST endpoints.

Option short	Option long	Default option value	Meaning
`-pp`	`--url-path-prefix`	-	Prefix of the HCMS endpoint URL path. Should start with a slash. See more rules below.
-	`--forwarded`	`false`	Enable/disables use of `X-Forwarded-`* and `Forwarded` HTTP headers, i.e., makes those headers trusted.
-	`--forwarded-levels`	-	Limits the maximum depth of HTTP proxies accepted in forwarded requests (`X-Forwarded-`* HTTP headers). If no value is specified, there is no limit - any number of nested values is accepted. Used only when `forwarded` is `true`.
`-H`	`--add--header`	-	Adds a constant value for single header, directly in the HTTP server configuration. Input format is `header_name:value`. Any spaces in the value itself must be escaped, or the whole argument must be put inside quotes.
-	`--remove-header`	-	Removes one header at a time from the list of constant headers.

When providing a prefix for the HCMS endpoint URL path, please keep in mind the following. By default, HCMS is available directly at /hcms/v1.0. When you specify a prefix, it will be prepended. So, with a /test1 prefix, the base URL will be /test1/hcms/v1.0.

For more information on X-Forwarded-* HTTP headers, please refer to the external documentation.

Storage configuration

You can use either a local storage or a shared filesystem hosted on AWS.

The local mode is the default one. In this case, binary data associated with the asset is copied to the satellites. You do not need to set the mode to local upon initial installation, but you need to do so if you want to move back from AWS to local mode, e.g., from AWS to your own datacenter.

In case of using AWS, binary data associated with the asset are stored in the specified S3 bucket by the application server and are shared by the satellites. Please refer to this article to understand advantages and use cases as well as prerequisites for using S3 storage.

When storage is set to local, there is no need for any further configuration. For AWS, you will need to supply some options.

Option short	Option long	Default option value	Meaning
`-s`	`--storage`	`local`	Specifies how binary data is managed by the satellites. One of the two values is accepted: `local` and `s3push`
`-s3bucket`	-	-	ID of the AWS bucket
`-s3region`	-	`eu-central-1`	AWS region
`-s3accessKey`	-	-	An access key with permissions to use (read, write) the bucket; optional if both the satellite and the Censhare Server are on the same EC2 infrastructure with permissions provided via AWS roles.
`-s3secretKey`	-	-	A secret key (password) with permissions to use (read, write) the bucket. Required if and only if the `-s3accessKey` has been specified.

Dynamic image cache configuration

Note By setting any of the actual options, you will automatically enable the dynamic image cache.

See also this article for detailed explantion and further availble parameters.

Option short	Option long	Default option value	Meaning
-	`--image-cache-disable`	-	Disables the dynamic image cache. Mutually exclusive with all other `--image-cache-*` options.
-	`--image-cache-max-size`	-	Specifies the maximum size of the (entire) dynamic image cache, in megabytes.
-	`--image-cache-max-age`	-	Specifies the expiration time of the dynamic image cache records, in minutes.
-	`--image-cache-storage-item`	`master`	Specifies the storage item used as a source for all image variants. Such storage item needs to be configured before, read this article for instructions.
-	`--image-cache-autodetect`	`true`	Specifies if the images are generated in the same format as the source image; only works for `png` or `jpeg` source images.
-	`--image-cache-default-format`	`png`	Specifies the format for the images generated from source images that are neither `png` or `jpg` or when no auto detection is enabled. Can also be only `png` or `jpeg`.

If you want to use the local storage for dynamic image cache, no further configuration is required. For the AWS configuration, you will need to specify the options below. The keys are optional, but they must be always specified in pair (either both of them, or neither of them).

Note It is not recommended to use the same S3 bucket for both generl storage and dynamic image cache. Such setup can lead to losing some images.

Option short	Option long	Default option value	Meaning
-	`--image-cache-s3bucket`	-	AWS S3 bucket used to store the dynamic image cache content. Only the bucket name, the entire URL is not meant here.
-	`--image-cache-s3region`	`eu-central-1`	AWS S3 region used to store the dynamic image cache content.
-	`--image-cache-s3accessKey`	-	An access key with permissions to use (read, write) the bucket.
-	`--image-cache-s3secretKey`	-	A secret key (password) with permissions to use (read, write) the bucket. Required if and only if the `-s3accessKey` has been specified.

Although HCMS in general supports other S3-compatible solutions, for now, the CLI tool allows to only manage the actul S3 buckets. For using any other hosting, you will need to add a custom base URL for that provider in the HeadlessCMS.xml, in the url-override attribute.

User tracking for HCMS Client

The HCMS CLI allows to enable or disable user tracking for the HCMS Client.

Option short	Option long	Default option value	Meaning
-	`--user-tracking`	-	Enables or disables user tracking for HCMS Client framework. Can be `true` or `false`.

Note If you use the HCMS Client, you must activate user tracking.

Delete

Command	Argument	Meaning
`hcms configuration delete`	configuration id	Deletes a specified configuration

Option short	Option long	Default option value	Meaning
`-G`	-	-	When specified, keeps all satellite groups of the deleted configuration. They can be then moved to another configuration as explained here

Change configuration id

Command	1st Argument	2nd Argument	Meaning
`hcms configuration change-id`	Current configuration id	New configuration id	Changes the id of the specified configuration