# Codehaus Cargo : Custom File Configurations

Created by Former user, last modified by S. Ali Tokmen on May 10, 2024

### Custom File Configurations

It is sometimes necessary to make changes to files within a Cargo standalone configuration. Normally Cargo will create this configuration and then start the server leaving the user with no chance to replace or modify these files before the server is started.

#### Custom Configuration Files

The main reason for file changes is to make changes to configuration files to add, remove or modify configuration settings that are not yet covered by Cargo.

Cargo uses its own default configuration files (located within the cargo jars) which use token replacements to set the Cargo configuration options. These files can be extracted out of the jar so that modification can be made and Cargo can be instructed to use these new configuration files instead.

Custom tokens can also be specified in the configuration files and their values set in the cargo properties.

These type of files have to be marked as a configuration file so that token replacement can be used.

#### Other Generic Files and Directories

Using the custom file configuration options you can add any files or directories into the standalone configuration home. Although this shouldn't really be necessary in most situations, it is left as an option so that if the need arises if can be used.

This is not meant to be used to deploy artifacts like a war to the server, for that you should be using a Cargo Deployer.

This is not meant to be used to add extra jars to a server's classpath, for that you should be using the `extraClasspath` or`sharedClasspath` options in Cargo.

### Options

Option Name | Notes | Optional | Default Value
--- | --- | --- | ---
file | This specifies the path to the file that should be used. Can also specify a directory path if a whole directory needs to be copied over. | no | n/a
todir | This specified the name the directory that the file should be copied to relative to the configurations home. If this is not specified, its value will be determined based on the tofile setting and if that is not specified, it will default to the configuration's home directory | yes | The configuration home root
tofile | This specified the name the file to where it should be copied relative to the configurations home. This path variable can also be used to specify both the directory and file name. If this is not specified, its value will be determined based on the file name of the original file | yes | The file name of the original file
configfile | This specifies if the file being copied is a configuration file or not. This determines whether token replacement should be applied to the file. Do not use this option when passing a file that is not an ascii file as it will corrupt the copied file. | yes | `false`
overwrite | This specifies if the file should overwrite a file if it already exists | yes | `true`

Example:

file | todir | tofile | destination file (relative to standalone configuration root)
--- | --- | --- | ---
`/tmp/server.xml` | `conf` |  | `conf/server.xml`
`/tmp/server.xml` |  | `conf/server.xml` | `conf/server.xml`
`/tmp/server.xml` | `conf` | `server-2.xml` | `conf/server-2.xml`
`/tmp/server.xml` |  |  | `server.xml`

### Usage

Example pom.xml fragment of how to use custom file configuration.s
Note in this example if (customMessage) is set in any of the files with configfile=true it will be replaced with "Hello World" when it gets copied to the standalone server's directory.

    <build>
      <plugins>
        <plugin>
          <groupId>org.codehaus.cargo.maven3</groupId>
          <artifactId>cargo-maven3-plugin</artifactId>
          <configuration>
            <container>
              <containerId>tomcat5x</containerId>
            </container>
            <configuration>
              <files>
                <copy>
                  <file>/tmp/server.xml</file>
                  <tofile>conf/server.xml</tofile>
                  <configfile>true</configfile>
                  <overwrite>true</overwrite>
                </copy>
              </files>
              <properties>
                <customMessage>Hello World</customMessage>
              </properties>
            </configuration>
          </configuration>
        </plugin>
      </plugins>
    </build>