Locations

The locations section associates absolute URI prefixes (location) to a specific configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# .symfony.cloud.yaml
web:
    locations:
        "/":
            root: "public"
            passthru: "/index.php"
            #index: [ index.php ]
            expires: -1
            scripts: true
            allow: true
            rules:
                '\.(gif|jpe?g|png)$':
                    expires: 60
        "/admin":
            expires: 300
            passthru: true
            allow: true

Here is the reference of location configurations:

• root defines the folder used to serve static content for the given location, relative to the application root. Typical values for this property are public or web. Absolute paths are not supported.

  Caution

  SymfonyCloud requires that the location root must not be the root of the project. It is important for security that private file mounts are not web-accessible.

• expires: Enables the Cache-Control and Expires headers for static resources. Can be a duration or -1 for no caching (default). Times can be suffixed with "ms" (milliseconds), "s" (seconds), "m" (minutes), "h" (hours), "d" (days), "w" (weeks), "M" (months, 30d) or "y" (years, 365d).
• index determines the file (or files) to consider when serving a request for a directory. It can be a filename, an array of filenames, or null. Typically index.php.
• scripts allows or disallows execution of scripts in that location. Possible values are true or false, default is true.
• passthru makes requests forwarded to the application if the resource is missing. Typical values for non-PHP applications are true or false. In a PHP application, the value is the path to the front controller such as /index.php or /app.php. The default value is false.
• headers defines any additional headers to apply to static assets. This section is a mapping of header names to header values. Responses sent by the application aren't affected.
• allow allows or disallows serving files which don't match a rule. Possible values are true or false, default is true.
• request_buffering allows to enable or disable request buffering. As most application servers do not support chunked requests (e.g. fpm, uwsgi), request_buffering is enabled by default.
• rules defines rules to override current settings for some requests. The key is a PCRE regular expression that is matched against the full request URI, content is the same structure as locations configuration.

Upstream

upstream is an optional key that describes how the application listens to requests, in particular which protocol is used:

1
2
3
4
5

# .symfony.cloud.yaml
web:
    upstream:
        socket_family: tcp
        protocol: http

• socket_family describes whether the application listens on a Unix socket (unix) or a TCP one (tcp, the default). When defined to unix, SymfonyCloud sets the SOCKET environment variable with the path to the socket that the application must listen to. With tcp, SymfonyCloud sets the PORT environment variable with the port that the application must listen on.

  Tip

  If the application is not listening at the expected location, SymfonyCloud returns 502 Bad Gateway errors.

• protocol specifies if the application expects to receive incoming requests over the HTTP or the FastCGI protocol. Possible values are http and fastcgi. The default varies depending on the runtime the application is using.

Commands

Under the commands section, the start entry defines the command used to launch the application server listening according to the upstream configuration:

1
2
3
4

# .symfony.cloud.yaml
web:
    commands:
        start: "gunicorn -b $PORT project.wsgi:application"

curl -s https://get.symfony.com/cloud/configurator | (>&2 bash)

The configurator is a script specially crafted for SymfonyCloud. It ensures that projects are always using the most up-to-date version of some tools:

• croncape
• Symfony CLI
• Composer

Additionally, it creates some helpers: symfony-build, symfony-start, symfony-deploy, symfony-database-migrate, php-ext-install, and yarn-install.

(>&2 symfony-build)

symfony-build is our recipe to build a Symfony application the best way possible. It removes the development frontend, install the application dependencies using Composer (and Yarn, by running yarn-install), optimize the autoloader, build Symfony cache if possible and finally build the production assets using Encore.

Composer install is run using default flag values. If you need to override those flags, you can define them using the $COMPOSER_FLAGS environment variable:

1
2
3
4
5
6
7

# .symfony.cloud.yaml
hooks:
    build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | (>&2 bash)
        (>&2 COMPOSER_FLAGS="--ignore-platform-reqs" symfony-build)

One can also set NO_YARN to any value to disable all Yarn and assets automation during the symfony-build run.

(>&2 symfony-deploy)

symfony-deploy is to be used each time a Symfony application is deployed. Its purpose is to run the symfony-start helper and when executed from the web container, restart FPM and run the symfony-database-migrate helper.

(>&2 symfony-start)

symfony-start is to be used each time a Symfony application starts in a new container. Its purpose is to move the Symfony cache built by symfony-build to be used by the application or built the cache otherwise. It is automatically executed by symfony-deploy and SymfonyCloud automatically runs it before starting (or restarting) workers.

(>&2 symfony-database-migrate)

You usually don't need to worry about this helper. symfony-database-migrate purpose is to run database migrations. By default, it will run your Doctrine migrations if doctrine/doctrine-migrations-bundle is installed. If your application uses another migration system you can override /app/.global/bin/symfony-database-migrate during build time and symfony-deploy will make use of it. You can use this script at any moment if you need to run migrations manually or if you need to run them for workers.

php-ext-install

php-ext-install is a script that you can use to compile and install PHP extensions not provided out of the box by SymfonyCloud. It is written specifically for SymfonyCloud to ensure fast and reliable setup during the build step. It currently supports three ways to fetch the sources from:

• From PECL: php-ext-install redis 5.3.2
• From a URL: php-ext-install redis https://github.com/phpredis/phpredis/archive/5.3.2.tar.gz
• From a Git repository: php-ext-install redis https://github.com/phpredis/phpredis.git 5.3.2

To ensure your application can be built properly, it is recommended to run php-ext-install after the configurator but before symfony-build:

1
2
3
4
5
6
7
8
9
10

# .symfony.cloud.yaml
hooks:
    build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | (>&2 bash)
        (>&2
            php-ext-install redis 5.3.2
            symfony-build
        )

When installing PECL PHP extensions, you can configure them directly as variables instead:

1
2
3
4

# .symfony.cloud.yaml
variables:
    php-ext:
        redis: 5.3.2

yarn-install

yarn-install is a script that installs Node and Yarn the best way possible in a PHP container on SymfonyCloud. Similarly to Composer install, you can customize Node setup and Yarn install behaviors using the following environment variables:

• NVM_DIR: Directory used to install NVM and Node. Default value is /app/.nvm.
• NODE_VERSION: Pinpoint the Node version that NVM is going to install. Default is --lts
• YARN_FLAGS: Flags to pass to yarn install. No value by default.

Shall you need to use the Node installation setup by symfony-build, you can use the following snippet:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# .symfony.cloud.yaml
hooks:
    build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | (>&2 bash)
        (>&2 symfony-build)
        (>&2
            # Setup everything to use the Node installation
            unset NPM_CONFIG_PREFIX
            export NVM_DIR=${SYMFONY_APP_DIR}/.nvm
            set +x && . "${NVM_DIR}/nvm.sh" use --lts && set -x
            # Starting from here, everything is setup to use the same Node
            yarn encore dev
        )

Or if you want to use two different Node versions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# .symfony.cloud.yaml
hooks:
    build: |
        set -x -e

        curl -s https://get.symfony.com/cloud/configurator | (>&2 bash)
        (>&2 symfony-build)
        (>&2
            cd web/js_app
            unset NPM_CONFIG_PREFIX
            export NVM_DIR=${SYMFONY_APP_DIR}/.nvm

            NODE_VERSION=8 yarn-install

            # Setup everything to use the Node installation
            set +x && . "${NVM_DIR}/nvm.sh" use 8 && set -x

            # Starting from here, everything is setup to use Node 8
            yarn build --environment=prod
        )