Import your own code

Configure application

You will next need to include information that defines how you want your application to behave each time it is built and deployed on Platform.sh in a .platform.app.yaml file.

├── .platform
│   ├── routes.yaml
│   └── services.yaml
├── .platform.app.yaml
└── < application code >

An example .platform.app.yaml looks like this:

PHP
Go
Python
Node.js
# This file describes an application. You can have multiple applications
# in the same project.

# The name of this app. Must be unique within a project.
name: app

# The type of the application to build.
type: php:7.3
build:
    flavor: composer

# The hooks that will be performed when the package is deployed.
hooks:
    build: |
        set -e

    deploy: |
        set -e

# The relationships of the application with services or other applications.
# The left-hand side is the name of the relationship as it will be exposed
# to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand
# side is in the form `<service name>:<endpoint name>`.
#relationships:
#    database: "db:mysql"

# The size of the persistent disk of the application (in MB).
disk: 2048

# The mounts that will be performed when the package is deployed.
mounts:
    # Because this directory is in the webroot, files here will be web-accessible.
    'web/uploads':
        source: local
        source_path: uploads
    # Files in this directory will not be web-accessible.
    'private':
        source: local
        source_path: private


# The configuration of app when it is exposed to the web.
web:
    locations:
        "/":
            # The public directory of the app, relative to its root.
            root: "web"
            # The front-controller script to send non-static requests to.
            passthru: "/index.php"
# This file describes an application. You can have multiple applications
# in the same project.
#
# See https://docs.platform.sh/user_guide/reference/platform-app-yaml.html

# The name of this app. Must be unique within a project.
name: app

# The runtime the application uses.
type: golang:1.13

# The hooks executed at various points in the lifecycle of the application.
hooks:
    build: |
        # Modify this line if you want to build differently or use an alternate name for your executable.
        go build -o bin/app

# The relationships of the application with services or other applications.
#
# The left-hand side is the name of the relationship as it will be exposed
# to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand
# side is in the form `<service name>:<endpoint name>`.
relationships:
    database: "db:mysql"

# The configuration of app when it is exposed to the web.
web:
    upstream:
        socket_family: tcp
        protocol: http

    commands:
        # If you change the build output in the build hook above, update this line as well.
        start: ./bin/app

    locations:
        /:
            # Route all requests to the Go app, unconditionally.
            # If you want some files served directly by the web server without hitting Go, see
            # https://docs.platform.sh/configuration/app/web.html
            allow: false
            passthru: true

# The size of the persistent disk of the application (in MB).
disk: 1024
# This file describes an application. You can have multiple applications
# in the same project.
#
# See https://docs.platform.sh/user_guide/reference/platform-app-yaml.html

# The name of this app. Must be unique within a project.
name: app

# The runtime the application uses.
type: "python:3.7"

# The build-time dependencies of the app.
dependencies:
    python3:
       pipenv: "2018.10.13"

# The hooks executed at various points in the lifecycle of the application.
hooks:
    build: |
      pipenv install --system --deploy

# The size of the persistent disk of the application (in MB).
disk: 1024
# The relationships of the application with services or other applications.
#
# The left-hand side is the name of the relationship as it will be exposed
# to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand
# side is in the form `<service name>:<endpoint name>`.
relationships:
    database: "db:mysql"
    rediscache: "cache:redis"

# The configuration of app when it is exposed to the web.
web:
    commands:
        start: python server.py
# This file describes an application. You can have multiple applications
# in the same project.
#
# See https://docs.platform.sh/user_guide/reference/platform-app-yaml.html

# The name of this app. Must be unique within a project.
name: app

# The runtime the application uses.
type: nodejs:10

# The relationships of the application with services or other applications.
#
# The left-hand side is the name of the relationship as it will be exposed
# to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand
# side is in the form `<service name>:<endpoint name>`.
relationships:
  database: "db:mysql"

# The configuration of app when it is exposed to the web.
web:
  commands:
   start: "node index.js"

# The size of the persistent disk of the application (in MB).
disk: 512

mounts:
    'run':
        source: local
        source_path: run

