Copy Strategies

In Digital.ai Deploy, a copy strategy controls how file.Folder artifacts are transferred to target hosts using the overthere.Host library. It specifies whether files are packaged as an archive or copied individually, affecting deployment speed and compatibility.

A copy strategy defines how files are packaged, transferred, and extracted on the target system for example, whether they are bundled into an archive and moved in a single operation or copied individually. The selected strategy determines deployment performance and cross-platform compatibility.

Deploy supports the following copy strategies: Tar, ZipUnix, ZipWindows, and OneByOne (default/fallback). Strategies are applied based on the chosen configuration.

Target Host Environment Prerequisite (Deploy 25.3+)

Starting with Deploy 25.3, Deploy no longer checks for tar or unzip at runtime. These tools must be installed on the target host before deployment. If missing, archive-based strategies (Tar, ZipWindows, ZipUnix) will fail.

• Linux: Install tar and unzip.
• Windows: Ensure PowerShell 5.0+ is available with unzip support.

---

Large Artifacts Deployments (From Deploy 26.1+)

Deploy 26.1 supports deploying artifacts larger than 2 GB without failing due to archive size. This applies to all artifact types like udm.FileArtifact, udm.ArchiveArtifact, udm.FolderArtifact, but permission behavior differs only for udm.FolderArtifact with ZIP and JAR based sources.

Keep the following in mind when deploying large udm.FolderArtifact sources:

• Copy strategy: For best performance and predictable permissions on Unix targets, use Tar and udm.FolderArtifact sources in TAR formats over ZIP-based strategies.
• Heap size: Large artifacts increase memory pressure, especially with many parallel deployments. Size the Deploy JVM heap accordingly. For guidance, see Production Environment Installation.
• Permissions for large ZIP and JAR formats: For ZIP and JAR sources above 2 GB, Deploy uses adaptive permissions rather than true permission retention.

For full details on the processing pipeline, adaptive permissions, artifact storage support, and configuration options, see Deploy Larger Artifacts > 2 GB.

---

OneByOne

Copies each file individually to the target host. This is the default for backward compatibility and is used as a fallback when no other strategy is configured. OneByOne works with any artifact type, but it's not recommended when your deployment needs to preserve file permissions.

File Permission Handling

Original file permissions are not preserved. On Unix, files use default permissions (rw-r--r--). On Windows, standard ACLs are applied, but POSIX permissions are not supported. Deployments between different operating systems (for example, Linux to Windows) lose POSIX permission information.

Deployment Performance

The OneByOne strategy transfers files individually, which can result in slower deployments, especially for large folders or many small files, due to the high number of transfer operations. This approach is less efficient than archive-based strategies.

For faster deployments and better file permission handling, use Tar or Zip strategies, which transfer all files as a single archive and extract them on the target host.

---

Tar

Bundles files into a tar archive, transfers, and extracts them on the target host. From Deploy 25.3+, Tar supports options like --strip-components and members for file.Folder, enabling targeted extraction and directory flattening. Use this strategy for .tar, .tar.gz, and .tar.bz2 artifacts on Unix/Linux systems over SSH, especially when you need to preserve file permissions.

File Permission Handling

Original file permissions are preserved when deploying to Unix/Linux via SSH. Deployments to localhost or across different operating systems (for example, Unix to Windows) may not retain permissions.

Limitation

This strategy only works over SSH connections.

---

ZipWindows

Bundles files into a ZIP archive, transfers, and extracts them using the PowerShell ExtractArchive command on Windows targets. This strategy is for .zip artifacts and is ideal for Windows hosts with PowerShell 5.0 or later.

File Permission Handling

POSIX file permissions are not retained. Standard Windows ACLs are applied during extraction. For older Windows versions (earlier than Server 2016), upgrade PowerShell to meet requirements.

Limitation

Requires PowerShell 5.0 or later with unzip support on the target Windows host.

---

ZipUnix

Bundles files into a ZIP archive, transfers, and extracts them using the unzip command on Unix hosts. Use this strategy for .zip artifacts when deploying to Unix/Linux targets over SSH, especially if you need to preserve file permissions.

File Permission Handling

Original file permissions are preserved when deploying to Unix/Linux systems via SSH. Deployments to localhost or across different operating systems (for example, Linux to Windows) will not retain POSIX permissions.

note

For ZIP source archives larger than 2 GB, Deploy processes the archive using streaming and POSIX permissions from the source are not available. In this case, adaptive permissions are applied before the copy strategy transfers files to the target. For details, see How Deploy Processes Large Artifacts.

Limitation

This strategy works only with SSH connections to Unix/Linux hosts and cannot retain permissions during cross-platform deployments.

---

How to Configure

Deploy offers several configuration methods to optimize file.Folder deployments. The following section explains each option in order of precedence, from highest to lowest, in determining which copy strategy configuration is applied.

