Laravel Toolkit

summary

Laravel Toolkit is a free Plesk extension you can use to simplify routine tasks related to hosting Laravel applications.

In this topic you will learn how to upload, configure, and run Laravel applications in Plesk. Note that this topic presumes that you already have your application ready, or are planning on creating one. This is not a guide on how to create Laravel applications.

Prerequisites

Before you can host Laravel applications, the free Laravel Toolkit extension must be installed on the Plesk server:

• If you are the Plesk administrator, install the extension from the Extensions Catalog.
• Otherwise, contact your hosting provider and ask them to install the extension for you.

Once the extension is installed, you are ready to begin. You will see the Laravel button in the Navigation Pane, and also in the “Create Website” drawer on the domain cards of all your domains.

Uploading Your Application

Before you can configure and run your application, you need to upload it to the Plesk server and register it in Laravel Toolkit. There are three ways of doing this:

• Create a Laravel skeleton. If your application is stored in a folder or a compressed file on your computer, or if you are looking to create your application from scratch, Laravel Toolkit can create the necessary directory structure, and also a local Git repository.
• Install from a remote Git repository. If your application is stored in a remote repository, you can deploy it to the Plesk server.
• Scan for an existing application. If you have already uploaded your application to Plesk, you can register your application in Laravel Toolkit by scanning for it.

Note

To be able to create a Laravel skeleton or to install from a remote Git repository, the free Git extension must be installed on the Plesk server.

Creating a Laravel skeleton:

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

Installing from a remote Git repository:

1. Log in to Plesk.
2. Go to Websites & Domains, find the domain that will host your application, and then click Create Website > Laravel.
3. Select “Install from remote repository”.
4. Type or paste the URL of the remote repository containing your application’s files.
5. If the remote repository requires authentication, add the public key you see on this page to the repository.
6. Click Install Application.

Scanning for an existing application:

1. Log in to Plesk.
2. Go to Websites & Domains, find the domain that will host your application, and then open the “Hosting & DNS” tab.
3. Click Hosting.
4. Change the “Document root” value to match the path to your application’s public directory (by default, /httpdocs/public), and then click Save.
5. Go back to the “Dashboard” tab, click Create Website > Laravel, click Cancel, and then click Scan.

Once you have uploaded or deployed your application’s files and your application has been registered in Laravel Toolkit, the Laravel button will appear on the card of the domain hosting your application.

You can now proceed to the next step.

Running Artisan, Composer, and Node.js Commands

To manage your Laravel application, you will likely need to run Artisan, Composer, and/or Node.js commands. Laravel Toolkit makes it easy to run them from the Plesk interface with no need for shell access.

If you are unsure whether you need to run any Artisan, Composer, and/or Node.js commands for your application to run properly, consult the person or organization that provided you with the application.

Note

To be able to run Node.js commands, the free Node.js extension must be installed on the Plesk server.

Running an Artisan, Composer, or Node.js command:

1. Log in to Plesk.

2. Go to Websites & Domains, find the domain hosting your application, and then click Laravel.

3. Go to the corresponding tab, type in the command you want to run or select one from the list, and then press the Enter key or click the button.

   Note

   When running Node.js commands, you may need to specify a particular Node.js version and/or package manager for the command to have the desired effect. If you are unsure what to choose, consult the person or organization that provided you with the application.

Viewing Your Application’s Log Files

As it runs, your Laravel application writes its log to a separate log file. You can see the contents of that file straight from the Laravel Toolkit interface to make monitoring your application and troubleshooting whatever issues that may come up easier.

Viewing your application’s log:

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

This will open the domain log browser showing only the log entries from the Laravel log.

Viewing Your Application’s Scheduled Tasks

With Laravel, you can schedule tasks inside the application’s code instead of using an external scheduler, such as cron. With Laravel Toolkit, you can see all currently configured scheduled tasks straight from the Laravel Toolkit interface, and also enable or disable Laravel scheduled tasks.

