Deployment

Deployment is the process of downloading your code from your Git provider onto your server and running the deploy script. The Deploy Now button sits at the top right of the Deployments page, next to a summary of the latest deployment (branch, commit, status and time). The page contains the following sections:

• Source & deploy triggers: on the left, Source code (Git provider, repository, deployed branch, a Change branch link and a collapsed Site deploy key section); on the right, Auto deploy with the Push to deploy switch and the Deploy trigger URL.
• Deployment Histories
• Deploy Script

Sites not installed from Git (for example WordPress) can still be deployed: click Deploy Now or use the Deploy trigger URL to run your deploy script.

The Deployment Histories table shows the date, branch, author, commit, duration and status of each deployment. Click a row to open the log of that deployment; after you click Deploy Now, the row of the new deployment opens automatically. For security, the log is deleted 7 days after the deployment; the rest of the history is kept for 3 months.

.env file

Some applications, such as Laravel applications, need an .env file to configure the database, cache, and so on. You can create and edit this file directly in FlashPanel.

On the site's Overview page > Utilities section > select .env. The file opens in an editor where you can edit and save it.

! Automatic .env file

When you install a Git repository containing a Laravel application, FlashPanel automatically creates the .env file from .env.example (or an empty .env file if the project has no .env.example), then sets the production environment, turns off debug mode and fills in the server's database connection details.

Automatic deployment

Auto deploy lets you deploy your project as soon as you push code to your Git provider. When you push to the configured deployment branch, FlashPanel pulls the latest code and runs your application's deploy script.

Steps to enable auto deploy:

1. On the site management page, open Deployments in the left-hand menu
2. In Source & deploy triggers > Auto deploy, turn on the Push to deploy switch. Turn it off to stop deploying automatically

INFO

The Push to deploy switch is only available for sites installed from GitHub, GitLab or Bitbucket, and for paid users. For a self-hosted Git repository, use the deploy trigger URL.

Deployment script

The commands executed on your server when your project is deployed are defined by your site's deploy script. You can edit it in the Deploy Script section of the Deployments page, then click Save (or press Ctrl/⌘ + S). While there are unsaved changes, the section title shows an Unsaved changes label; click Discard changes to go back to the saved script. Click the Custom Scripts icon in the corner of the editor to paste a saved script.

While the script has unsaved changes, the Deploy Now button becomes Save & deploy: the script is saved first and then deployed.

FlashPanel provides several variables for you to use; click the Variables button at the top right of the Deploy Script section to see their actual values for your site and copy a variable name:

FLASHPANEL_SITE_ROOT='/path/to/yoursite.com'
FLASHPANEL_SITE_OWNER='site-owner'
FLASHPANEL_CODE_BRANCH='siteBranch'
FLASHPANEL_PHP='your-phpVersion'
FLASHPANEL_PHP_FPM='your-phpVersion-fpm'

The default deploy script for a site installed from Git looks like this:

cd $FLASHPANEL_SITE_ROOT

# Checkout lock file
if [ -f composer.lock ]; then
  git checkout composer.lock
fi

if [ -f package-lock.json ]; then
  git checkout package-lock.json
fi

git pull origin $FLASHPANEL_CODE_BRANCH

# Install Composer
# $FLASHPANEL_PHP /usr/local/bin/composer install --no-dev --optimize-autoloader --no-ansi

# echo 'Restarting FPM...';
# sudo -S service $FLASHPANEL_PHP_FPM reload

Remove the leading # from the commands you want to run.

Output limit

Only the first 50 KB of the deployment output is kept. Use quiet flags or > /dev/null to print only what you need, see Output limit.

PHP Versions

If you have multiple PHP versions installed on your server, your deploy script may need to be updated to use the correct PHP version.

By default, php always points to the PHP version used on the command line (CLI). If you need a different PHP version, call phpx.x, where x.x is the version (e.g. php8.3).

The deploy script for newly created sites uses the $FLASHPANEL_PHP environment variable. This environment variable always contains the site's current PHP version, so you don't need to change your deploy script when you switch the site's PHP version.

Environment variables

FlashPanel automatically injects the following environment variables into your deploy script at runtime:

Variable	Description
FLASHPANEL_SITE_ROOT	The site's root directory, e.g. /home/flashpanel/mysite.com
FLASHPANEL_SITE_OWNER	The Linux user that owns the site.
FLASHPANEL_CODE_BRANCH	The name of the branch to be deployed.
FLASHPANEL_PHP	The PHP command for the site's PHP version (e.g. php8.3).
FLASHPANEL_PHP_FPM	The site's PHP-FPM service name (e.g. php8.3-fpm).
FLASHPANEL_PNPM	Path to the pnpm command of the site owner.

WARNING

Environment Variables

FlashPanel prefixes every injected variable with FLASHPANEL_. Please do not use this prefix when defining your own environment variables.

Deploy from CI

Besides deploying from the FlashPanel dashboard or with Auto deploy, you can also deploy from the CI platform of your choice using the Deploy trigger URL.

1. On the Deployments page > Source & deploy triggers > Deploy trigger URL
2. Click Refresh trigger URL and confirm to generate a new URL, then copy it

WARNING

The URL is only shown once, right after it is refreshed. Copy it and store it somewhere safe; if you lose it, refresh again to generate a new one.

INFO

Refreshing the trigger URL is available for paid users only.

Use the Deployment Trigger

You can deploy at any time by having your CI platform send a GET or POST request to the trigger URL.

You can refresh the URL at any time, but you'll then need to update every service that uses the old URL.

Deployment branch

You can change the branch deployed for your site. After changing the branch, click Deploy Now to deploy the code from the new branch.

Steps to update the deployment branch:

1. On the site management page > open Settings > Update Git Branch section
2. Select or enter the new branch name
3. Click Update

Steps to deploy manually:

1. On the site management page > open Deployments
2. Click Deploy Now at the top right of the page

Git Remote

Updating the Git remote changes the repository URL on your server; the site is not removed or interrupted during this process. The new Git remote must contain the same repository/Git history as the currently installed repository.

You should not use this function to install a completely different project. If you want to install a different project, completely remove the existing code with Remove Code first.

Steps to update the Git remote:

1. On the site management page > open Settings > Update Git Remote section
2. Change the provider, Git account or repository address. See Site settings for details.
3. Click Update

Steps to remove code:

1. On the site's Overview page > Danger Zone section > select Remove Code
2. (Optional) Check Delete Database, Delete Database User (only shown when the site has an attached database) and Restore default page?
3. Check Yes, Do it! and click Remove Code