[vc_row][vc_column][vc_column_text]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.[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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.

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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.

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

 2.1 Creating the SSH key pair

ssh user@ipaddress
# enter password
cd ~/.ssh
ls

# if this directory exists and you have id_rsa and id_rsa.pub, then you can skip the key generation

# generating a new key pair
ssh-keygen -t rsa -b 4096
# press enter 3 times, no passphrase required
cd ~/.ssh
ls
# you should now see id_rsa and id_rsa.pub

 

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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.

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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

# to view and copy your public key do
cd ~/.ssh
cat id_rsa.pub

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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.

# go to /home/<user>
cd ~

# example: git@github.com:arianacosta/mysite.git
git clone git@github.com:<user>/<repo>.git

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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’

# go to the repo's directory (where composer.json is located)
cd ~/mysite

# run composer but skip the development packages
composer install --no-dev --prefer-dist

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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.

# edit the .env (if it doesn't exist just create it)
nano ~/mysite/.env

# Set the parameters, exit with CTRL+X, and Y to save.

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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

# go to the application directory
cd ~/mysite

# run the migrations
php artisan migrate

[/vc_column_text][/vc_column][/vc_row][vc_row css=”.vc_custom_1488583779784{margin-top: 40px !important;}”][vc_column][vc_column_text]

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.[/vc_column_text][vc_column_text]

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>

#Preventing Access to App Root
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

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

[/vc_column_text][/vc_column][/vc_row]