Installing Laravel on cPanel

Creating and running a Laravel application is a snap, but installing it on production servers may be overwhelming for first comers. In this tutorial, we will cover how to deploy a Laravel application from GitHub into cPanel. Before starting make sure you have:

  • cPanel account with SSH access
  • Composer installed
  • MySQL database (optional)
  • Domain name
  • Laravel repository in GitHub (or similar)

Tested on CentOS 7.3, WHM v62, Laravel 5.

1. Setting the helper domain

Although this sounds counter-intuitive, the actual domain will be set later as an add-on domain, not as the primary one. The problem is that cPanel requires a domain to create an account. You may use any fake domain, but I recommend using a fake domain TLD instead of the .com like .laravel (this will help you keep things organized).

Create a cPanel account with a fake domain like ‘mysite.laravel’ instead of ‘mysite.com’.

Note this step is only to be able to create a cPanel account without the actual domain.

2. Accessing Repository on GitHub from the Server

You will need to create an SSH key pair, register the public key as a deploy key on GitHub, add it to the agent and finally clone the repo.

 2.1 Creating the SSH key pair

 

2.2 Adding the SSH key to the Agent

In order for the key to be recognized by the system, it need to be registered with the SSH agent.

2.2 Adding the key to GitHub

We need to tell GitHub to allow the server to access the repo.

  1. Go to your repository settings in GitHub.
  2. Go to Deploy Keys
  3. Paste the public key

3. Cloning the Repository

We will now clone the repo in the user’s home

Do NOT put the repo inside public_html, this is insecure because it makes the code and the settings public.

4. Installing Composer Dependencies

The first time the application is installed, it is necessary to download all its dependencies.

Use ‘composer install’ only the first time, for subsequent deployments use ‘composer update’

5. Setting up the Environment

As you may already know, Laravel’s environment file ‘.env’ is not under version control. Therefore it has to be configured manually. Luckily, by default, composer.json has an instruction that copies the ‘.env.example’ to the ‘.env’ so all you have to do is set up the parameters.

It is a good practice to keep the .env.example with all parameters but with not with actual keys or passwords.

6. Running Database Migrations

If your project uses a database, you will need to run the migrations to set up the tables. Make sure that the db user has the privileges to access the database (this is done in cPanel) and remember to put the database connection information in the ‘.env’.

7. Pointing the Domain to the Public Directory

In the first step, we used a fake domain to create the cPanel account. This allows us to put the actual domain as an Addon which can have a custom document root.

The document root should always be the application’s public directory.

  1. Go to the Addon section in cPanel
  2. Put the actual domain name: mysite.com
  3. Use any subdomain: mysite is fine
  4. Set the document root to: mysite/public
  5. Test the site on your browser

Congratulations! You have installed a Laravel application on cPanel.

If you see this error:

Sorry, the domain is already pointed to an IP address that does not appear to use DNS servers associated with this server.

Make sure that the name servers are pointing to this server. You cannot add an Addon domain that you do not own.

8. Additional Methods and Troubleshooting

8.1 Using public_html (NOT recommended)

If for some reason you still need to install the application on public_html, it is possible. However, it is extremely important that you create a .htacess file to redirect anyone that tries to access the app root to the public directory.

Be aware that the files on public_html can be seen with http://<ip or domain>/~<user>

8.2 Staging Site (Multiple Apps)

You may add as many sites as you want with different domains or subdomains. This is particularly useful for creating a staging site.

  1. Install a new app in a different directory i.e. /home/<user>/mysecondsite
  2. Create a ‘stage’ subdomain and point its document root to /home/<user>/mysecondsite/public
  3. Access stage with http://stage.mysite.com

Share Post :