Configuration

Once the Swift publication module is installed, you must ensure its configuration is aligned with your business needs and production environment.

Ensure that your public receivers are configured for both Swift (Pages app) and DX Core publishing.
Configure REST communication between author and public instances.
Decide on an external version store, such as S3, and configure it.

REST-based publication

To communicated between author and public instances securely the swift.publication.rest.authentication.signature.enabled property key is set to true by default. It is for secure request handling by sending signatures from the author instance, verified by public instances using a public key.

If set to false, the signature mechanism is disabled, and only requests from localhost are permitted. This property must have consistent values across both the author and public instances.

When authentication is enabled, the public key must be deployed to public instances under /server/activation/publicKey. Swift publication doesn’t automatically propagate the key on the initial publication. You must add it manually if it’s missing.

Example configuration for JVM arguments such as AWS retryMode

-Daws.retryMode=standard (1)

1	This changes the default AWS legacy mode to the `standard` retry strategy. See the Specify a strategy section of the AWS SDK for Java documentation for more details.

MicroProfile Config

First, make sure you have receivers configured in the MicroProfile Config. If you’re using local development, you must add a default receiver. Then, add the Swift publication configuration section to your MicroProfile Config, as shown in the examples below.

MicroProfile Config REST

info:
  magnolia:
    develop: true
    superuser:
      enabled: true
      password: superuser!
    publishing:
      core:
        receiver: &receivers (1)
          - name: magnoliaPublic-0 (2)
            url: http://dev-magnolia-helm-public-0-svc:8080
            enabled: true
          - name: magnoliaPublic-1
            url: http://dev-magnolia-helm-public-1-svc:8080
            enabled: true
swift: (3)
  publication:
    receivers: *receivers

1	Configure your receivers.
2	Similar to other modules, defining your public instances for the workflow is mandatory. You can change the public instance name for the hostname in development environments.
3	Add the Swift publication configuration section.

Swift publication currently manages publication for Pages only. Assets and other content types continue to use the standard DX Core publication mechanism by default. See Configuring the Assets app for more details.

As a result, when configuring public instances you must define both sets of receiver properties:

magnolia.publishing.receivers.* — DX Core publishing (used by Assets when Swift is installed, or by all content if Swift is not used).
swift.publication.receivers.* — Swift publication (applies to Pages only by default).

Define both for every public instance you configure so that Pages publish via Swift and other content types publish via DX Core publishing.

Example: DX Core publishing receivers

magnolia.publishing.receivers[0].name=public1
magnolia.publishing.receivers[0].url=<SERVER_URL>/magnoliaPublic
magnolia.publishing.receivers[0].enabled=true
magnolia.publishing.receivers[1].name=public2
magnolia.publishing.receivers[1].url=<SERVER_URL>/magnoliaPublic
magnolia.publishing.receivers[1].enabled=true

Properties

swift.publication.rest
Property	Description
`swift.publication.rest.retry.attempts`	optional, default is `3` Configures the number of REST retries upon publication request failures.
`swift.publication.rest.executor.retry.poolSize`	optional, default is `3` The size of the scheduled thread pool used for REST retries.
`swift.publication.rest.retry.interval`	optional, default is `2` The interval between REST retry attempts in milliseconds.
`swift.publication.rest.retry.statusCodes`	optional, default is `408,429,500,502,503,504` REST retries are attempted for the status codes defined in this property. Default codes are set according to Google retry strategy. The list includes the following HTTP status codes: 408 Request Timeout 429 Too Many Requests 500 Internal Server Error 502 Bad Gateway 503 Service Unavailable 504 Gateway Timeout
`swift.publication.rest.sync.poll.interval`	optional, default is `3000` This property defines the time between retry synchronisation polling in milliseconds.
`swift.publication.rest.sync.status.timeout`	optional, default is `3600` Timeout for status synchronizations between author and public instances in seconds.
`swift.publication.save.bulk.size`	optional, default is `50` Defines the number of items processed in bulk in publishing and unpublishing operations. This has several performance advantages: Preventing JVM memory and CPU overload Reduced risk of timeouts and partial failures Minized database locking and contention by keeping transactions shorter

Versioning store

Instead of storing content versions within Magnolia’s internal JCR repository, Swift publication stores versions in an external version store. You must define which workspaces Swift publication works on and configure providers such as Amazon S3.

Properties

Property Description

swift.versioning.workspaces

required

Defines which workspaces Swift publication works on.

Example configuration for the website workspace

swift.versioning.workspaces[0].name=website

Controls which workspaces store versions in the external version store. It does not change which publication option is used.

Including dam means asset versions are stored externally, only if the Assets app is configured for Swift publication.

swift.publication.version.bulk.size

optional, default is 50

Defines how many versions are processed in a single batch on the public instance before changes are persisted.

If the number of versions is less than or equal to this value, all versions appear at the same time on public instances.
If it’s higher, publishing isn’t atomic, and visitors may observe intermediate states while publication is ongoing.

Higher values reduce the chance of exposing unfinished publications but increase memory usage on public instances.

Amazon S3

You must extend your MicroProfile Config further. Depending on the external store you have set up, copy and adapt the following versioning section into your MicroProfile Config.

Cloud-storage-config Amazon S3

swift:
  publication:
    …
  versioning:
    s3:
      bucket: <YOUR_S3_BUCKET> (1)
      region: <AWS_REGION> (2)
      endpoint: <YOUR_ENDPOINT> (3)

