Laravel Toolkit | Plesk Obsidian Documentation

The Laravel Toolkit is a complimentary Plesk extension designed to simplify and streamline the routine tasks associated with hosting Laravel applications. This guide will walk you through the process of uploading, configuring, and executing your Laravel applications within the Plesk environment. Please note that this documentation assumes you have an existing Laravel application ready for deployment or are planning to develop one; it does not cover the steps involved in creating a Laravel application from scratch.

Prerequisites

Before you can host Laravel applications using this toolkit, the free Laravel Toolkit extension must be installed on your Plesk server.

• If you are the Plesk administrator, you can install the extension directly from the Extensions Catalog.
• If you are not the administrator, please contact your hosting provider and request that they install the extension for you.

Once the extension is successfully installed, you will observe the Laravel button in the Navigation Pane, as well as within the “Create Website” drawer on the domain cards for all your domains, indicating you are ready to proceed.

Uploading Your Application

Prior to configuring and running your Laravel application, it must first be uploaded to the Plesk server and registered with the Laravel Toolkit. There are three primary methods for achieving this:

• Create a Laravel skeleton: This option is ideal if your application is stored locally in a folder or a compressed file, or if you intend to start developing your application from the ground up. The Laravel Toolkit will establish the necessary directory structure and a local Git repository.
• Install from a remote Git repository: If your application's codebase resides in a remote Git repository, you can conveniently deploy it directly to the Plesk server using this method.
• Scan for an existing application: Should you have already manually uploaded your application to Plesk, this feature allows you to register it within the Laravel Toolkit by performing a scan.

Note: To utilize the "Create a Laravel skeleton" or "Install from a remote Git repository" functionalities, the free Git extension must be installed on your Plesk server.

Creating a Laravel Skeleton

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain designated to host your application, and then click Create Website > Laravel.
3. Select “Install Skeleton,” and then click Install Application.
4. After the skeleton has been installed, you will need to upload your application files to Plesk (for example, by using FTP or File Manager), replacing any default files as required.

Installing from a Remote Git Repository

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain designated to host your application, and then click Create Website > Laravel.
3. Choose “Install from remote repository.”
4. Enter or paste the URL of the remote repository that contains your application's files.
5. If the remote repository requires authentication, ensure you add the public key displayed on this page to your repository’s settings.
6. Click Install Application.

Scanning for an Existing Application

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then open the “Hosting & DNS” tab.
3. Click Hosting.
4. Modify the “Document root” value to align with the path to your application’s public directory (by default, this is typically `/httpdocs/public`), then click Save.
5. Return to the “Dashboard” tab, click Create Website > Laravel, click Cancel, and then click Scan.

Once your application’s files have been successfully uploaded or deployed, and your application is registered within Laravel Toolkit, the Laravel button will become visible on the card of the domain hosting your application. You may now proceed to the subsequent steps.

Running Artisan, Composer, and Node.js Commands

To effectively manage your Laravel application, you will frequently need to execute Artisan, Composer, and/or Node.js commands. The Laravel Toolkit provides a convenient way to run these commands directly from the Plesk interface, eliminating the need for shell access.

If you are uncertain whether your application requires specific Artisan, Composer, or Node.js commands to function correctly, please consult the developer or organization that provided your application.

Note: To enable the execution of Node.js commands, the free Node.js extension must be installed on the Plesk server.

Executing Artisan, Composer, or Node.js Commands

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Go to the relevant tab (Artisan, Composer, or Node.js), type the command you wish to run or select one from the provided list, and then press the Enter key or click the execute button.

Note: When running Node.js commands, it might be necessary to specify a particular Node.js version and/or package manager to achieve the desired outcome. If you are unsure which options to select, please consult the individual or entity who provided the application.

Viewing Your Application’s Log Files

As your Laravel application operates, it generates and records its activity in a dedicated log file. The Laravel Toolkit interface allows you to view the contents of this log file directly, significantly simplifying the process of monitoring your application and troubleshooting any potential issues that may arise.

Accessing Your Application’s Log

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Click Logs.

This action will open the domain log browser, filtered to display only the log entries originating from your Laravel application.

Viewing Your Application’s Scheduled Tasks

Laravel provides the capability to schedule tasks directly within your application’s codebase, rather than relying on external schedulers like cron. The Laravel Toolkit allows you to view all currently configured scheduled tasks directly from its interface. Furthermore, you can enable or disable these Laravel scheduled tasks as needed.

Accessing Your Application’s Scheduled Tasks

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Go to the “Scheduled Tasks” tab. This tab will only be visible if one or more scheduled tasks are configured within your application.

Note: To enable or disable your application’s scheduled tasks, a specific preparatory operation is required, which varies depending on whether you are using Plesk for Linux or Plesk for Windows. This procedure must be performed for every domain hosting a Laravel application whose scheduled tasks you intend to manage.

Enabling Scheduled Tasks Management