Configuration	Precedence	Behavior	Possible Values	Deploy Restart Required	Applicable For Version
Infrastructure CI details	1	If an Infrastructure CI has a copy strategy defined, this setting applies first.	Configurable per Infrastructure CI: Tar, ZipWindows, ZipUnix, OneByOne	No	All versions
Autodetect	2	Applies when autodetect: true on deploy-task.yaml and Infrastructure CI has no copy strategy defined.	true, false (default, for backward compatibility)	Yes (on modification)	All versions (behavior updated in 25.3)
Global configuration	3	Applies if Infrastructure copy strategy is not defined and autodetect: false.	Tar, Zip, OneByOne	No	25.3+
OneByOne (default and fallback)	4	Final fallback when no other setting is defined.	OneByOne copy strategy	No	All versions

1. Configure at Infrastructure Level

On any overthere.Host CI except localhost, select a Copy Strategy in the Artifact Copy Strategy section. Use this option to enforce a consistent strategy across specific hosts.

2. Enable Autodetect (Recommended)

From version 25.3, the copy strategy for a file.Folder artifact can be automatically determined based on the uploaded source artifact type, rather than the target host’s extraction capabilities. This behavior is turned off by default to make it compatible with older versions, but it can be enabled by setting the properties in deploy-task.yaml as follows:

deploy.task:
  artifact-copy-strategy:
    autodetect: true

When autodetect is set to true, Digital.ai Deploy selects the appropriate extraction tool based on the artifact’s extension (TAR, ZIP, etc.), optimizing deployments without requiring host-level configuration.

tip

For mixed artifact deployments, enable autodetect and remove infrastructure-level copy strategy settings for optimal performance.

3. Create a Global Default Copy Strategy

You can define a global default copy strategy using the configuration item defaultCopyStrategy. This strategy is applied when neither autodetect nor infrastructure-level settings are used.

This option is useful when you need a global fallback for all file.Folder deployments.
It works similarly to default CI naming conventions such as defaultSmtpServer, defaultNamedCredential, and defaultProxyServer.

For more information, see Default names for CIs in Deploy

• The new CI is called Configuration/defaultCopyStrategy and is referenced by file.Folder.
• Create this configuration under Configuration > New > file > FileCopyStrategy.

note

The name of this configuration item must be exactly defaultCopyStrategy, and the type must be file.FileCopyStrategy. When named this way, the configuration is automatically bound to file.Folder as the default and is mapped in file.folder.defaultCopyStrategy.

How the Global Default Is Applied

• New folder artifacts: If a global default is set, it is automatically applied to any newly created CI of file.Folder.
• Existing folder artifacts: Not automatically applied to CIs created before the global configuration. Update their defaultCopyStrategy field manually to use the global setting.
• Fallback behavior: If the selected strategy cannot be applied (e.g., tar command unavailable), the system falls back to OneByOne copy strategy.

---

Recommended Configuration

For best performance and minimal configuration overhead starting with Deploy 25.3+:

1. Enable autodetect (autodetect: true) so Deploy selects the optimal copy strategy per artifact.
2. Remove infrastructure (host)–level copy strategy settings unless a specific host must enforce a fixed strategy (for example, policy or tooling limitation).
3. Use the global default (defaultCopyStrategy) only as a fallback for file.Folder deployables. It applies at the folder level when no infrastructure-level setting or autodetect configuration is present.
4. Keep OneByOne only as the implicit fallback do not set it explicitly except when troubleshooting strategy failures.

If you must set a strategy manually, refer above for guidance on which strategy fits your artifact type and host environment.

Use Autodetect

Autodetect configuration option selects the copy strategy based on the artifact type. Each TAR or ZIP is transferred once as an archive and extracted on the target. In contrast, a fixed host-level strategy forces all artifacts to use the same method, which can slow deployments or cause permission issues for the minority type in mixed TAR/ZIP deployments.

Use a Global Default

Set defaultCopyStrategy in these scenarios:

• Initial rollout: To enforce a consistent baseline strategy.
• Environment validation: Confirm that tar, unzip, and PowerShell are available on target hosts before enabling autodetect.
• Multi-team environments: Provide a safe interim baseline for multiple teams.

After validation, remove the global default and rely on autodetect.

Example Use Case

When deployments contain mixed artifact types — 80% TAR / 20% ZIP files.

Scenario	Copy Strategy Defined in Infrastructure CI	Autodetect	Result	Performance
1	Tar	False	TAR files deployed using Tar copy strategy (optimized). ZIP files fallback to OneByOne copy strategy.	Partial (~80% optimized)
2	None	True	TAR files deployed using Tar copy strategy (optimized). ZIP files deployed using ZipUnix or ZipWindows copy strategy.	Full (100% optimized)