Specify your S3 bucket name.

Specify the AWS Region you’re using.

If you want to reuse the same bucket across different environments, like test or production, you can save your publications in a different space per environment. You can do this by modifying the root folder as a base folder for publication storage.

AWS S3 bucket names are globally unique, meaning no two buckets can have the same name. If you try to create a bucket and receive an error stating the bucket already exists, it means that the bucket name is already in use, either by you or someone else.

Properties

Property Description

bucket

required

The name of your unique S3 bucket associated with your AWS connection.

region

required

The AWS region where your unique bucket is located. For example, Asia Pacific (Sydney). See AWS Local Zones locations for more details.

endpoint

optional

The URL used to send your API requests. See AWS service endpoints for more details on AWS web service entry points.

While this property is optional, it must be configured for local development environments. This involves updating the endpoint to point to your local service.

rootFolder

optional

This path points to the folder you want to use within your bucket.

pathstyle

optional

This boolean defines whether a path-style URL or a custom-style endpoint is used.

When set to true, path-style requests must be used.

Path-style requests will be deprecated; see Amazon S3 Path Deprecation Plan – The Rest of the Story for more details.

When set to false, the access style is determined by your endpoint configuration. For example, the bucket name is included in the domain in virtual-hosted–style requests.

connection-acquire-timeout

optional, default is 10

Timeout in seconds for acquiring an S3 connection from the pool. See AWS SDK for Java API Reference for more details.

max-connections

optional, default is 50

Maximum number of S3 connections in the pool. See AWS SDK for Java API Reference for more details.

max-connection-acquires

optional, default is 10000

Maximum number of pending requests when the pool is empty. Additional requests are queued pending a free connection in the pool if all connections are in use. See AWS SDK for Java API Reference for more details.

rate-limit-period

optional, default is 100

Time period in milliseconds during which only a certain amount of calls, defined by the rate-limit, are permitted.

rate-limit

optional, default is 5

Limit for the maximum number of calls permitted during a given time (the rate-limit-period).

rate-limit-timeout

optional, default is 60000

Duration in milliseconds, after which a call times out if the current rate limit doesn’t allow its execution.

in-memory-threshold-kb

optional, default is 1000

Controls whether content read from the version store is kept in memory or written to a temporary file until it’s processed. Content is kept in memory up to the configured value (in KB) and written to disk if its size exceeds that limit.

access-key-id

optional

Specifies your AWS access key ID, similar to the aws.accessKeyId system property. If cred-encrypted is true, this property’s value must be the ID of an encrypted password in the Passwords app.

secret-access-key

optional

Specifies your AWS secret access key, similar to the aws.secretAccessKey system property. If cred-encrypted is true, this property’s value must be the ID of an encrypted password in the Passwords app.

cred-encrypted

optional, default is false

If set to true, the access-key-id and secret-access-key properties are treated as IDs of encrypted passwords in the Passwords app for decryption and authentication.

All AWS access key properties, including these, and AWS connection configurations are optional, and Magnolia falls back to existing authentication methods if you don’t supply any credentials.

AWS connection

The magnolia-aws-foundation module handles all Amazon connections from Magnolia. It’s installed automatically by Maven when you install any AWS-dependent module.

To use AWS in Magnolia, you must have a working AWS account.

You need AWS credentials to connect AWS to Magnolia. Credentials consist of:

AWS access key ID
AWS secret access key
Optionally, a session token (when using the AWS default credential provider chain)

Generate the key in the security credentials section of the Amazon IAM Management Console. In the navigation bar on the upper right, choose your user name, and then choose My Security Credentials.

Using the AWS default credential provider chain

The AWS SDK uses a chain of sources to look for credentials in a specific order. For more information, see Default credentials provider chain.

Set your AWS credentials by following the instructions in the AWS documentation: Provide temporary credentials to the SDK.

For a more secure implementation using the default credential provider chain, we recommend using a session token, which expires, rather than a permanent user token.
Disable Magnolia’s internal credential handling by doing one of the following:
1. Adding the following configuration properties to your WEB-INF/config/default/magnolia.properties file:
  magnolia.aws.validateCredentials=false magnolia.aws.useCredentials=false
2. Using JVM arguments as shown in the next step.

Set your AWS session or user token. AWS credentials can be injected using environment variables or JVM system properties. For more details, see Default credentials provider chain and Configure access to temporary credentials.

Example configuration with a session token and JVM arguments

-Dmagnolia.aws.validateCredentials=false(1)
-Dmagnolia.aws.useCredentials=false(1)
-Daws.accessKeyId=$AWS_ACCESS_KEY_ID(2)
-Daws.secretAccessKey=$AWS_SECRET_ACCESS_KEY(2)
-Daws.sessionToken=$AWS_SESSION_TOKEN(2)(3)

1	Disables Magnolia’s internal credential handling using JVM properties.
2	JVM properties to inject environment variables containing the AWS credentials. Ensure that your environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` are set.
3	`AWS_SESSION_TOKEN` is optional.

Example configuration with a permanent user token

-Dmagnolia.aws.validateCredentials=false
-Dmagnolia.aws.useCredentials=false
-Daws.accessKeyId=<your-access-key-id>
-Daws.secretAccessKey=<your-secret-access-key>

Feedback

DX Core

Configuration

REST-based publication

MicroProfile Config

Properties

Versioning store

Properties

Amazon S3

Properties

AWS connection

Using the AWS default credential provider chain

Location

Main doc sections