file.Folder CI Deployments

A file.Folder configuration item (CI) in Digital.ai Deploy allows you to deploy a directory structure either as an exploded folder or from an archive onto a target host. The source for a file.Folder can be a directory, a TAR, ZIP, or other supported archive format. During deployment, the contents are extracted and copied to the destination host as a folder, using the most appropriate copy strategy for performance and correctness.

When a folder artifact is deployed to a target machine, Deploy applies copy strategies to optimize the transfer and extraction process. These strategies determine how files are packaged, transferred, and unpacked on the destination host.

File Plugin

The File plugin in Digital.ai Deploy provides the foundation for managing file-based resources, including files, folders, and archives, on target hosts. It supports placeholder replacement, upgrade, and undeploy operations, making it flexible for a wide range of deployment scenarios.

For a detailed overview of the File plugin and its capabilities, refer to File plugin.

Copy Strategies

Copy strategies define how folder artifacts are transferred and extracted on the target host. Digital.ai Deploy supports several strategies, such as OneByOne, Tar, ZipUnix and ZipWindows. The choice of strategy impacts deployment speed, file permissions, and compatibility with different operating systems.

Digital.ai Deploy supports multiple copy strategies, including OneByOne, Tar, ZipUnix and ZipWindows. Which strategy is used for a given file.Folder deployment depends on configuration and artifact type.

• For a general overview and comparison, see Copy Strategies.
• The Tar strategy has additional features specific to file.Folder deployments, described below.

Tar Copy Strategy

Deploy 25.3 introduces two new configuration options for the Tar copy strategy stripComponents and members. These options make file.Folder deployments more efficient by allowing deployment of only the necessary folder levels and files, giving greater flexibility and control.

Configuration Options

• stripComponents – Removes a defined number of leading directory levels from the archive during extraction. This ensures only the relevant portion of the folder structure is deployed, without unnecessary parent directories.

• members – Specifies which files or directories to extract from the archive. This avoids unpacking the entire archive and deploys only what is required. Members can be defined as:

  • Literal paths: project/module1/src1
  • Variables: ${dictionaryValue}

These options are configurable using YAML definitions with the xl-cli apply command. For more information about XL CLI commands, see XL CLI Command Reference.

caution

Both stripComponents and members options are only supported with the Tar copy strategy.

Configuration with YAML

You can configure stripComponents and members properties using YAML with dictionary values:

Example with stripComponents using dictionary values:

- name: Applications/test-folder-app
  type: udm.Application
  lastVersion: 1.0.0
  children:
  - name: 1.0.0
    type: udm.DeploymentPackage
    deployables:
    - name: test-folder-deployable
      type: file.Folder
      fileEncodings:
        ".+\\.properties": ISO-8859-1
      isRescanned: true
      targetPath: /app/test-folder
      targetPathShared: "true"
      createTargetPath: "true"
      stripComponents: "{{stripcomponents}}"
      members:
      - {{folder.domain.cluster}}/app/opt/ws/app/{{folder.domain.cluster}}/
      file: !file "artifacts/Applications/test-folder-app/1.0.0/test-folder-deployable/test-folder.tar.gz"

Dictionary values:

stripcomponents=6
folder.domain.cluster=sample02

note

Instead of using dictionary values, you can directly specify the values in the YAML configuration. For example, you can set stripComponents: "6" directly in the deployable configuration without using the {{stripcomponents}} placeholder.

Example with default copy strategy configuration:

- name: Applications/test-sample-folder-tar
  type: udm.Application
  lastVersion: 1.0.0
  children:
  - name: 1.0.0
    type: udm.DeploymentPackage
    deployables:
    - name: test-sample-folder
      type: file.Folder
      placeholders:
      - place
      fileEncodings:
        ".+\\.properties": ISO-8859-1
      defaultCopyStrategy: Configuration/defaultCopyStrategy
      targetPath: /home/ubuntu/folder-tests/folder-new
      file: !file "artifacts/Applications/test-sample-folder-tar/1.0.0/test-sample-folder/test-sample.tar.gz"

Apply these configurations using the xl-cli apply command:

xl apply -f your-application.yaml

Example usage:

Given the following archive structure:

├── project
│   ├── module1
│   │   ├── src1
│   │   │   ├── app.py
│   │   │   └── helper.py
│   │   └── resources
│   │       └── config.yml
│   └── module2
│       ├── src2
│       │   ├── main.js
│       │   └── utils.js
│       └── docs
│           └── guide.md
│   └── module3
│       ├── src3
│       │   ├── main.js
│       │   └── utils.js
│       └── docs
│           └── guide.md
└── LICENSE

1. Using stripComponents only:

tar --strip-components=1 -xvf archive.tar.gz

Result: Removes "project" folder, extracts all contents.

   ├── module1
   │   ├── src1
   │   │   ├── app.py
   │   │   └── helper.py
   │   └── resources
   │       └── config.yml
   ├── module2
   │   ├── src2
   │   │   ├── main.js
   │   │   └── utils.js
   │   └── docs
   │       └── guide.md
   └── module3
       ├── src3
       │   ├── main.js
       │   └── utils.js
       └── docs
           └── guide.md

2. Using stripComponents with members:

tar --strip-components=1 -xvf archive.tar.gz project/module1/src1 project/module2/src2 project/module3/src3

Result: Removes "project" folder and extracts only specified paths.

├── module1
│   └── src1
│       ├── app.py
│       └── helper.py
├── module2
│   └── src2
│       ├── main.js
│       └── utils.js
└── module3
    └── src3
        ├── main.js
        └── utils.js

Using Tar with StripComponents and Member

Starting with Deploy 25.3, archives are extracted directly to the target directory instead of a temporary location. By using stripComponents, we can remove unnecessary leading directory paths, and with members, we can selectively extract only the required files or folders. This allows us to deploy just the necessary components, reducing I/O operations and improving deployment efficiency.

tar -xf <tarball> -C <target_dir> --strip-components=<stripcomponents> <members>

• For a full comparison and best practices including mixed-archive scenarios, see Copy Strategies.