> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsun YAML tags

> A description of custom YAML tags available for Upsun files.

In addition to the [basic functions you should be familiar with](/docs/core-concepts/yaml/what-is-yaml), YAML allows for special tags.
Upsun accepts certain custom tags to facilitate working with configuration files.

These tags work with Upsun configuration files, but may not elsewhere.

## Include

Use the `!include` tag to embed external files within a given YAML file.

The tag requires two properties:

| Property | Type     | Possible values               | Description                                                                                             |
| -------- | -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| `type`   | `string` | `string`, `binary`, or `yaml` | See the descriptions of [strings](#string), [binaries](#binary), and [YAML](#yaml). Defaults to `yaml`. |
| `path`   | `string` |                               | The path to the file to include, relative to the application directory or `source.root`.                |

<Info>
  By default, `path` is relative to the current application's directory (what you would define with `source.root`).
  It is possible to include files from a directory parent to the folder however.

  For example, for the following project structure:

  ```text theme={null}
  .
  ├── .upsun/
  |   └── .upsun/config.yaml
  ├── backend
  │   ├── main.py
  │   ├── requirements.txt
  │   └── scripts
  │       ├── ...
  │       └── common_build.sh
  └── frontend
      ├── README.md
      ├── package-lock.json
      ├── package.json
      ├── public
      ├── scripts
      │   └── clean.sh
      └── src
  ```

  This configuration is valid:

  ```yaml .upsun/config.yaml theme={null}
  applications:
    frontend:
      source:
        root: frontend

      # ...

      hooks:
        build: !include
          type: string
          path: ../backend/scripts/common_build.sh
  ```
</Info>

### `string`

Use `string` to include an external file inline in the YAML file as if entered as a multi-line string.

For example, if you have a build hook like the following:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: |
        set -e
        cp a.txt b.txt
```

You could create a file for the script:

```text build.sh theme={null}
set -e
cp a.txt b.txt
```

And replace the hook with an include tag for an identical result:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    hooks:
      build: !include
        type: string
        path: build.sh
```

This helps you break longer configuration like build scripts out into a separate file for easier maintenance.

Even if `path` is relative to the current application's directory, it is also possible to include a shell script from a directory parent to the folder however.

For example, for the following project structure:

```bash theme={null}
.
├── .upsun/
|   └── config.yaml
├── backend
│   ├── main.py
│   ├── requirements.txt
│   └── scripts
│       ├── ...
│       └── common_build.sh
└── frontend
    ├── README.md
    ├── package-lock.json
    ├── package.json
    ├── public
    ├── scripts
    │   └── clean.sh
    └── src
```

This configuration is valid:

```yaml .upsun/config.yaml theme={null}
applications:
  frontend:
    source:
      root: frontend
    # ...
    hooks:
      build: !include
        type: string
        path: ../backend/scripts/common_build.sh
```

<Info>
  Please note that Upsun will execute this `../backend/scripts/common_build.sh` script using [Dash](https://wiki.archlinux.org/title/Dash).
</Info>

### `binary`

Use `binary` to include an external binary file inline in the YAML file.
The file is base64 encoded.

For example, you could include a `favicon.ico` file in the same folder as your app configuration.
Then you can include it as follows:

```yaml .upsun/config.yaml theme={null}
some-property:
  favicon: !include
    type: binary
    path: favicon.ico
```

### `yaml`

Use `yaml` to include an external YAML file inline as if entered directly.
Because `yaml` is the default, you can use it without specifying the type.

For example, you could have your configuration for works defined in a `worker.yaml` file:

```yaml worker.yaml theme={null}
commands:
  start: python queue-worker.py
variables:
  env:
    type: worker
```

Then the following three configurations are exactly equivalent:

```yaml .upsun/config.yaml theme={null}
workers:
  queue1: !include "worker.yaml"
```

```yaml .upsun/config.yaml theme={null}
workers:
  queue1: !include
    type: yaml
    path: 'worker.yaml'
```

```yaml .upsun/config.yaml theme={null}
workers:
  queue1:
    commands:
      start: python queue-worker.py
    variables:
      env:
        type: worker
```

This can help simplify more complex files.

For [multiple application](/docs/configure-apps/multi-app) project, you can also include another `.upsun/apps/my-app.yaml` file in the main `.upsun/config.yaml`.

```yaml .upsun/apps/my-app.yaml theme={null}
source:
  root: "/"
type: "nodejs:18"
web:
  commands:
    start: "node index.js"
  upstream:
    socket_family: tcp
  locations:
    "/":
      passthru: true
```

and including it:

```yaml .upsun/config.yaml theme={null}
applications:
  myapp:
    !include ./apps/my-app.yaml
```

## Archive

Use the `!archive` tag for a reference to an entire directory specified relative to where the YAML file is.

For example, you might want to define a configuration directory for your [Solr service](/docs/add-services/solr).
You might do so as follows:

```yaml .upsun/config.yaml theme={null}
mysearch:
  type: solr:8.0
  configuration:
      conf_dir: !archive "solr/conf"
```

The `!archive` tag means that the value for `conf_dir` isn't the string `solr/conf` but the entire `solr/conf` directory.
This directory is in the `.upsun/` directory, since that's where the `.upsun/config.yaml` file is.
The `solr/conf` directory is then copied into the Upsun management system to use with the service.