1. Log in to your Plesk account.
2. Enable the “Scheduler management” permission (found on the “Permissions” tab) for the subscription to which your application’s domain belongs.
3. (Plesk for Linux) Navigate to Websites & Domains, locate the domain hosting your application, go to the “Hosting & DNS” tab, and then click Hosting.
4. (Plesk for Linux) Under “SSH Access,” select any option other than “Forbidden,” and then click Save.

You can now manage your application’s scheduled tasks directly from the Laravel Toolkit interface.

Enabling Your Application’s Scheduled Tasks

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Click the Scheduled Tasks toggle button so that it displays “Enabled.”

Scheduled tasks are now active for your Laravel application.

Editing the Environment Variables

Your Laravel application may depend on one or more custom environment variables to function correctly, or its behavior might be influenced by specific environment variable settings. If you are unsure whether your application requires any particular environment variables, it is advisable to consult the developer or organization that provided your application.

Modifying Environment Variables

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Click the Edit button adjacent to “Environment variables (.env).”
4. Make the necessary modifications to the environment variables, and then click Update.

The updated environment variables are now in effect for your application.

Putting Your Application in Maintenance Mode

To prevent website visitors from encountering errors or an incomplete user experience while you are performing maintenance, updates, or development on your application, you can activate maintenance mode. When your application is in maintenance mode, visitors to your website will be presented with a page displaying a “503 SERVICE UNAVAILABLE” error.

Activating Maintenance Mode

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Click the Maintenance mode toggle button so that it displays “Enabled.”

Your Laravel application is now operating in maintenance mode.

Note: Remember to deactivate maintenance mode once you have completed your work or updates to ensure your application is accessible to users again.

Updating Your Application

Regardless of whether your Laravel application’s files are stored in a local or a remote Git repository, it is crucial to ensure that any changes made to the application’s code are successfully propagated to the Plesk server. You have the flexibility to choose between manual or automatic deployment methods for these updates.

If you require precise control over the timing of your application’s updates, manual deployment is recommended. With this approach, no changes committed to the application’s code in the repository will be transferred to the Plesk server until you explicitly initiate the process. The trade-off for this control is that you must perform manual actions each time an update is necessary.

Updating Your Application Manually

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Go to the “Deployment” tab and, under “Deployment mode,” select the “Manual” radio button.
4. Under “Deployment scenario,” clear the checkboxes corresponding to any steps you do not wish to execute during deployment, and then click Deploy.

Once the Laravel Toolkit has completed all selected deployment steps, your application and its dependencies will be updated.

If you prefer that changes to your application’s code are automatically propagated to the Plesk server, the method varies based on whether the application’s code is stored in a local or a remote Git repository.

Updating Your Application Automatically (Local Repository)

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Go to the “Deployment” tab and under “Deployment mode” select the “Automatic” radio button.
4. Under “Deployment scenario,” clear the checkboxes corresponding to any steps you do not wish to execute during deployment.

Now, every time a commit is pushed to the master branch of the local repository containing your application’s code, your application and its dependencies will be automatically updated.

Updating Your Application Automatically (Remote Repository)

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Copy the webhook URL displayed on this page, and then add it to your remote repository’s settings. Refer to your repository provider’s documentation for specific instructions.
4. Go to the “Deployment” tab and under “Deployment mode” select the “Automatic” radio button.
5. Under “Deployment scenario,” clear the checkboxes corresponding to any steps you do not wish to execute during deployment.

Subsequently, every time the event configured to trigger the webhook occurs in the remote repository hosting your application’s code, your application and its dependencies will be automatically updated.

Configuring a Deployment Script

Your application might necessitate the execution of specific commands on the server during the deployment process to ensure its proper functioning. To bypass the need to run these commands manually each time, you can configure a deployment script that will be automatically executed with every application update.

If you are unsure whether your application requires any particular commands to be run during deployment, please consult the developer or organization that provided your application.

Note: For Plesk for Linux users, SSH access must be enabled before you can edit the deployment script directly from the Laravel Toolkit interface. This is a one-time configuration.

(Plesk for Linux) Enabling Deployment Script Editing

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, go to the “Hosting & DNS” tab, and then click Hosting.
3. Under “SSH Access,” select any option other than “Forbidden,” and then click Save.

You are now able to edit the deployment script through the Laravel Toolkit interface.

Editing the Deployment Script

1. Log in to your Plesk account.
2. Navigate to Websites & Domains, locate the domain hosting your application, and then click Laravel.
3. Go to the “Deployment” tab, and then click Edit script.
4. Type or paste your desired deployment script, and then click Update.

The deployment script is now active and will be executed automatically whenever you update your application.

Managing Queues

Queues in Laravel are a powerful mechanism that enables the asynchronous processing of time-consuming tasks, such as parsing large uploaded files, in the background. If your application is designed to utilize queues, you can enable and configure the queue worker process directly within Plesk.

