Skip to main content
Version: Early Access

Customizing Large Artifact Deployments

This topic covers the configuration options available for customizing how Deploy handles large artifact deployments, including the in-memory processing threshold, executable detection regex, and JVM heap sizing guidance.

For background on how Deploy processes large artifacts and the adaptive permissions model, see How Deploy Processes Large Artifacts.

In-Memory Threshold​

ZIP archives processed using ZipFile via SeekableInMemoryByteChannel are handled in memory and preserve POSIX permissions. When a ZIP archive exceeds the configured inMemoryThreshold, Deploy processes it using ZipArchiveInputStream (streaming mode). In this mode, POSIX permissions are not preserved and adaptive permissions are applied.

If you need to further optimize heap memory usage, you can configure a lower inMemoryThreshold (in bytes) in deploy-artifact-resolver.yaml. Reducing this threshold forces ZIP archives larger than the configured value to be processed via streaming instead of in memory, thereby reducing heap consumption.

Where to configure: XL_DEPLOY_SERVER_HOME/centralConfiguration/deploy-artifact-resolver.yaml

deploy:
  artifact:
    # Size in bytes. Default is 2 GB. Values above 2 GB are capped at 2 GB.
    inMemoryThreshold: 2147483648
note

The maximum supported size for in-memory ZIP processing is 2 GB. Even if a higher value is configured, the threshold is capped at 2 GB.

Executable File Detection​

When adaptive permissions are applied, Deploy determines executable files using a configurable regular expression. A property, udm.BaseDeployableFolderArtifact.executableFileNamesRegex, is introduced for all udm.FolderArtifact deployables (for example, file.Folder). This property is used during deployment when a udm.FolderArtifact is extracted (exploded) to detect executable files.

If POSIX permissions are not available in the source archive entry stream:

  • Files matching the configured pattern receive 755 (rwxr-xr-x) permissions
  • All other files receive 644 (rw-r--r--) permissions

Where to configure: XL_DEPLOY_SERVER_HOME/centralConfiguration/type-defaults.properties

This setting is applied globally through type defaults. For more information, see Central Configuration Overview.

Default pattern:

# Regular expression that matches file names of executable files.
# Matching files receive 0755 permissions when POSIX permissions
# are not available in the source archive entry stream.

#udm.BaseDeployableFolderArtifact.executableFileNamesRegex=.+\.(sh|bat|exe|bin|py|app|cmd|pkg|run|bash|ps1)

You can adjust the pattern to match executable file types used in your environment. For example, if your deployments include Ruby scripts, add rb to the alternation group.

For more information about configuring type defaults, see Central Configuration Overview.

JVM Heap Sizing​

Processing large artifacts in memory increases heap pressure. Ensure the JVM heap is sized to accommodate the expected number and size of concurrent deployments.

For guidance on JVM heap sizing and memory configuration for your deployment size, see:

Large-Archive-Specific Logging​

To troubleshoot large-archive (> 2 GB) processing such as artifact resolution, streaming, and placeholder scanning, enable these additional packages. For background on how Deploy processes large archives, see How Deploy Processes Large Artifacts.

    <logger name="com.xebialabs.deployit.core.rest.api" level="debug" />
    <logger name="com.xebialabs.deployit.artifact.resolution" level="debug" />
    <logger name="com.xebialabs.deployit.repository.sql.artifacts" level="debug" />
    <logger name="com.xebialabs.deployit.repository.sql.commands" level="debug" />
    <logger name="com.xebialabs.deployit.repository.sql.reader" level="debug" />
    <logger name="com.xebialabs.deployit.io" level="debug" />
    <logger name="com.xebialabs.deployit.util" level="debug" />
    <logger name="com.xebialabs.xldeploy.packager" level="debug" />
    <logger name="com.xebialabs.xldeploy.packager.io" level="debug" />
    <logger name="com.xebialabs.xldeploy.packager.placeholders" level="debug" />
    <logger name="com.xebialabs.xlplatform.artifact.resolution.http" level="debug" />

After enabling these loggers, look for log entries containing stream:2G to identify where Deploy switches to the streaming code path.

caution

Do not enable debug logging during large artifact deployments in production. The volume of log output generated during streaming and placeholder scanning can flood the logs, degrade performance, and consume significant disk space. Use debug logging only in a test or staging environment to diagnose specific issues.