For developers
Project configuration

2min
Requirements
Hosty CLI requires projects to use Git as a version control system. Git hashes are used to calculate build hash of the code to avoid rebuild of Docker images if hash does not change.
Configuration file
Hosting configuration for a project is represented by hosty.yaml file located in .hosty folder relative to the project's root (.hosty/hosty.yaml).
Below you can find a full example of configuration file with list of configuration options:
YAML
# Name of the hosting cluster. Provided by hosting administrators.
clusterName: unicorn
# AWS region name of the hosting cluster. Provided by hosting administrators.
clusterRegion: eu-west-2
# Name of the project. Provided by hosting administrators.
projectName: example
# List of project services.
services:
  # Adds a Redis service to the project. In this case,
  # each application will have the following env variables:
  # - REDIS_HOST
  # - REDIS_PORT
  # - REDIS_PASSWORD
  redis:
    # Size (in MB) of the Redis storage.
    size: 256

# List of project applications (usually there's only 1, but multiple applications are supported too).
applications:
  # Arbitrary name of the application.
  backend:
    # Allowed application types:
    # - php:nginx
    # - php:apache
    # - node
    # - python:nginx
    type: php:nginx
    # Path to the application folder relative to the project root.
    appRoot: ./drupal
    # List of additional files or folders to track to make Hosty aware that Docker images for
    # the environment have to be rebuilt if these files have been changed and committed to the git repo.
    # By default, only "appRoot" folder is tracked for changes.
    # Specify a list of paths relative to the project root.
    extraBuildDependencies:
      - ./.circleci

    # Nginx web server configuration.
    # Relevant only when "php:nginx" application type is chosen.
    # For nginx, we use https://github.com/wodby/nginx Docker image,
    # so you can check the repository to see the full list of configuration
    # options through environment variables.
    nginx:
      # Supported versions can be found on this page https://github.com/wodby/nginx?tab=readme-ov-file#docker-images.
      version: 1.25
      # Specify a tag of a Docker image to use.
      # Important note: Hosty automatically picks up the latest tag on deployment,
      # so for security reasons, we highly don't recommend hardcoding a tag version.
      # However, if a certain tag version of the Docker image causes issues, it
      # can be used as a temporary workaround until the issue with Docker image is solved.
      # List of supported tags can be found at https://github.com/wodby/nginx/tags.
      #tag: 5.38.0
      # Environment variables for nginx container.
      # You can find a full list of variables at https://github.com/wodby/nginx?tab=readme-ov-file#environment-variables.
      environmentVariables:
        # The application root folder is always mapped to "/var/www/html", so
        # specify here an absolute path to the web server root by replacing
        # your "appRoot" with "/var/www/html".
        NGINX_SERVER_ROOT: /var/www/html/web
        # For Drupal and WordPress, the Docker image has pre-defined presets
        # for improved developer experience and security.
        NGINX_VHOST_PRESET: drupal10

    # Apache web server configuration.
    # Relevant only when "php:apache" application type is chosen.
    # For apache we use https://github.com/wodby/apache Docker image,
    # so you can check the repository to see the full list of configuration
    # options through environment variables.
    apache:
      # Supported versions can be found on this page https://github.com/wodby/apache?tab=readme-ov-file#docker-images.
      version: 2.4
      # Specify a tag of a Docker image to use.
      # Important note: Hosty automatically picks up the latest tag on deployment,
      # so for security reasons we highly don't recommend hardcoding a tag version.
      # However, if a certain tag version of the Docker image would cause issues, it 
      # can be used as a temporary workaround until the issue with Docker image is solved.
      # List of supported tags can be found at https://github.com/wodby/apache/tags.
      #tag: 4.14.3
      # Environment variables for apache container.
      # You can find full list of variables at https://github.com/wodby/apache?tab=readme-ov-file#environment-variables.
      environmentVariables:
        # The application root folder is always mapped to "/var/www/html", so
        # specify here absolute path to the web server root by replacing
        # your "appRoot" with "/var/www/html".
        APACHE_DOCUMENT_ROOT: /var/www/html/web

    # PHP configuration.
    # Relevant only when "php:nginx" or "php:apache" application type is chosen.
    # For PHP, we use https://github.com/wodby/php Docker image,
    # so you can check the repository to see the full list of configuration
    # options through environment variables.
    php:
      # Supported versions can be found on this page https://github.com/wodby/php?tab=readme-ov-file#docker-images.
      version: 8.3
      # Specify a tag of a Docker image to use.
      # Important note: Hosty automatically picks up the latest tag on deployment,
      # so for security reasons, we highly don't recommend hard coding a tag version.
      # However, if a certain tag version of the Docker image causes issues, it
      # can be used as a temporary workaround until the issue with Docker image is solved.
      # List of supported tags can be found at https://github.com/wodby/php/tags.
      #tag: 4.52.2
      # Environment variables for php container.
      # You can find a full list of variables at https://github.com/wodby/php?tab=readme-ov-file#environment-variables.
      environmentVariables:
        # Environment variables support placeholders for several
        # global variables available at deployment:
        # - {{ projectName }}
        # - {{ clusterName }}
        # - {{ environmentName }}
        # Also, it supports several applications-specific placeholders.
        # You need to replace $applicationName with the actual name of your application
        # specified in this hosty.yaml file.
        # - {{ $applicationName.name }}
        # Replace $index with the index of host you need to use.
        # By default, there's just 1 host per application, so the $index is 0.
        # If you add more hosts to the application, then you can access their placeholders
        # by increasing $index value.
        # - {{ $applicationName.host.$index }}
        BACKEND_HOST: "{{ backend.host.0 }}"
        APPLICATION_MODE: development
      # Path to key/value .env files with environment variables.
      # Path is relative to the project root.
      environmentFiles:
        - ./.env.secrets
      # Script to build app dependencies from sources.
      hooks:
        build: |
          set -eu
          composer install --no-interaction

    # Adds a database to the application.
    database:
      # Currently only mysql database type is supported.
      type: mysql
      # List of table names to exclude content from
      # when importing database backup into development environments.
      # Use "%" wildcard symbol to add all table names matching the pattern.
      # The hosting makes 2 types of backup: full and partial.
      # Full backup contains the exact snapshot of the database "as is".
      # Partial backup contains backup with content excluded from tables
      # listed below.
      # Partial backup is used to spin up all development environments.
      # It is recommended to exclude cache tables and tables with personal
      # identifiable information for faster environments spin up and security reasons.
      excludeTablesFromImportOnDevEnvs:
        - cache%
        - sessions
        - user%

    # List of cron jobs.
    # Schedule conforms with the usual crontab syntax.
    # Cron jobs are disabled on development environments by default.
    crontab:
      enabled: true
      jobs:
        - schedule: "15 */6 * * *"
          command: drush cron

    # List of persistent file storages mounted to the application.
    persistentStorages:
      # Arbitrary name of the storage.
      public:
        # Path must be relative to the application root (appRoot) and should not include leading "./".
        path: web/sites/default/files
        # Optional list of arguments to use when importing files from s3 backup to a new
        # development environments using "aws s3 sync" command.
        syncArgsForDevEnvs: --exclude=styles/* --exclude=css/* --exclude=js/*
      # Arbitrary name of the storage.
      private:
        # Path must be relative to the application root (appRoot) and should not include leading "./".
        path: private
        # Optional list of arguments to use when importing files from s3 backup to a new
        # development environments using "aws s3 sync" command.
        syncArgsForDevEnvs: --exclude=twig/*
      # If you don't need to use "syncArgsForDevEnvs", then you can specify
      # persistent storage in shorter format as "<storageName>: <pathRelativeToAppRoot>", like on the example below.
      tmp: tmp

      # List of host names (domains) assigned to the environment.
      # See "overrides" section for an example how to assign a real domain name to a particular environment.
      #hosts:
      # By default, the hosting automatically assigns a host name based on the following pattern:
      #  - "{{ $applicationName.name }}-{{ environmentName }}.{{ projectName }}.{{ hostedZone }}"
      # For example:
      #  - "{{ drupal.name }}-{{ environmentName }}.{{ projectName }}.{{ hostedZone }}"

    # Configuration overrides for specific environments.
    overrides:
      # At the moment, we support only a list of environment names
      # as conditions for overrides.
      # Below is an example override for the stage environment.
      - condition:
          # The list of environments this overrides applies to.
          environments: [ stage ]
        # The rest of the override uses the same hierarchy as the
        # default application configuration, so you can override
        # whatever you wish.
        php:
          environmentVariables:
            APPLICATION_MODE: staging

      # At the moment, we support only a list of environment names
      # as conditions for overrides.
      # Below is an example override for the production environment.
      - condition:
          # The list of environments this overrides applies to.
          environments: [ production ]
          # Optional setting to reverse the logic of condition to apply.
          # If set to "true", then the override will be applied to all environments
          # apart from the production environment.
          negate: false
        # Assign a custom domain name to the application.
        # See "Adding a custom domain" documentation page for more details.
        hosts:
          - example.com
        # The rest of the override uses the same hierarchy as the
        # default application configuration, so you can override
        # whatever you wish.
        php:
          environmentVariables:
            APPLICATION_MODE: production
        # Specify a new cron schedule different from the default one
        # for all other environments.
        crontab:
          #enabled: true
          jobs:
            - schedule: "0 */1 * * *"
              command: drush cron

