Cpanel Git: Part 1 - Deploying the React App

This is my first post here.

I'm going to explain how to deploy a React App on a Cpanel Shared Hosting using Git. Ensure you have git and nodejs setup.

Scaffolding a new react app

1. You can use your preferred package manager e.g yarn, pnpm or using npx.

pnpm create vite@latest example-react-app

Read about vitejs at: https://vitejs.dev/guide/

1. Choose a framework
   

2. Choose a variant
   

3. Follow the remaining prompts
   

Initiate a git repository

Inside our newly scaffolded react app we are going to run the following commands
git init
git add .
git commit -m "Initial Project"

Creating a github repository

Head over to github.com and create a new repository. You can decide to create a private repository. For the purpose of this tutorial I will call it cpanel-react-example

Pushing to github

Since we have already initiated our github repository we are going to push our existing one. Now inside the react app we scaffolded earlier we will follow the github commands.

With that done, our github repository should look like this.

Adding the build action

We are going to create a new file .github/workflows/build.yml

If you don't understand this, inside your newly scaffolded app you will need to create a folder .github then create a folder workflows inside it. Finally you will create a file build.yml inside the workflows folder.

Edit the build.yml.

name: React App build workflow
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-20.04
    strategy:
      matrix:
        node-version: [15]
    steps:
    - uses: actions/checkout@v3
    - uses: pnpm/action-setup@v2.2.4
      with:
        version: 7
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'pnpm'
    - name: Install dependencies
      run: pnpm install
    - name: Build
      run: pnpm run build
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

What the script does is to build our react app and deploy it to the gh-pages branch whenever we push to the main branch. You can read more about github actions at https://docs.github.com/en/actions

We will commit our changes and push to github
git add .
git commit -m "Added github action"
git push

Once pushed we will have a new branch called gh-pages containing our deploy

Deploying to hosting

To deploy to your shared hosting you will need two items:

1. A .cpanel.yml file - Read more at https://docs.cpanel.net/knowledge-base/web-services/guide-to-git-deployment/
2. Deploy keys

Creating .cpanel.yml

The .cpanel.yml file is like the github action script but for cpanel. It contains the instructions on how to deploy the react app.

Navigate to the public folder of your react-app and create three new files
.cpanel.yml
.deploy.example.sh
.gitignore

We will edit our files using the content of this github gist: https://gist.github.com/sadiqsalau/c1b0f0e4b15e40274b64854c6c557e24

.cpanel.yml

This file is required for any cpanel deployment. It contains all command to deploy the react app. .cpanel.yml file can be destructive so make sure you take a look at it especially the parts that make use of the command rm -rf. Edit it to suit your deployment.

.deploy.example.sh

This file is an example of .deploy.sh. Treat it like a .env.example file

.deploy.sh

Based on the .cpanel.yml in that gist, this will automatically be created on your shared hosting when you run your first deployment. Treat it like a .env that exports variables that define the path where your react app will be deployed to on your hosting. Once created you should edit it before your next deployment.

.gitignore

Our .gitignore file will exclude .deploy.sh from being tracked by git.

With all three files setup, it's time to commit them. So we will run:
git add .
git commit -m "Added cpanel deploy script"
git push

Generating deploy keys

Open a new terminal and run
ssh-keygen -t ecdsa-sha2-nistp256 -C "your_email@example.com"
Note: Some shared hosting can't clone a repository using a key with password so when prompted to enter a password just press enter.

Also take note of where the generated keys are stored

We are going to rename our keys, for this tutorial they will be renamed to cpanel_react_example

Adding github deploy keys

Now go to your github repository, navigate to Settings > Security > Deploy Keys and add a new deploy key.

Give your key a title e.g Deploy key, for the key field copy the content of your public key (id_ecdsa.pub which we renamed to cpanel_react_example.pub). You can open the public key with a text editor or run the command cat key_name.pub with key_name being the name of your key.

As an example it should look like this

Finally add the deploy key.

Deploying to Cpanel

Login to Cpanel

Navigate to file manager

Creating .ssh folder

Click settings, enable hidden files and create a new folder named .ssh if it doesn't exist

Upload deploy keys

Open .ssh folder and upload your deploy keys

Change private key permission

Right click and change the permission of your private key to 0600

Create .ssh config

Still within our .ssh folder create a new file named config

Edit .ssh config

Edit replacing example-1 with your github repository name and example_1 with your ssh key name.

Host example-1.github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/example_1
  IdentitiesOnly yes

Once done return to cpanel dashboard

Creating a new cpanel repository

Navigate to Git Version Control

The Clone URL will have this format
git@example-repo.github.com:example-user/example-repo.git

The other fields should be filled automatically

Take note of the path to your repository.

Switching-checked out branch

Click on the manage button

Change the checked-out branch to gh-pages

Running first deployment

Switch to the Pull or Deploy tab

Before we deploy, let's open our repository in the file manager to see its contents

If you take a look at the files listed, you should notice that there is no .deploy.sh which we mentioned earlier. It will be created once we run our first deployment.
Let's return to the repository and deploy

Once it has been deployed a new file .deploy.sh will be created. It should be edited if you aren't deploying to the root of your site (usually the public_html folder).

Running the second deployment

Now return and run deploy once more.

Once deployed, navigate to the path where you specified in .deploy.sh, you should see the react app.

Visit the url of your site to see your live app..

Now whenever you make changes to your app and push to github just go to your repository, pull then deploy.

A working example can be found at: https://github.com/sadiqsalau/cpanel-react-example

The next part is using laravel as the API..