PHP App Deploy Template

The PHP App Deploy Template for Adaptable.io makes it simple to deploy an app written in PHP. In just a few clicks, Adaptable deploys all the cloud-based resources you need to run your full-stack Node.js app, including:

• Building your app into Serverless Containers
• Fully-managed Serverless Database (MongoDB, PostgreSQL, or MS SQL Server)
• Autoscaling
• Load Balancing
• HTTPS (SSL/TLS)

»Using this template

For step-by-step instructions on how to deploy your existing PHP app with this template, check out the App Guide for Deploying a PHP App.

»About this template

This deploy template uses the Adapt.js infrastructure description language, which is based on React. It is open source and is available on GitHub.

»Supported PHP versions

Adaptable currently supports PHP versions:

• 8.1
• 8.2 (default)
• 8.3

Adaptable automatically detects the PHP version to use from your composer.json file. If no composer.json file is present, the default PHP version is used.

{
  "require": {
    "php": "^8.3"
  }
}

»Template settings

»Base Directory

Specifies a sub-directory within your GitHub repo that will be used as the root of the app to be deployed.

Use this setting if you're deploying an app that is part of a monorepo or your app's source directory is not in the root of your GitHub repo.

Note that this is the directory where the Install Command, Build Command, and Start Command will be executed.
There is no access to access to anything outside the Base Directory during these commands, nor at runtime.

Default: <unset> (Looks for composer.json or index.php in the repository root directory)

»Install Command

This setting allows you to specify the install command used to fetch dependencies prior to building your code.

If you have more complex requirements than a single command, write an install script, like install.sh, place it in the Base Directory, make sure it is has executable permissions, and then use that as the Install Command.

The Install Command value will be executed as a bash shell script in the Base Directory, so you may use environment variables and other shell features. Note, however, that there is no access to files outside the base directory during this command.

Default:

• Executes composer install if a composer.json file is found.
• Installs Node.js packages using npm, yarn, or pnpm if package.json is found.

»Build Command

This setting allows you to specify the build command to run each time a new container image is built from your app source code.

Set this setting to the command line of the command used to build your project.

If you have more complex requirements than a single command, write a build script, like build.sh, place it in the Base Directory, make sure it is has executable permissions, and then use that as the Build Command.

The Build Command value will be executed as a bash shell script in the Base Directory, so you may use environment variables and other shell features. Note, however, that there is no access to files outside the base directory during this command.

Default:

• If a package.json file exists, execute either the "prod" script or the "build" script if one exists.

»Start Command

Specifies the command to run to start your app. Set this to the command that runs the production (non-development) version of your app.

The Start Command value will be executed as a bash shell script in the Base Directory, so you may use environment variables and other shell features. Note, however, that there is no access to files outside the base directory during this command.

Adaptable provides a script called start-php that sets up Nginx and then starts nginx and php-fhm with the correct options.

Default: start-php

»Database migrations

If your app needs to do database migrations, we recommend running those in your Start Command.

php artisan migrate --force && start-php

»Runtime Environment Variables

You can specify your own custom environment variables that will be available to your app while it is running. For more information on setting custom environment variables, see Customizing Your App Environment.

The template also automatically provides several pre-set environment variables to your app at runtime:

• ADAPTABLE_TRUST_PROXY_DEPTH: When this variable is set, it indicates that the app is behind one or more reverse proxies. The value is an integer number of proxies that your app may trust in the X-Forwarded-For HTTP request header. If this variable is set, the X-Forwarded-Proto and X-Forwarded-Host HTTP request headers may also be trusted.

• DATABASE_URL: This is the URL that your app should use to contact the database provisioned alongside your app. It will include the database protocol, port, and hostname, as well as the username, password, and specific database to connect to. It may also have additional query parameters containing database options. This URL can often be used directly by a library such as Sequelize. If you manually parse this URL, be aware that all special characters in each portion of the URL have been URL-encoded and should be decoded before use.
  Example: postgres://dbuser:secret@database-1.adaptable.io:1234/my-app-db?option=enabled

• EXTERNAL_HOSTNAME: This is the externally visible host and domain name for your app.
  Example: my-app.adaptable.app

• EXTERNAL_URL: This is the externally visible URL where your app users can contact your app. This will always begin with https://.
  Example: https://my-app.adaptable.app

• PORT: The TCP port that your app must listen on to receive incoming network requests. Your app is required to listen on this port. See containerized app requirements for more information.

