└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # How to deploy Laravel applications on shared hosting 2 | [![API Documentation](http://img.shields.io/badge/en-English-brightgreen.svg)](README.md) 3 | 4 | The simple guide to deploy Laravel and Lumen application on shared hosting. 5 | 6 | ## Requirements 7 | 8 | Before trying to deploy a Laravel application on a shared hosting, you need to make sure that the hosting services provide a fit [requirement to Laravel](https://laravel.com/docs/5.2#server-requirements). Basically, following items are required for Laravel 8.x: 9 | 10 | * PHP >= 7.4 11 | * PDO PHP Extension 12 | * Mbstring PHP Extension 13 | 14 | Well, it also depends on the Laravel version you want to try to install, checkout the appropriate version of [Laravel server requirements documentation](https://laravel.com/docs/master). 15 | 16 | Besides PHP and those required extensions, you also need these utilities to make the deployment much easier. 17 | 18 | * [Git](https://git-scm.com/) 19 | * [Composer](https://getcomposer.org/) 20 | 21 | **Next, if you are cloning a privately-hosted remote repository, you need to have the SSH access permission for your hosting account; otherwise, you are good if it is a public repo.** 22 | 23 | ## Set up access to private repositories 24 | To set up access to private repositories, perform the following steps: 25 | 26 | ### Generate an SSH key 27 | If you have not already configured one, run the following command to generate an SSH key: 28 | 29 | ```ssh-keygen -t rsa -b 4096 -C "username@example.foo"``` 30 | 31 | In this example, `username` represents the cPanel account username and `example.foo` represents your domain name. 32 | 33 | After you run this command, the system will prompt you to enter a passphrase. Do not enter a passphrase, and press Enter to continue. 34 | 35 | ### Confirm that you generated the SSH key correctly 36 | To confirm that the key exists and is in the correct location, run the following command: 37 | 38 | ```cat ~/.ssh/id_rsa.pub``` 39 | 40 | The output should resemble the following example, where AAAAB3Nza... represents a valid SSH key: 41 | 42 | ```ssh-rsa AAAAB3Nza...``` 43 | 44 | ### Register your SSH key with the private repository host 45 | Note: 46 | > For information about how to register your SSH key with another private repository host, consult that host’s website or documentation. Some repository hosts, such as Bitbucket, do not allow you to configure write access for your access keys. 47 | To register an SSH key with GitHub, perform the following steps: 48 | 49 | 1. Log in to your GitHub account. 50 | 51 | 2. Navigate to your private repository. 52 | 53 | 3. In the top right corner of the page, click *Settings*. A new page will appear. 54 | 55 | 4. In the left side menu, click *Deploy keys*. A new page will appear. 56 | 57 | 5. In the top right corner of the page, click *Add deploy key*. A new page will appear. 58 | 59 | 6. In the *Title* text box, enter a display name for the key. I personally use the domain name. 60 | 61 | 7. In the *Key* text box, paste the entire SSH key. 62 | 63 | 8. If you want to push code from your cPanel account to your GitHub account, select the *Allow write* access checkbox. 64 | 65 | Note: 66 | > If you do not select this checkbox, you can only deploy changes from your GitHub repository to the cPanel-hosted repository. 67 | 68 | 9. Click *Add* key. 69 | 70 | ### Test the SSH key 71 | To test your SSH key, run the following command, where `example.foo` represents the private repository’s host: 72 | 73 | ```ssh -T git@example.foo``` 74 | 75 | I guess that's enough for SSH. Please refer to below sections to learn more about deployment. 76 | 77 | ## Clone the repository 78 | 79 | Let's get started by understanding how we should organize the Laravel application structure. At first, you will have this or similar directories and files in your account, 80 | 81 | ```bash 82 | .bash_history 83 | .bash_logout 84 | .bash_profile 85 | .bashrc 86 | .cache 87 | .cpanel 88 | .htpasswds 89 | logs 90 | mail 91 | public_ftp 92 | public_html 93 | .ssh 94 | tmp 95 | etc 96 | www -> public_html 97 | ... 98 | ``` 99 | 100 | For the main account which is tied with the main domain, the front-end code should stay in `public_html` or `www`. Since, we don't want to expose *Laravel things* (such as, .env, ...) to the outside world, we will hide them. 101 | There are two methods of cloning the repository. You can either clone through the terminal or use a wizard that comes with cpanel. Most people are not aware about the second method. 102 | 103 | ### (a) Clone through the Terminal 104 | Create a new directory to store all the code, name it `repositories` or whatever you want to. 105 | 106 | ```bash 107 | $ mkdir repositories 108 | $ cd repositories 109 | ``` 110 | 111 | Alright, from here, just issue a git command to grab the code, 112 | 113 | ```bash 114 | $ git clone http://[GIT_SERVER]/awesome-app.git 115 | $ cd awesome-app 116 | ``` 117 | 118 | ### (a) Clone through Git™ Version Control Wizard 119 | - Search `git` in your cPanel home. 120 | - Click the *Create* button located on the top right. 121 | - Enter the clone URL for the remote repository in the respective text field. 122 | - The rest of the fields should now be autofilled for you automatically. You can change the naming as you desire. 123 | - Now click *Create* and the wizard will start cloning your repository if SSH Setup was done correctly. 124 | 125 | ## Configure 126 | Next step is to make the `awesome-app/public` directory to map with `www` directory, symbol link is a great help for this, but we need to backup `public` directory first. 127 | 128 | ```bash 129 | $ mv public public_bak 130 | $ ln -s ~/www public 131 | $ cp -a public_bak/* public/ 132 | $ cp public_bak/.htaccess public/ 133 | ``` 134 | 135 | Because we created the symbol link from `www` directory to make it become the *virtual* `public` in project, so we have to update the `~/www/index.php` in order to replace paths with the new ones: 136 | 137 | ```diff 138 | - require __DIR__.’/../bootstrap/autoload.php’; 139 | + require __DIR__.'/../repositories/awesome-app/bootstrap/autoload.php'; 140 | 141 | - $app = require_once __DIR__.’/../bootstrap/app.php’; 142 | + $app = require_once __DIR__.'/../repositories/awesome-app/bootstrap/app.php'; 143 | ``` 144 | 145 | The updated file should be: 146 | 147 | ```php 148 | require __DIR__.'/../repositories/awesome-app/bootstrap/autoload.php'; 149 | 150 | $app = require_once __DIR__.'/../repositories/awesome-app/bootstrap/app.php'; 151 | ``` 152 | 153 | The hard part is done, the rest is to do some basic Laravel setup. Allow write permission to `storage` directory is important, 154 | 155 | ```bash 156 | $ chmod -R o+w storage 157 | ``` 158 | 159 | **Edit your `.env` for proper configuration. Don't miss this!** 160 | 161 | Lastly, update the required packages for Laravel project using **composer** and add some necessary caches, 162 | 163 | ```bash 164 | $ php composer install 165 | $ php composer dumpautoload -o 166 | $ php artisan config:cache 167 | $ php artisan route:cache 168 | ``` 169 | 170 | **Congratulation! You've successfully set up a Laravel application on a shared hosting service.** 171 | 172 | ## FAQs 173 | 174 | > **1. How to acquire SSH access permission for my account?** 175 | 176 | Just contact your hosting support, they will need to confirm your identity and will permit your SSH access in no time. 177 | 178 | > **2. Where is git? I can't find it.** 179 | 180 | `git` is often put under this place in CPanel hosting services, `/usr/local/cpanel/3rdparty/bin/git`. So you need to provide full path to `git` if you want to issue a `git` command; or, you can also create an alias for convenient use, 181 | 182 | ```bash 183 | alias git="/usr/local/cpanel/3rdparty/bin/git" 184 | ``` 185 | 186 | > **3. How to get composer?** 187 | 188 | You can use FTP or SCP command to upload `composer.phar` to the host after downloading it locally. Or use `wget` and `curl` to get the file directly on host, 189 | 190 | ```bash 191 | $ wget https://getcomposer.org/composer.phar 192 | 193 | or 194 | 195 | $ curl -sS https://getcomposer.org/installer | php — –filename=composer 196 | ``` 197 | 198 | > **4. Does this work with Lumen?** 199 | 200 | Well, Laravel and Lumen are like twins, so it applies the same with Lumen. 201 | 202 | > **5. I try to run `composer` but it shows nothing. What is the problem?** 203 | 204 | You need to provide a proper PHP configuration to run `composer`, which means, you cannot execute `composer` directly on some hosting service providers. So to execute `composer`, you will need to issue this command, 205 | 206 | ```bash 207 | $ php -c php.ini composer [COMMAND] 208 | ``` 209 | 210 | > **6. Where can I get the `php.ini` to load for `composer`?** 211 | 212 | You can copy the default PHP configuration file `php.ini`, which is often at `/usr/local/lib/php.ini`, or find it by this command, 213 | 214 | ```bash 215 | $ php -i | grep "php.ini" 216 | ``` 217 | 218 | ## List of service providers tested and worked 219 | 220 | The following shared hosting service providers have been tested and worked perfectly 100%. 221 | 222 | * [NameCheap](https://www.namecheap.com/) 223 | * [JustHost](https://www.justhost.com/) 224 | * [bluehost](https://www.bluehost.com/) 225 | * [GoDaddy](https://godaddy.com/) 226 | * [HostGator](http://www.hostgator.com/) 227 | * [GeekStorage](https://www.geekstorage.com/) 228 | * [Site5](https://www.site5.com/) 229 | 230 | Works on [GeekStorage](https://www.geekstorage.com/) shared plan but I had to enable PHP 7.4 via `.htaccess` 231 | 232 | ``` 233 | AddHandler application/x-httpd-php74 .php 234 | ``` 235 | 236 | If you found any hosting providers that works, please tell me, I will update the list for others to know about them, too. 237 | 238 | ## Still trouble? 239 | 240 | If you still fail to deploy Laravel applications after following all above steps. Provide me [your issue](https://github.com/michaelgatuma/laravel-deploy-on-shared-hosting/issues) in details, I will help you out. 241 | 242 | ## Contribution Guide 243 | 244 | Free free to fork the project and submit [a pull request](https://github.com/michaelgatuma/laravel-deploy-on-shared-hosting/pulls). 245 | --------------------------------------------------------------------------------