Note

You cannot add, remove, or edit Laravel scheduled tasks from the Laravel Toolkit interface. Learn how to schedule tasks inside the application’s code

Viewing your application’s scheduled tasks:

1. Log in to Plesk.
2. Go to Websites & Domains, find the domain hosting your application, and then click Laravel.
3. Go to the “Scheduled Tasks” tab (the tab is only visible when there is one or more scheduled tasks configured).

Note

To be able to enable or disable your application’s scheduled tasks, you need to perform a particular operation first, depending on whether you are running Plesk for Linux or Plesk for Windows. You need to do it for every domain hosting a Laravel application whose scheduled tasks you want to run.

Enabling scheduled tasks management:

1. Log in to Plesk.
2. Enable the “Scheduler management” permission (found on the “Permissions” tab) for the subscription to which the domain hosting your application belongs.
3. (Plesk for Linux) Go to Websites & Domains, find 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 enable or disable your application’s scheduled tasks.

Enabling your application’s scheduled tasks:

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

Scheduled tasks are now enabled for your Laravel application.

Editing the Environment Variables

Your application may need one or more custom environment variables to run properly, or it may change its behavior depending on the environment variables that have been set. If you are unsure whether your application needs any environment variables to run properly, consult the person or organization that provided you with the application.

Editing environment variables:

1. Log in to Plesk.
2. Go to Websites & Domains, find the domain hosting your application, and then click Laravel.
3. Click the Edit button next to “Environment variables (.env)”.
4. Edit the environment variables as necessary, and then click Update.

The updated environment variables are now in effect.

Putting Your Application in Maintenance Mode

To prevent website visitors from seeing errors while you are working on or updating your application, you can put it in maintenance mode. While your application is in maintenance mode, website visitors will see a page showing a “503 SERVICE UNAVAILABLE” error.

Putting your application in maintenance mode:

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

Your Laravel application is now in maintenance mode.

Note

Do not forget to take your application out of maintenance mode once you have finished working on or updating it.

Updating Your Application

Whether your Laravel application’s files are stored in a local or a remote Git repository, you need to make sure that the changes made to the application’s code are propagated to the Plesk server. You can choose between deploying the changes manually or automatically.

If you need precise control over when your application is updated, we recommend updating it manually. This way, no changes made to the application’s code in the repository are propagated to the Plesk server until you are ready to do so. The downside of this approach is that you must perform manual actions every time the application needs to be updated.

Updating your application manually:

1. Log in to Plesk.
2. Go to Websites & Domains, find 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 the steps you do not want to run during deployment, and then click Deploy.

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

If you want the changes made to the application’s code to be automatically propagated to the Plesk server, the method differs depending 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 Plesk.
2. Go to Websites & Domains, find 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 the steps you do not want to run during deployment.

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

Updating your application automatically (remote repository):

1. Log in to Plesk.
2. Go to Websites & Domains, find the domain hosting your application, and then click Laravel.
3. Copy the webhook URL you see here, and then add it to the remote repository. For specific instructions, see your repository provider’s documentation.
4. Go to the “Deployment” tab and under “Deployment mode” select the “Automatic” radio button.
5. Under “Deployment scenario”, clear the checkboxes corresponding to the steps you do not want to run during deployment.

Now, every time the event triggering the webhook takes place in the remote repository storing the application’s code, your application and its dependencies will be updated.

Configuring a Deployment Script

Your application may require certain commands to be run on the server during deployment to run properly. To avoid running the commands manually, you can configure a deployment script that will be run every time the application is updated.

If you are unsure whether your application needs any commands to be run during deployment to run properly, consult the person or organization that provided you with the application.

Note

In Plesk for Linux, you need to enable SSH access before you can edit the deployment script from the Laravel Toolkit interface. You only need to do it once.

(Plesk for Linux) Enabling the ability to edit the deployment script:

