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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
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 |
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.
|
1 2 |
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_rsa |
2.2 Adding the key to GitHub
We need to tell GitHub to allow the server to access the repo.
- Go to your repository settings in GitHub.
- Go to Deploy Keys
- Paste the public key
|
1 2 3 |
# to view and copy your public key do cd ~/.ssh cat id_rsa.pub |
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.
|
1 2 3 4 5 |
# go to /home/<user> cd ~ # example: git@github.com:arianacosta/mysite.git git clone git@github.com:<user>/<repo>.git |
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’
|
1 2 3 4 5 |
# 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 |
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.
|
1 2 3 4 |
# 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. |
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’.
|
1 2 3 4 5 |
# go to the application directory cd ~/mysite # run the migrations php artisan migrate |
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.
- Go to the Addon section in cPanel
- Put the actual domain name: mysite.com
- Use any subdomain: mysite is fine
- Set the document root to: mysite/public
- 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>
|
1 2 3 4 5 |
#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.
- Install a new app in a different directory i.e. /home/<user>/mysecondsite
- Create a ‘stage’ subdomain and point its document root to /home/<user>/mysecondsite/public
- Access stage with http://stage.mysite.com