Sari la conținutul principal
FreeThree checks for your projectUptime, accessibility, SEO and cookie checks for your project
Menu

The project file

Write and check .tilizy/app.yaml, the file that tells Tilizy how to build and run your website.

On this page

The project file, .tilizy/app.yaml, tells Tilizy how to build and run your website: the PHP version, the framework, the build steps, the scheduled jobs and the folders that must survive a deploy. It lives in your repository next to your code, so a change to your hosting is a commit you can review. If something is not written in .tilizy/, the platform does not do it.

The files in .tilizy/

FileWhat it holds
.tilizy/app.yamlThe project file. The only file that is required.
.tilizy/services.yamlThe database, cache and search services. See Services.
.tilizy/security.ymlOptional. Which database columns hold personal data, so that copies of the database leave the server with those values replaced. See Database and files.
.tilizy/<environment>/app.yamlOptional. Settings that differ for one environment, committed and shared by the team.
.tilizy/hooks/changeOptional. A script that tilizy dev:watch runs on your computer when files change.
.tilizy/local/Your own local settings and local secret values. Not committed.

Create and check the file

In an existing checkout, let the CLI write a starting point. It detects the framework, the PHP version and the web root:

tilizy app:init

After every edit, check the result. The command reads the files the same way a deploy does and prints what it understood, or an error that names the file and the key:

tilizy app:validate

A complete example

This is a small, complete project file for a Drupal website. A WordPress, PrestaShop or Laravel website uses the same keys with its own commands.

runtime: php-8.4-fpm
framework: drupal11
docroot: web

mounts:
  - source: sites/default/files
    persistent: files

hooks:
  build:
    - composer install --no-dev --optimize-autoloader --no-interaction
  deploy:
    - drush updatedb --no-interaction
    - drush config:import --no-interaction
  post_deploy:
    - drush search-api:index

crons:
  - schedule: '*/5 * * * *'
    cmd: drush cron

env:
  SITE_MODE: production

secrets:
  - HASH_SALT
  - SMTP_PASSWORD

php:
  memory_limit: 256M

resources:
  php:
    mem: 1g
    cpus: 2

Reference

Only runtime is required. Leave out what you do not need.

KeyWhat it does
runtimeThe PHP version, written as php-<version>-fpm, for example php-8.4-fpm. An unsupported value is refused, and the error lists the supported ones.
frameworkdrupal11, wordpress, prestashop, laravel, node or custom. It selects which framework commands the CLI offers. For Drupal and PrestaShop the platform also supplies the connection settings of the application. With the other values, your application reads its settings from environment variables. Empty means custom.
docrootThe folder the web server serves, relative to the repository root, for example web or public. Leave it out when the root itself is served.
mountsFolders your application writes to and that must survive a deploy, such as uploaded files. Each entry has a source, a path relative to docroot, and a persistent name. The name is what you pass to the tilizy files:* commands as --mount.
hooks.buildCommands that build the release, such as composer install and your asset build. They run in a build container before the release goes live, and are tried up to three times.
hooks.deployCommands that change the database, such as updates and a configuration import. They stop at the first failure.
hooks.post_deployCommands that run after the new release is live, such as a content import, a cache warm-up or a search reindex.
hooks.readinessOptional. One command that proves the new release starts against the updated database. It must end with a non-zero exit code on failure. If it fails, the deploy stops and the previous release keeps serving.
hooks.rehearse_migrationsOptional, true or false. Runs pending database updates on a temporary copy of the database first. Read Deploys and releases before you switch it on.
cronsScheduled commands. Each entry has a schedule and a cmd. See Cron and processes.
processesLong-running programs that Tilizy keeps running beside your website, such as a queue worker.
envEnvironment variables that are not secret, as NAME: value.
secretsThe names of the secrets your application needs. Only the names: the values are kept outside the repository. See Environment variables and secrets.
phpPHP settings as directive: value, for example memory_limit or upload_max_filesize. They override the defaults of the platform.
php_extensionsA list of optional PHP extensions to load. Only extensions the platform carries are accepted. An unknown name is refused when the file is read.
resourcesLimits per part of the environment: php, webserver, builder, or a service type such as redis. Each takes mem (512m, 2g), cpus (cores, for example 1.5) and pids.
web.servernginx or apache. Leave it out for the default of your framework: Apache for PrestaShop, nginx for everything else.
web.configThe path, relative to the repository root, of a file with extra web server rules such as rewrites or headers. Write it in the syntax of the selected server. A missing file fails the deploy.
plugins.pruneRemoves files from the built release that the running website does not need.
egress.allowHosts the copy on your computer may reach on the internet. See Run your website locally.
environmentsSettings that differ per environment, keyed by environment name.
addonsExtra CLI command sets for this project, beyond the one your framework brings.

Hooks

Every hook is a list of shell commands, run in order from the root of your application. The tools your project installs with Composer, such as drush, are on the path. A command that ends with a non-zero exit code fails the deploy. The order and the place each hook runs are described in Deploys and releases.

Settings per environment

Put the differences for one environment in .tilizy/<environment>/app.yaml, or in an environments block in the project file. The environment name is the name of its branch, for example main for a live environment that follows main. The name local stands for the copy on your computer.

environments:
  staging:
    env:
      SITE_MODE: staging
    resources:
      php:
        mem: 512m

Only these keys can differ: runtime, env, php, php_extensions, resources and egress. Any other key in an environment block is an error. The framework, the web root, the mounts, the hooks, the services and the names of the secrets are the same everywhere, which is what keeps staging a faithful copy of live.

Removing files from a release

plugins.prune shrinks the release after the build, just before it goes live. Your build and deploy hooks still see every file.

plugins:
  prune:
    paths:
      - docs
      - "**.md"
      - "web/**.txt"
      - "!web/robots.txt"
    tests: true
    unused_extensions: true
  • paths takes patterns relative to the repository root. * matches inside one folder name, ** crosses folders, and a leading ! keeps what an earlier pattern removed. The last matching pattern wins. A pattern that matches a folder applies to everything in it.
  • tests: true removes test folders.
  • unused_extensions: true removes Drupal modules and themes that are in the code but not enabled.

What can go wrong

  • A typing error in a value. An unknown runtime, framework, service type or resources key is refused with a message that names it. Run tilizy app:validate before you push.
  • Framework commands disappear from the CLI. When the project file cannot be read, tilizy drush and its relatives are not available. The CLI prints a warning that names the file and the error.
  • A mount that points outside the project. A source may leave the web root, for example ../private, but not the repository. Each mount needs a persistent name.
  • An unsafe prune pattern. A pattern that is absolute, starts with / or contains .. fails the deploy.
  • A build step that only pretends to finish. Build hooks are tried up to three times. A step that records "done" before it has finished can fail once and then pass on the second try. Make each step check its real result.

Next: Services and Deploys and releases.