# Import & Export YAML Configuration


The Zerops YAML configuration provides powerful capabilities for both importing and exporting projects and services. This documentation covers how to define your infrastructure as code and move configurations between environments.

## YAML Configuration Basics

The Zerops YAML configuration can be used to create or replicate services in Zerops. You can import configurations in two ways:

- **Using the GUI**:
  - **For projects**: In the Zerops dashboard, click on **Import a project** in the Projects section
  - **For services**: Navigate to a project's details page and click **Import services** in the services section
- **Using the [CLI](/references/cli)**: Run `zcli project project-import` for projects or `zcli project service-import` for individual services

Both methods provide straightforward ways to migrate or replicate infrastructure as needed.

</Dropdown>

:::note
The example above is a general guideline; not all keys are valid for every service type. For technology-specific details, refer to the **Create service** page in the **How To** section of the Zerops documentation.

- `REQUIRED.` If a parent object is defined, the key-value pair is required to be filled. All other key-value pairs are optional.
:::

## Project Configuration

The project configuration is used to define the project you want to import.

### Usage

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">project</td>
      <td className="w-fit">object</td>
      <td className="w-fit">_REQUIRED, if a whole project is imported_ 
Only one project can be defined.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">name</td>
      <td className="w-fit">string, REQUIRED</td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">description</td>
      <td className="w-fit">string</td>
      <td className="w-fit">Description of the new project.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">corePackage</td>
      <td className="w-fit">string</td>
      <td className="w-fit">[Core package](/features/infrastructure#project-core-options) of the new project. 
Values: <b>LIGHT</b>/<b>SERIOUS</b> (default LIGHT)</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">tags</td>
      <td className="w-fit">list of strings</td>
      <td className="w-fit">One or more string tags.
Tags provide better orientation in projects.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">envVariables</td>
      <td className="w-fit">map[string]string</td>
      <td className="w-fit">[Project-level environment variables](/features/env-variables#project-variables) that are available to all services in the project.</td>
    </tr>
  </tbody>
</table>

:::important
The `corePackage` value can be upgraded later from Lightweight to Serious Core, but cannot be downgraded. Upgrades involve a brief service disruption and are partially destructive (logs/statistics are lost). Make sure to choose a suitable core package for your project. Learn more about [core upgrade process](/features/infrastructure#project-core-upgrade).
:::

This example will create a project named `project0` with [serious core](/features/infrastructure#serious-core) package and the description `This project is an example only`. The project will have two tags: `test` and `dev`, and two environment variables: `LOG_LEVEL` and `API_VERSION`:

```yaml
# ==== Define a project to import ====
project:
  # REQUIRED. Name of your project
  name: project0
  # Project description
  description: "This project is an example only"
  # Project core package
  corePackage: LIGHT
  # List of project tags for filtering
  tags:
    - test
    - dev
  # Project-level environment variables
  envVariables:
    LOG_LEVEL: info
    API_VERSION: v1
```

## Service Configuration

The service configuration defines one or more services to import into your project. Services are specified as an array under the `services` key, allowing you to configure multiple services in a single YAML file. You need at least one service and either an existing project to import into or a project defined in the YAML file.

The Service Configuration section is divided into multiple subsections for better organization:
- [**Service Basic Configuration**](#service-basic-configuration) - Core parameters like hostname, type, mode, and environment variables
- [**Service Vertical Autoscaling**](#service-vertical-autoscaling) - CPU, RAM, and disk scaling settings
- [**Service Horizontal Autoscaling**](#service-horizontal-autoscaling) - Container count scaling settings
- [**Service Mount Shared Storage**](#service-mount-shared-storage) - Connecting to shared storage services
- [**Service Nginx Configuration**](#service-nginx-configuration) - Custom web server settings
- [**Service zerops.yaml Configuration**](#service-zeropsyaml-configuration) - Build and run configurations

</Dropdown>

### Service Basic Configuration

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">services</td>
      <td className="w-fit">list of objects, REQUIRED</td>
      <td className="w-fit">At least one service is required.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">hostname</td>
      <td className="w-fit">string, REQUIRED</td>
      <td className="w-fit">
        The unique service identifier.
        Limitations:
        - duplicates in the same project forbidden
        - maximum 25 characters, lowercase ASCII letters (a-z) or numbers (0-9) only
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">type</td>
      <td className="w-fit">enum, REQUIRED</td>
      <td className="w-fit">Specifies the service type and version. See [supported types](/references/import-yaml/type-list).</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">mode</td>
      <td className="w-fit">enum</td>
      <td className="w-fit">Values: <b>HA</b> / <b>NON_HA</b> (default NON_HA)
Defines the operation mode of the service.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">envSecrets</td>
      <td className="w-fit">map[string]string</td>
      <td className="w-fit">Environment variables that are blurred by default in Zerops GUI. Can be edited or deleted in Zerops GUI.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">dotEnvSecrets</td>
      <td className="w-fit">string (multiline)</td>
      <td className="w-fit">Environment variables in .env file format that are automatically created as secret envs.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">objectStorageSize</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">Object storage size in GB.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">objectStoragePolicy</td>
      <td className="w-fit">enum</td>
      <td className="w-fit">
        Values: **private / public-read / public-objects-read / public-write / public-read-write / custom**
        Select a predefined AWS S3 bucket access policy.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">objectStorageRawPolicy</td>
      <td className="w-fit">json</td>
      <td className="w-fit">
        Define your own AWS S3 bucket access policy. See [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) for details.
        Use `{{ .BucketName }}` placeholder if you need to use bucket name in your custom policy rules.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">buildFromGit</td>
      <td className="w-fit">string (URL)</td>
      <td className="w-fit">
        A URL of a Github or Gitlab repository used for a one-time build of your service.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">enableSubdomainAccess</td>
      <td className="w-fit">boolean</td>
      <td className="w-fit">
        Default: `false`

        Set `true`, if you want to enable a public access to your service via a Zerops subdomain. Not suitable for production.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">priority</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">
        Services are sorted before creation by priority in descending order, i.e. the higher the priority the sooner the service is created.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">override</td>
      <td className="w-fit">boolean</td>
      <td className="w-fit">
        Default: `false`

        This only works for **runtime** services.

        The parameter allows you to replace an existing runtime service with the same hostname byt triggering a redeploy if the service already exists.
      </td>
    </tr>
  </tbody>
</table>

</Dropdown>

The `services` object allows you to define one or more services in the same yaml file.

:::caution
The `yamlPreprocessor` option in your project & service import YAML is required to generate random secret values, passwords, and public/private key pairs. For more information, see the [yamlPreprocessor](/references/import-yaml/pre-processor) page.
:::

### Service Vertical Autoscaling

The vertical autoscaling configuration defines how the service can scale its resources vertically.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">minCpu</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">Minimum number of virtual CPUs</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">maxCpu</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">Maximum number of virtual CPUs</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">cpuMode</td>
      <td className="w-fit">enum</td>
      <td className="w-fit">Values: **SHARED / DEDICATED**</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minRam</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum RAM in GB that each container of the service can scale down to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">maxRam</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Maximum RAM in GB that each container of the service can scale up to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minDisk</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum disk space in GB that each container of the service can scale down to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">maxDisk</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Maximum disk space in GB that each container of the service can scale up to.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">startCpuCoreCount</td>
      <td className="w-fit">integer</td>
      <td className="w-fit">
        Number of CPU cores with which each container starts.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeCpuCores</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum number of unused CPU cores before a container starts scaling.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeCpuPercent</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum percentage of unused CPU cores before a container starts scaling.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeRamGB</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum unused memory in GB before a container starts scaling.
      </td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">minFreeRamPercent</td>
      <td className="w-fit">float</td>
      <td className="w-fit">
        Minimum percentage of unused memory before a container starts scaling.
      </td>
    </tr>
  </tbody>
</table>

</Dropdown>

### Service Horizontal Autoscaling

The horizontal autoscaling configuration is used to define the horizontal autoscaling settings for the service.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
  <td className="w-fit font-semibold">minContainers</td>
  <td className="w-fit">integer</td>
  <td className="w-fit">Minimum number of containers of the service.
Default: 1, maximum value: 10</td>
</tr>
<tr>
  <td className="w-fit font-semibold">maxContainers</td>
  <td className="w-fit">integer</td>
  <td className="w-fit">Maximum number of containers of the service.
Maximum value: 10</td>
</tr>
</tbody>
</table>

```yaml
services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/zeropsio/recipe-php
    enableSubdomainAccess: true
    # Minimum number of containers
    minContainers: 2
    # Maximum number of containers
    maxContainers: 6
```

The `minContainers` and `maxContainers` parameters allow you to define the minimum and maximum number of containers for the service. The service will automatically scale between these values as needed.

### Service Mount Shared Storage

The mount shared storage configuration defines which shared storage services should be mounted to the service.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
  <tr>
    <td className="w-fit font-semibold">mount</td>
    <td className="w-fit">list of strings</td>
    <td className="w-fit">Mount shared storage to the service. `buildFromGit` must be filled.</td>
    </tr>
  </tbody>
</table>

```yaml
services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    enableSubdomainAccess: true
    mount:
      - teststorage1
```

The `mount:` parameter allows you to mount a shared storage (which should be created inside the project) to the service.

### Service Nginx Configuration

The nginx configuration defines the nginx settings for the service.

<table className="w-full my-1.5 whitespace-nowrap">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">nginxConfig</td>
      <td className="w-fit">string (multiline)</td>
      <td className="w-full">Insert full nginx config.</td>
    </tr>
   </tbody>
</table>

```yaml
#yamlPreprocessor=on
services:
  - hostname: app
    type: php-nginx@8.4
    enableSubdomainAccess: true
    nginxConfig: |-
      server {
          listen 80 default_server;
          listen [::]:80 default_server;

          server_name _;
          root /var/www;

          location / {
              try_files $uri $uri/ /index.html;
          }

          access_log syslog:server=unix:/dev/log,facility=local1 default_short;
          error_log syslog:server=unix:/dev/log,facility=local1;
      }
```

The `nginxConfig: |-` parameter allows you to specify a custom nginx configuration for the service.

### Service zerops.yaml Configuration

The `zeropsSetup` and `zeropsYaml` parameters provide flexibility in how you define and use your service configurations. Both parameters are optional and work together in the following ways:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit">Field</th>
      <th className="w-fit">Type</th>
      <th className="w-fit">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit font-semibold">zeropsSetup</td>
      <td className="w-fit whitespace-nowrap">string</td>
      <td className="w-fit">Specifies which service setup to use. This should match a setup name found in either the `zeropsYaml` parameter (if provided) or the `zerops.yaml` file in the repository root. If not specified, defaults to the service hostname.</td>
    </tr>
    <tr>
      <td className="w-fit font-semibold">zeropsYaml</td>
      <td className="w-fit whitespace-nowrap">object</td>
      <td className="w-fit">Contains the full [zerops.yaml configuration](/zerops-yaml/specification). If provided, this will be used instead of looking for a `zerops.yaml` file in the repository.</td>
    </tr>
  </tbody>
</table>

```yaml
services:
  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp
    # Specify which setup to use from zerops.yaml
    zeropsSetup: backendapi
    # Full zerops.yaml configuration
    zeropsYaml:
      zerops:
        - setup: backendapi
          build:
            base: nodejs@18
            buildCommands:
              - npm ci
              - npm run build
            deployFiles: ./dist
            cache: node_modules
          run:
            initCommands:
              - npm run db:migrate
            start: npm start
```

#### How They Work Together

- **Neither parameter specified**:
  - The system looks for a `zerops.yaml` file in the repository root
  - It searches for a setup with a name that matches the service hostname
- **Only `zeropsSetup` specified**:
  - The system looks for a setup with the specified name in the `zerops.yaml` file in the repository root
- **Only `zeropsYaml` specified**:
  - The system uses the provided YAML configuration instead of looking for a file in the repository
  - It searches for a setup with a name that matches the service hostname
- **Both parameters specified**:
  - The system uses the provided `zeropsYaml` configuration
  - It specifically looks for the setup named in `zeropsSetup` within that YAML

If the specified `zeropsSetup` does not exist in the available YAML configuration (either provided in `zeropsYaml` or found in the repository), the import will fail.

## Export

Zerops provides the ability to export your existing projects and services as YAML configurations through the GUI. This feature is particularly useful for:
- Creating backups of your project configurations
- Replicating project or service setups across different environments
- Sharing project templates with team members
- Creating version-controlled infrastructure configurations

The exported YAML follows the same structure as the import YAML configuration detailed above. It will contain all the configuration parameters you've set for your project and services.

### How to Export

#### Exporting a Single Service
Navigate to your service dashboard in the Zerops GUI, click the three-dot menu (⋮) in the top-right corner of the service card, and choose **Export service as yaml**.

#### Exporting an Entire Project
In the Zerops GUI, go to the project dashboard, click the three-dot menu (⋮) in the top-right corner of the project card, and select **Export project as yaml**.

### Using Exported Configurations

The exported YAML files are compatible with:
- The Zerops GUI import functionality
- The `zcli project project-import` command
- The `zcli project service-import` command (for single service exports)

This allows you to easily move configurations between environments or create new instances of your infrastructure.