The .platform.appl.yaml file is extremely flexible, and can contain many lines with very fine-grained control over your application. At the very least, Platform.sh requires three principle attributes in this file to control your builds:

  • name: The name of your application container does not have to be the same as your project name, and in most single application cases you can simply name it app. You should notice in the next step, when you configure how requests are handled in .platform/routes.yaml that name is reused there, and it is important that they are the same.

    Note If you are trying to to deploy microservices, the only constraint is that each of these application names must be unique.

  • type: The type attribute in .platform.app.yaml sets the container base image for the application, and sets the primary language. In general, type should have the form

    type: <runtime>:<version>
    

    Set version to one supported by Platform.sh, which you can find below as well as in the documentation for each language:

Language runtime Supported version
C#/.Net Core dotnet 2.0, 2.1, 2.2
Go golang 1.11, 1.12, 1.13
Java java 11, 12, 8, 13
Lisp lisp 1.5
Node.js nodejs 6, 8, 10
PHP php 7.2, 7.3, 7.4
Python python 2.7, 3.5, 3.6, 3.7, 3.8
Ruby ruby 2.3, 2.4, 2.5, 2.6
  • disk: The disk attribute defines that amount of persistent storage you need to have available for your application, and requires a minimum value of 256 MB.

There are a few additional keys in .platform.app.yaml you will likely need to use to fully configure your application, but are not required:

  • relationships: Relationships define how services are mapped within your application. Without this block, an application cannot by default communicate with a service container. Provide a unique name for each relationship and associate it with a service. For example, if in the previous step you defined a MariaDB container in your .platform/services.yaml with

    db:
        type: mariadb:10.4
        disk: 256

    You must define a relationship (i.e. database) in .platform.app.yaml to connect to it:

    relationships:
        database: "db:mysql"

  • Build and deploy tasks: There are a number of ways in which your Git repository is turned into a running application. In general, the build process will run the the build flavor, install dependencies, and then execute the build hook you provide. When the build process is completed, the deploy process will run the deploy hook.

    • build: The build key defines what happens during the build process using the flavor property. This is a common inclusion for PHP and Node.js applications, so check the the documentation to see if your configuration requires this key.
    • dependencies: This key makes it possible to install system-level dependencies as part of the build process.
    • hooks: Hooks define custom scripts that you want to run at different points during the deployment process.
      • build: The build hook is run after the build flavor if that is present. The file system is fully writable, but no services and only a subset of variables are available at this point. The full list of build time and runtime variables is available on the variables section of the public documentation.
      • deploy: The deploy hook is run after the application container has been started, but before it has started accepting requests. Services are now available, but the file system will be read-only from this point forward.
      • post-deploy: The post-deploy hook functions exactly the same as the deploy hook, but after the container is accepting connections.
  • web: The web key configures the web server through a single web instance container running a single Nginx server process, behind which runs your application.

    • commands: Defines the command to actually launch the application. The start key launches your application. In all languages except for PHP, web.commands.start should be treated as required. For PHP, you will instead need to define a script name in passthru, described below in locations.
    • locations: Allows you to control how the application container responds to incoming requests at a very fine-grained level. The simplest possible locations configuration is one that simply passes all requests on to your application unconditionally:

      web:
        locations:
          '/':
              passthru: true
      

      The above configuration forwards all requests to /* to the process started by web.commands.start. In the case of PHP containers, passthru must specify what PHP file to forward the request to, as well as the docroot under which the file lives. For example,

      web:
        locations:
            '/':
                root: 'web'
                passthru: '/app.php'
      
  • mounts: Configuring mounts are not required, unless part of your application requires write-access. By default, Platform.sh provided a read-only filesystem for your projects so that you can be confident in the health and security of your application once it has deployed.

    If your application requires writable storage to function properly (i.e., saving files; mounts should not contain code) it can be defined like so:

    mounts:
      'web/uploads':
          source: local
          source_path: uploads
    

    In this case, the application will be able to write to a mount that is visible in the /app/web/uploads directory of the application container, and which has a local source at /mnt/uploads. Consult the mounts documentation for a more thorough discussion of how these attributes should be written.

Each language and framework may have additional attributes that you will need to include in .platform.app.yaml depending on the needs of your application. To find out what else you may need to include to configure your application, consult

  • The Application documentation for Platform.sh: The documentation goes into far more extensive detail of which attributes can also be included for application configuration, and should be used as your primary reference.

  • Language-specific templates for Platform.sh Projects: Compare the .platform.app.yaml file from the simple template above to other templates when writing your own.

Now that you have configured your application, you will next need to handle HTTP requests to your application using the .platform/routes.yaml file.