To implement queues, you must first enable them for your subscription and create a database for the queue worker to utilize. This is a one-time setup procedure.

Laravel queues support various queue backends. However, this guide focuses exclusively on using a MySQL/MariaDB database as the backend, which is the most straightforward method for enabling queues in Plesk and typically sufficient for most users. While other backends may offer advantages like improved access times, they often demand specialized expertise for implementation and maintenance, and may also involve additional costs.

Enabling Queues

1. Log in to your Plesk account, and then locate the domain hosting your application.
2. Enable scheduled tasks for your application. This step is essential for queues to function correctly.
3. In your application’s Git project repository, add the following line to the “require” section of the composer.json file:

   "plesk/ext-laravel-integration": "^7.0"

   Note: Within each section of the composer.json file, every line, except for the last one, must terminate with a comma.

   If you are using a local Git repository, avoid making this change via File Manager. Instead, commit these changes directly to the repository to prevent them from being overwritten during subsequent application deployments.

4. Click Laravel, navigate to the “Deployment” tab, and then click Deploy. This action will result in modifications to the composer.lock file. Commit these changes to your repository to ensure they are not overwritten during future deployments.
5. After committing the changes, click Deploy once more.
6. (Optional) Return to the domain card, click Databases, and then click Add Database.

   Note: If your Laravel application is already utilizing a MySQL/MariaDB database, you can use that existing database for queues. In this scenario, you can skip this step and the following step.

7. (Optional) Create a new MySQL or MariaDB database and a corresponding database user.
8. Return to the domain card, click Laravel, and then click the Edit button next to “Environment variables (.env).”
9. Add the following lines to the .env file, ensuring you replace the placeholders with the correct information for the database you intend to use (either the one just created or your existing Laravel database):

   DB_CONNECTION=mysql
   DB_HOST=<database server IP address or hostname>
   QUEUE_CONNECTION=database
   DB_DATABASE=<database name>
   DB_USERNAME=<database user name>
   DB_PASSWORD=<database user password>

   Then, click “Update.”
10. Put your Laravel application into maintenance mode.
11. Go to the “Artisan” tab, and then run the following commands, in the specified order:

    queue:table
    migrate

12. Go to the “Dashboard” tab, take your Laravel application out of maintenance mode, and then click the Queue toggle button so that it displays “Enabled.”

Queues are now successfully enabled for your Laravel application.

To optimize the queue worker process’s utilization of server resources, several settings can be configured within Plesk. These settings primarily govern the conditions under which the queue worker process may terminate, thereby releasing occupied memory.

Configuring the Queue Worker Process

1. Log in to your Plesk account, and then locate the domain hosting your application.
2. Click Laravel, and then navigate to the “Queue” tab.
3. (Optional) Select the “Stop Worker When Empty” checkbox to instruct the worker process to halt execution when there are no jobs pending in the queue. If enabled, the worker process will initiate every 60 seconds, process all current jobs in the queue, and then exit. If this checkbox is not selected, the worker process will continue to run even when the queue is empty.
4. (Optional) Define a custom “Timeout” value to configure the worker process to exit with an error if a job has been running for a duration exceeding the specified value. Ensure that the “Timeout” value is sufficiently long to allow for typical jobs generated by your Laravel application to complete processing. If a custom “Timeout” value is not set, the worker process will not exit, even if an individual job remains in the queue for an extended period (e.g., due to becoming stuck).

   Caution: Setting a “Timeout” value that is too low may lead to job failures due to insufficient processing time (for example, when uploading a large file). Should you experience failed jobs after setting a custom “Timeout” value, consider increasing it or reverting the parameter to its default value (“0,” which indicates no limit on job processing time).

5. (Optional) Set a custom “Max Jobs” value to configure the worker process to exit once it has processed a specific number of jobs. If a custom “Max Jobs” value is not set, the worker process will continue running indefinitely, even after processing a substantial number of jobs.
6. (Optional) Specify a custom “Max Time” value to configure the worker process to exit after it has been running for the designated number of seconds (note that the worker process will not exit while it is in the middle of processing a job). If a custom “Max Time” value is not set, the worker process will continue to run even if it has been active for a prolonged duration.

The queue worker process has now been configured and is optimized for more efficient utilization of server resources.

Jobs within the queue may fail for various reasons. Plesk diligently tracks these failed jobs, providing you with options to either restart them or dismiss them from the list.

Viewing, Restarting, and Dismissing Failed Jobs

1. Log in to your Plesk account, and then locate the domain hosting your application.
2. Click Laravel, navigate to the “Queue” tab, and then click Show failed jobs to view the list of jobs that have failed.
3. (Optional) Select one or more failed jobs, and then click Retry to attempt restarting them.
4. (Optional) Select one or more failed jobs, and then click Delete to remove them from the list.
5. (Optional) Click Flush to clear all failed jobs from the list.

Failed jobs have now been successfully restarted and/or dismissed as per your actions.