App Guides

Deploying a Laravel App

This guide will help you deploy your Laravel app to the Adaptable Cloud. In just a few clicks, Adaptable deploys all the cloud-based resources you need to run your Laravel app, including:

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

»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.

important

Do not specify an exact PHP version in your composer.json.

Adaptable only supports specifying the major and minor version of PHP or a range that includes multiple minor versions. This allows Adaptable to update the patch version without breaking your app.

For example, specify a PHP version like ^8.3 or >=8.3 instead of an exact version like 8.3.1 in composer.json:

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

»Step 1: Choose a GitHub repo to deploy

Start by clicking the button below:

If you're new to Adaptable, you'll need to sign in with GitHub and authorize Adaptable to access your repo.

Choose the repo you'd like to deploy to Adaptable, then choose a branch.

Once connected, Adaptable will deploy your repo each time you push to this branch.

List of GitHub repos
tip

If you don't see the repo you're looking for, click Add more GitHub repositories to authorize Adaptable on more of your repos or GitHub organizations.

»Step 2: Choose a Deploy Template

Since you're deploying a Laravel app, choose the Laravel App Template.

Choosing a deploy template

»Step 3: Choose database type

You can choose to have Adaptable create a new fully-managed database for your app. Adaptable supports MongoDB, PostgreSQL, and Microsoft SQL Server, which are all supported by Laravel's Eloquent ORM.

If your app does not need a database or if you already have a database hosted elsewhere, choose None.

tip

If you choose an Adaptable database, Adaptable automatically sets DB_URL in your app's Runtime Environment.

If you are using an external database service, you'll need to add appropriate variables in your app's Runtime Environment after the first deploy completes.

»Step 4: Review settings

These settings tell Adaptable where to find your Laravel app within your repo and how to build and run your app.

By default, Adaptable will look in the root of your repo for a composer.json or index.php file. If your app is in a subdirectory within your repo, set Base Directory to the directory where one of those files is located.

Adaptable supports auto-detection of the Install Command, Build Command, and Start Command for most common Laravel apps. See the Laravel App Template for details on the defaults for each command.

If your app needs different commands for any of these steps, click the Change button next to the setting. Each of the commands will be executed as a bash script in the Base Directory.

When you're satisfied with the settings, click Next.

Reviewing template settings

»Database migrations

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

example

For example, if you're using the Laravel Eloquent ORM, we recommend setting your Start Command to:

php artisan migrate --force && start-php

»Step 5: Choose an app name

Choose a name for your app project on Adaptable. This name will be used to create a URL for your project like https://YOURAPPNAME.adaptable.app, so it must be unique among all other app names on Adaptable.

Enter your chosen app name and click Next.

»Step 6: Pre-flight checks

Adaptable will now perform some basic checks on your GitHub repo to ensure it's ready to deploy.

For more information on any of the checks, see Pre-flight checks.

When the checks have passed, click Deploy App to start deploying your new app.

»Deployed!

Once deployment is complete, your app will be running at https://YOURAPPNAME.adaptable.app. You will be redirected to the app status page with a congratulations message if your app deployed successfully. Otherwise you'll get an error message and some help to resolve the error. In either case, you will have the option to take a tour to see how Adaptable works!

»Setting environment variables

Laravel apps often need some environment variables in order to deploy successfully. You can add environment variables to your app's Runtime Environment after the first deploy.

»Troubleshooting 500 "Server Error"

If you open your app's URL in a web browser, Laravel may provide more information about the nature of the error.

tip

If your app's page just shows Server Error with no additional information, go to your app's Settings tab and under Runtime Environment, make sure there is a variable named APP_DEBUG with a value of true. Then click Save Settings and Update Deployment and wait for the re-deployment to complete.

Setting APP_DEBUG to true allows Laravel to give more information on errors in the web interface.

tip

Now that your app is set up on Adaptable, each time you push to the branch you selected on your GitHub repo, Adaptable will automatically deploy your code changes.

»Having trouble?

Look for the How to Fix This App tip box on your App Status page. It will help guide you toward logs and documentation appropriate for the error your app has.

If you need to make any code changes, you can push to your GitHub repo to update your app and Adaptable will re-deploy it.

If you're still having trouble deploying, contact our support team for help.

»Next Steps: Connect to the database

If you chose to have Adaptable create a new database for your app, Adaptable will automatically set the DB_URL environment variable that Laravel's Eloquent ORM will use.

No additional setup should be required.

»Additional info

»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.

note

Runtime environment variables are not available during your app's build process.

»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.