Apps that use a PostgreSQL database will also have the following environment variables set:

• PGDATABASE: The name of the database to connect to.

• PGHOST: The hostname of the database cluster.

• PGPASSWORD: The password to use when connecting to the database. Note that this environment variable may contain special characters.

• PGPORT: The TCP port number to connect to.

• PGSSLMODE: Specifies whether to negotiate SSL/TLS with the database cluster. In Adaptable, this will always be verify-full. Adaptable-provisioned PostgreSQL databases require the use of SSL/TLS.

• PGSSLROOTCERT: Path to a file containing SSL/TLS root certificates associated with the database cluster. In order for your PostgreSQL client to verify the database cluster's certificate, you must correctly configure your PostgreSQL client to verify using this root certificate.

• PGUSER: The username to use when connecting to the database.

Apps that use a Microsoft SQL Server database will also have the following environment variables set:

• MSSQL_DATABASE: The name of the database to connect to.

• MSSQL_HOST: The hostname of the database cluster.

• MSSQL_PASSWORD: The password to use when connecting to the database. Note that this environment variable may contain special characters.

• MSSQL_TCP_PORT: The TCP port number to connect to.

• MSSQL_USER: The username to use when connecting to the database.

»Build Environment Variables

You can specify your own custom environment variables that will be available to your app during the image build process. For more information on setting custom environment variables, see Customizing Your App Environment.

»Resources created

When this template is used to deploy your app, it creates the following Adaptable Cloud resources:

»Serverless database

The first time your app is deployed, the template creates a fully-managed serverless database that your app can use to store its data.

This template supports MongoDB, PostgreSQL, and Microsoft SQL Server.

Connection information for the database is provided directly to your running app via the DATABASE_URL environment variable.

»Load balancer

The template creates an HTTPS load balancer that sits in front of your app. This means that your deployed app immediately supports TLS encryption and advanced protocols like HTTP/2 and HTTP/3 without having to change your app source code.

»Container image

The template automatically builds your app source code from your GitHub repo into a Kubernetes-compatible container image each time you push to your selected branch on GitHub.

If your app requires custom dependency install steps to be run during the image build process, see Install Command. If your app requires custom build steps to be run during the image build process, see Build Command. To provide environment variables that can be accessed during the image build process, see Build Environment.

»Serverless containers

After the template builds your app into a container image, it deploys that image to the Adaptable Container Service, which is a highly scalable serverless platform based on Kubernetes.

»Pre-flight checks

This template includes a set of pre-flight checks that are performed before your app is deployed. These checks help ensure your app meets certain requirements and can identify some common issues before deployment.

»Check: composer.json or index.php exists

The image builder requires that either composer.json or index.php exists in the Base Directory you have selected within the repository.

By default, the template looks for one of these files in the root of your GitHub repo. If your app's composer.json or index.php is in a sub-directory of your repo, you need to set Base Directory to the directory that contains one or both of those files.

If this check fails:

• Confirm you are deploying the correct GitHub repo and correct branch which contains either a composer.json file or index.php file for your app.

• Confirm your app's composer.json or index.php file is in the root directory of your GitHub repo or you have set Base Directory to the directory path within the repo where one of those files is located.

»Check: Template settings validated

This checks that your Adaptable app's settings object matches the structure required by the template. Normally, Adaptable checks this each time you modify your app's settings and will not allow you to save invalid settings.

If this check fails:

• Contact Adaptable support with any error message you receive.

»Additional app requirements

»Containerized app requirements

In order to run your app on the Adaptable Container Service, it must meet a few requirements. Most web-based apps shouldn't have trouble meeting these requirements.

• Your app must listen for HTTP requests on 0.0.0.0 on the TCP port specified by the PORT environment variable. (Alternatively, your app can listen on a fixed port, but you will have to specify this PORT in your App's settings after the first failed deploy.)

• Your app must be stateless. Although your app can write to local disk storage, that storage is a memory file system and will be lost when your app is scaled down or updated. Local disk storage is also not shared between multiple autoscaled instances of your app. This means your app cannot use local file-based databases, such as NeDB or SQLite.

• Your app cannot perform background activities outside the scope of request handling. Your app's CPU allocation is set to zero when your app is not processing a network request.

• You should not perform HTTPS/TLS in your app itself. Adaptable automatically provides HTTPS/TLS via our highly scalable load balancing tier.

• When your app starts, it must listen for HTTP requests within 4 minutes of being started.