1. Log in to Plesk.
2. Go to Websites & Domains, find 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 can now edit the deployment script from the Laravel Toolkit interface.

Editing the deployment script:

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

The deployment script is now in effect and will be run every time you update your application.

Managing Queues

Queues in Laravel make it possible to process time-consuming tasks, such as parsing an uploaded file, asynchronously in the background. If your application supports queues, you can enable them in Plesk to configure the queue worker process.

To use queues, you need to enable them for your subscription, and also to create a database for the queue worker to use. This is a one time procedure.

Laravel queues can use a variety of queue backends. However, in this guide we will only cover using a MySQL/MariaDB database as backend. This is the simplest way to enable queues in Plesk, and it should be sufficient for most users. Other backends may provide advantages, such as improved access times, but they require expertise to implement and maintain, and may also incur additional costs.

Enabling queues:

1. Log in to Plesk, and then locate the domain hosting your application.

2. Enable scheduled tasks for your application. This is necessary for queues to function.

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

   In each section of the composer.json file, every line except the last one must end with a comma.

   If you use a local Git repository, do not make this change via File Manager. Instead, commit changes to the repository. This is to avoid the changes being overwritten the next time you deploy your application.

4. Click Laravel, go to the “Deployment” tab, and then click Deploy. This will result in changes being made to the contents of the composer.lock file. Commit those changes to the repository to avoid the changes being overwritten the next time you deploy your application.

5. After committing the changes, click Deploy once again.

6. (Optional) Return to the domain card, click Databases, and then click Add Database.

   Note

   If your Laravel application is already using a MySQL/MariaDB database, you can use that database to enable queues. In that case, skip this step, and also the following step.

7. (Optional) Create a MySQL or MariaDB database, and a 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, replacing the placeholders with the information about the database you want to use (either the one just created, or the one already being used by your Laravel application):

   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>
   

   and then click “Update”.

10. Put your Laravel application into maintenance mode.

11. Go to the “Artisan” tab, and then run the following commands, in this 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 shows “Enabled”.

Queues are now enabled for your Laravel application.

To make the queue worker process use server resources more efficiently, there is a number of settings you can configure in Plesk. They mostly deal with conditions under which the queue worker process may exit, freeing the memory it has been using.

Configuring the queue worker process:

1. Log in to Plesk, and then locate the domain hosting your application.

2. Click Laravel, and then go to the “Queue” tab.

3. (Optional) Select the “Stop Worker When Empty” checkbox to configure the worker process to stop when there are no jobs in the queue. If you do, the worker process will start every 60 seconds, process all jobs currently in the queue, and then exit.

   If you do not select the “Stop Worker When Empty” checkbox, the worker process will remain running even when there are no jobs in the queue.

4. (Optional) Set a custom “Timeout” value to configure the worker process to exit with an error if job has been running for a length of time exceeding the configured value. Make sure that the “Timeout” value allows enough time for a typical job created by your Laravel application to finish.

   If you do not set a custom “Timeout” value, the worker process will not exit even if an individual job has been in the queue being processed for a long time (for example, because the job has become stuck).

   Caution

   Setting too low a value may result in jobs failing because of insufficient time to process (for example, when uploading a large file). If you start experiencing failed jobs after setting a custom “Timeout” value, consider increasing it or returning the parameter to its default value (“0”, indicating 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 certain number of jobs.

   If you do not set a custom “Max Jobs” value, the worker process will not stop, even if it has processed a large number of jobs.

6. (Optional) Set a custom “Max Time” value to configure the worker process to exit once it has been running for the specified number of seconds (the worker process will not exit while in the middle of processing a job).

   If you do not set a custom “Max Time” value, the worker process will keep running even if it has been running for a long time.

The queue worker process has been configured and should now use server resources more efficiently.

Jobs may fail due to many reasons. Plesk keeps track of failed jobs, which you can restart or dismiss.

Viewing, restarting, and dismissing failed jobs:

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

Failed jobs have now been restarted and/or dismissed.