# Name of the hosting cluster. Provided by hosting administrators.
clusterName: unicorn
# AWS region name of the hosting cluster. Provided by hosting administrators.
clusterRegion: eu-west-2
# Name of the project. Provided by hosting administrators.
projectName: example
# List of project services.
services:
  # Adds a Redis service to the project. In this case,
  # each application will have the following env variables:
  # - REDIS_HOST
  # - REDIS_PORT
  # - REDIS_PASSWORD
  redis:
    # Size (in MB) of the Redis storage.
    size: 256

# List of project applications (usually there's only 1, but multiple applications are supported too).
applications:
  # Arbitrary name of the application.
  backend:
    # Allowed application types:
    # - php:nginx
    # - php:apache
    # - node
    # - python:nginx
    type: php:nginx
    # Path to the application folder relative to the project root.
    appRoot: ./drupal
    # List of additional files or folders to track to make Hosty aware that Docker images for
    # the environment have to be rebuilt if these files have been changed and committed to the git repo.
    # By default, only "appRoot" folder is tracked for changes.
    # Specify a list of paths relative to the project root.
    extraBuildDependencies:
      - ./.circleci

    # Nginx web server configuration.
    # Relevant only when "php:nginx" application type is chosen.
    # For nginx, we use https://github.com/wodby/nginx Docker image,
    # so you can check the repository to see the full list of configuration
    # options through environment variables.
    nginx:
      # Supported versions can be found on this page https://github.com/wodby/nginx?tab=readme-ov-file#docker-images.
      version: 1.25
      # Specify a tag of a Docker image to use.
      # Important note: Hosty automatically picks up the latest tag on deployment,
      # so for security reasons, we highly don't recommend hardcoding a tag version.
      # However, if a certain tag version of the Docker image causes issues, it
      # can be used as a temporary workaround until the issue with Docker image is solved.
      # List of supported tags can be found at https://github.com/wodby/nginx/tags.
      #tag: 5.38.0
      # Environment variables for nginx container.
      # You can find a full list of variables at https://github.com/wodby/nginx?tab=readme-ov-file#environment-variables.
      environmentVariables:
        # The application root folder is always mapped to "/var/www/html", so
        # specify here an absolute path to the web server root by replacing
        # your "appRoot" with "/var/www/html".
        NGINX_SERVER_ROOT: /var/www/html/web
        # For Drupal and WordPress, the Docker image has pre-defined presets
        # for improved developer experience and security.
        NGINX_VHOST_PRESET: drupal10

    # Apache web server configuration.
    # Relevant only when "php:apache" application type is chosen.
    # For apache we use https://github.com/wodby/apache Docker image,
    # so you can check the repository to see the full list of configuration
    # options through environment variables.
    apache:
      # Supported versions can be found on this page https://github.com/wodby/apache?tab=readme-ov-file#docker-images.
      version: 2.4
      # Specify a tag of a Docker image to use.
      # Important note: Hosty automatically picks up the latest tag on deployment,
      # so for security reasons we highly don't recommend hardcoding a tag version.
      # However, if a certain tag version of the Docker image would cause issues, it 
      # can be used as a temporary workaround until the issue with Docker image is solved.
      # List of supported tags can be found at https://github.com/wodby/apache/tags.
      #tag: 4.14.3
      # Environment variables for apache container.
      # You can find full list of variables at https://github.com/wodby/apache?tab=readme-ov-file#environment-variables.
      environmentVariables:
        # The application root folder is always mapped to "/var/www/html", so
        # specify here absolute path to the web server root by replacing
        # your "appRoot" with "/var/www/html".
        APACHE_DOCUMENT_ROOT: /var/www/html/web

    # PHP configuration.
    # Relevant only when "php:nginx" or "php:apache" application type is chosen.
    # For PHP, we use https://github.com/wodby/php Docker image,
    # so you can check the repository to see the full list of configuration
    # options through environment variables.
    php:
      # Supported versions can be found on this page https://github.com/wodby/php?tab=readme-ov-file#docker-images.
      version: 8.3
      # Specify a tag of a Docker image to use.
      # Important note: Hosty automatically picks up the latest tag on deployment,
      # so for security reasons, we highly don't recommend hard coding a tag version.
      # However, if a certain tag version of the Docker image causes issues, it
      # can be used as a temporary workaround until the issue with Docker image is solved.
      # List of supported tags can be found at https://github.com/wodby/php/tags.
      #tag: 4.52.2
      # Environment variables for php container.
      # You can find a full list of variables at https://github.com/wodby/php?tab=readme-ov-file#environment-variables.
      environmentVariables:
        # Environment variables support placeholders for several
        # global variables available at deployment:
        # - {{ projectName }}
        # - {{ clusterName }}
        # - {{ environmentName }}
        # Also, it supports several applications-specific placeholders.
        # You need to replace $applicationName with the actual name of your application
        # specified in this hosty.yaml file.
        # - {{ $applicationName.name }}
        # Replace $index with the index of host you need to use.
        # By default, there's just 1 host per application, so the $index is 0.
        # If you add more hosts to the application, then you can access their placeholders
        # by increasing $index value.
        # - {{ $applicationName.host.$index }}
        BACKEND_HOST: "{{ backend.host.0 }}"
        APPLICATION_MODE: development
      # Path to key/value .env files with environment variables.
      # Path is relative to the project root.
      environmentFiles:
        - ./.env.secrets
      # Script to build app dependencies from sources.
      hooks:
        build: |
          set -eu
          composer install --no-interaction

    # Adds a database to the application.
    database:
      # Currently only mysql database type is supported.
      type: mysql
      # List of table names to exclude content from
      # when importing database backup into development environments.
      # Use "%" wildcard symbol to add all table names matching the pattern.
      # The hosting makes 2 types of backup: full and partial.
      # Full backup contains the exact snapshot of the database "as is".
      # Partial backup contains backup with content excluded from tables
      # listed below.
      # Partial backup is used to spin up all development environments.
      # It is recommended to exclude cache tables and tables with personal
      # identifiable information for faster environments spin up and security reasons.
      excludeTablesFromImportOnDevEnvs:
        - cache%
        - sessions
        - user%

    # List of cron jobs.
    # Schedule conforms with the usual crontab syntax.
    # Cron jobs are disabled on development environments by default.
    crontab:
      enabled: true
      jobs:
        - schedule: "15 */6 * * *"
          command: drush cron

    # List of persistent file storages mounted to the application.
    persistentStorages:
      # Arbitrary name of the storage.
      public:
        # Path must be relative to the application root (appRoot) and should not include leading "./".
        path: web/sites/default/files
        # Optional list of arguments to use when importing files from s3 backup to a new
        # development environments using "aws s3 sync" command.
        syncArgsForDevEnvs: --exclude=styles/* --exclude=css/* --exclude=js/*
      # Arbitrary name of the storage.
      private:
        # Path must be relative to the application root (appRoot) and should not include leading "./".
        path: private
        # Optional list of arguments to use when importing files from s3 backup to a new
        # development environments using "aws s3 sync" command.
        syncArgsForDevEnvs: --exclude=twig/*
      # If you don't need to use "syncArgsForDevEnvs", then you can specify
      # persistent storage in shorter format as "<storageName>: <pathRelativeToAppRoot>", like on the example below.
      tmp: tmp

      # List of host names (domains) assigned to the environment.
      # See "overrides" section for an example how to assign a real domain name to a particular environment.
      #hosts:
      # By default, the hosting automatically assigns a host name based on the following pattern:
      #  - "{{ $applicationName.name }}-{{ environmentName }}.{{ projectName }}.{{ hostedZone }}"
      # For example:
      #  - "{{ drupal.name }}-{{ environmentName }}.{{ projectName }}.{{ hostedZone }}"

    # Configuration overrides for specific environments.
    overrides:
      # At the moment, we support only a list of environment names
      # as conditions for overrides.
      # Below is an example override for the stage environment.
      - condition:
          # The list of environments this overrides applies to.
          environments: [ stage ]
        # The rest of the override uses the same hierarchy as the
        # default application configuration, so you can override
        # whatever you wish.
        php:
          environmentVariables:
            APPLICATION_MODE: staging

      # At the moment, we support only a list of environment names
      # as conditions for overrides.
      # Below is an example override for the production environment.
      - condition:
          # The list of environments this overrides applies to.
          environments: [ production ]
          # Optional setting to reverse the logic of condition to apply.
          # If set to "true", then the override will be applied to all environments
          # apart from the production environment.
          negate: false
        # Assign a custom domain name to the application.
        # See "Adding a custom domain" documentation page for more details.
        hosts:
          - example.com
        # The rest of the override uses the same hierarchy as the
        # default application configuration, so you can override
        # whatever you wish.
        php:
          environmentVariables:
            APPLICATION_MODE: production
        # Specify a new cron schedule different from the default one
        # for all other environments.
        crontab:
          #enabled: true
          jobs:
            - schedule: "0 */1 * * *"
              command: drush cron
﻿
﻿
Adding a new project
Example: Next.js