Forem: Kenean

Automate your Laravel app deployment with Github Actions

Kenean — Fri, 10 Dec 2021 21:56:35 +0000

Hello again my fellow artisans!!

In this article, I will go through the step-by-step process of how you can automate your Laravel app deployment on a VPS, for free of course.

Setting the scene...

I am a part of a small team working on a Laravel project which is deployed on a VPS. Each of our team members will work on a particular task and when it's ready for production there is always a need for someone access to the server to deploy each change that is being pushed to our GitHub repo.

This become a very repetitive and unpleasant task for all of us and a solution was needed within our scale and budget, that's when we turned to the mighty Github Actions to automate our workflows.

Let's dive into the simplified version of our workflow setup guide.

Assumptions

In this guide, I assume you have the followings points in check.

You have a configured Linux server that is capable of running a Laravel application and Git is installed on it.
You have a Laravel application Github repository. If you don't have one you can follow the first 2 sections on my previous post here free-serverless-laravel-deployment.

How it works

On typical workflow a developer will create a new branch for a given task and make a pull request to the main/master branch or make the changes on the main/master branch it self (not advisable) and do a push.

Both pull request and push are events on a given branch we can subscribe to with Github Actions. Therefor we can define a set of instructions that should be carried out when ever the given events happen on our repository. These instructions might be running our Tests, Builds, and Deployments.

Create deployment script

The first thing we will do is create a deployment script that will contain all the necessary commands to deploy and run our application.

In the root directory of your application create a folder called .scripts.

Inside the .scripts directory create a file called deploy.sh with the following content.

Refer to comments on the scripts to know what we are doing on each line.

Create a workflow

A Github action workflow is a set of instructions that consists different jobs and steps that can be triggered on events we mentioned above.

Workflows for a repository are stored inside .github/workflows in the root directory of your applications.

create a file called deploy.yml inside .github/workflows folder with the following content.

Commit the newly created files

Now we have created all the necessary files for our automation let's commit them with the following commands.



$ git add deploy.sh deploy.yml 
$ git commit -m "Deployment automation"

Create deployment branch and push to Github

If you notice on our deploy.sh and deploy.yml files we have referred to a branch called production. we will use this branch to add commits that are production-ready with a push or pull request.

Create this branch for your repository with the following git command and push them to GitHub.



$ git checkout -b production 
$ git push -u origin production

Setting up ssh key

It's time to set up the connection between our server and Github's.

To do this we first need to generate a new ssh key pair on our server.

Run this command on your server to generate the ssh keys.



$ ssh-keygen -t rsa -b 4096 -C "email@example.com"

When prompt to enter a file name and passphrase, just press enter and accept the defaults.

This will create 2 ssh keys, public and private inside your home directory .ssh/ folder.

And now add your newly generated ssh private key to the ssh-agent with the following commands.



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

And let's add our public key to the authorized_keys file on our server with the following command.



$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

Copying ssh keys to Github

Our above setup will allow:-

1. Github Actions to authenticate itself to our server and run our deploy.sh script.

For this to work, we have to let Github know how to authenticate to our server.

As we prepared our ssh key above will provide it to GitHub alongside the server HOST, the ssh PORT, the ssh private KEY, and the USERNAME of our server.

To do this go to your Github account on your browser and open your repository.

Click on setting like shown below

And on the sidebar menu click on secrets

On the Action Secret page, click on add a new repository secret.

On the new secret page, add the following keys one by one.

`HOST`

The HOST secret is your server IP address, put in the HOST keyword in the name field and your server IP address in the value field.

`PORT`

The PORT secret is your ssh port. use the PORT keyword in the name and 22 in the value to use the default ssh port.

`SSHKEY`

The SSHKEY secret is the private ssh key we generated on our server. normally you wouldn't share your private ssh key with anyone but since we are doing automation it's required.

Use the SSHKEY keyword for the name field.

To copy your private key value go to your server and run the following command.



$ cat ~/.ssh/id_rsa

This will print your private ssh key on your terminal, copy it and past it inside the value field.

`USERNAME`

The last secret would be the USERNAME you want to authenticate with.

To get this you can run whoami on your server and get the value. Then use the USERNAME keyword for the name field and past in the value.

when you are done you should have your secrets looking something like this

2. Our server to authenticate to Github and fetch the latest commits on our repository.

In order to Github allow access to our server we have to provide the ssh public key we generated earlier.

if we have multiple repositories we can provide the public key at the account level, but if it is just one repository we can provide it in the repository and allow access only to that one repository on our account.

To do that go to your repository settings again and click on Deploy keys

Add deploy keys..

Give it a title that helps you remember the server, like PROD_SERVER.

And for the key field value go to your server and print your public key with the following command and copy it.



$ cat ~/.ssh/id_rsa.pub

Don't check to allow write access and just click on add key button.

The last thing would be to change our remote origin on our server to use SSH instead of HTTPS and do a fetch to get the new commits on the server

To do that go to your Github repository and click on the code button and copy the link on the ssh tab.

Then on your server go to your deployed application directory, most commonly inside /var/html/www and run the following command.



git remote set-url origin git@github.com:USERNAME/REPOSITORY.git
git fetch

replace the URL with the one you copied.

Give your deploy.sh script execution permission



sudo chmod +x ./REPOSITORY/.scripts/deploy.sh

There you have it, my friends, you have now a Laravel application deployment automation. create a test commit and push it to your production branch to see the magic happen.

You can go crazy with it by adding in more workflows for your test builds, staging environments, etc…

Free Serverless Laravel Deployment

Kenean — Sat, 09 Oct 2021 12:54:17 +0000

If you have a small Laravel application and you don't want to go through the trouble of setting your own VPS or something like Laravel Vapor you might want to read this one through.

So in this ride we will see how we can set up and deploy our Laravel application on a serverless environment called Vercel, including automated deployments and previews with out any cost.

At this point you are probably thinking this sound too good to be true. Well... you are right, there are of course some gotchas.

The primary thing is you have to find other ways to host and manage your database and other services your application need.

And this set up would not be a replacement for the more robust deployment strategies on AWS and Laravel Vapor.

Now we got that out of the way, Lets dig in!

Creating a Laravel application

If you already have a project you can skip this step. I will go ahead and create a new one using composer for the sake of clarity.

We will call our app laravel-vercel

Open your terminal and run:
composer create-project laravel/laravel laravel-vercel

Initialize a Git repository and push to Github

After the application is created, we will need to go into the root directory and set up Git and push our code to Github.

Run these commands to set up a Git repository:
cd laravel-vercel
git init
git add .
git commit -m "init"

Now lets create a new repository on Github and push our application.

Go to the Github repository creation page here and create a repository called laravel-vercel.

After we create our repository we will see a page similar to the following image.

Copy and run the commands highlighted in the image from your newly create Github repository page.

Create Vercel configuration files

So for this magic to happen we have to create 2 Vercel configuration files in our application.

`app/index.php`

Create a php file called index.php within a folder called api in your application root directory.
And then add the following content to it.



<?php
require __DIR__ . '/../public/index.php';

The default entry point for the serverless function on vercel is the app directory. the above script will make sure the request is forwarded to our Laravel app entry point public/index.php.

`vercel.json`

Create a new file again called vercel.json in the root directory. This file will be responsible for setting up our Vercel configurations. This is where the real magic happens.

Add the following content to your file and we will go through them in details.



{
    "version": 2,
    "functions": {
        "api/index.php": { "runtime": "vercel-php@0.3.1" }
    },
    "routes": [
        {
            "src": "/(.*)",
            "dest": "/api/index.php"
        }
    ],
    "env": {
        "APP_NAME": "Laravel Vercel",
        "APP_ENV": "production",
        "APP_DEBUG": "false",
        "APP_URL": "https://laravel-vercel.vercel.app",

        "APP_CONFIG_CACHE": "/tmp/config.php",
        "APP_EVENTS_CACHE": "/tmp/events.php",
        "APP_PACKAGES_CACHE": "/tmp/packages.php",
        "APP_ROUTES_CACHE": "/tmp/routes.php",
        "APP_SERVICES_CACHE": "/tmp/services.php",
        "VIEW_COMPILED_PATH": "/tmp",
        "CACHE_DRIVER": "array",
        "LOG_CHANNEL": "stderr",
        "SESSION_DRIVER": "cookie",
        "VIEW_COMPILED_PATH": "/tmp/views",
        "SSR_TEMP_PATH": "/tmp/ssr",
        "NODE_PATH": "node"
    }
}

version



"version": 2, 
//This make sure to run our code on Vercel version 2

functions



"functions": {
    "api/index.php": { "runtime": "vercel-php@0.3.1" }
},

The api/index.php key will define our app entry point which will be forwarded to the Laravel app entry point public/index.php

"runtime": "vercel-php@0.3.1" will define our PHP runtime, which is basically a module that transform our code into Serverless Functions for Vercel.

In this set up we are using the community runtime for PHP called vercel-php.

routes



"routes": [
   {
      "src": "/(.*)",
      "dest": "/api/index.php"
   }
],

The routes will tell Vercel to forward all URIs to our application serverless function.

env



"env": {
        "APP_NAME": "Laravel Vercel",
        "APP_ENV": "production",
        "APP_DEBUG": "false",
        "APP_URL": "https://laravel-vercel.vercel.app",

        "APP_CONFIG_CACHE": "/tmp/config.php",
        "APP_EVENTS_CACHE": "/tmp/events.php",
        "APP_PACKAGES_CACHE": "/tmp/packages.php",
        "APP_ROUTES_CACHE": "/tmp/routes.php",
        "APP_SERVICES_CACHE": "/tmp/services.php",
        "VIEW_COMPILED_PATH": "/tmp",
        "CACHE_DRIVER": "array",
        "LOG_CHANNEL": "stderr",
        "SESSION_DRIVER": "cookie",
        "VIEW_COMPILED_PATH": "/tmp/views",
        "SSR_TEMP_PATH": "/tmp/ssr",
        "NODE_PATH": "node"
    }

As you already probably guessed this is going to be our application environment variable section. you can pass environment variables you have on your Laravel app .env.

NOTICE! do not pass sensitive environment values like APP_KEY and database config values since they will be tracked by git and would be visible on your repo. We later will see how we can pass those values in more secure way.

Some of the unusual variables are Laravel's default values that we don't normally see in the our env file. we have to pass them here since serverless applications are state-less and the only folder we can reliably modify at run-time is Vercel’s tmp folder.

Commit and push Changes to Github

lets push our newly created file to our Github repo

git add .
git commit -m "add Vercel configs"
git push orgin Main

Link our repository to Vercel

Create your free account on Vercel using your Github account.

Once you are done, on your Vercel Dashboard you will see a button called New Project, something similar this the following image.

When you click on it you see the creation page and your Github repositories listed, on a much similar page like the following.

Click Import on your laravel-vercel repository (or what ever you named yours).

If you are not seeing your repositories listed, click on the Adjust GitHub App Permissions link and set up the permissions there.

Once you click on import you will see the following like page

You can click on skip for the Create a Team section and go to the Configure Project section.

On the Environment Variable section, we will add our sensitive Laravel app env variables.
These are:
APP_KEY
DB_CONNECTION
DB_HOST
DB_PORT
DB_DATABASE
DB_USERNAME
DB_PASSWORD

Finally, click on Deploy and sit back to see the magic happen.

Your application will get built and deployed on Vercel. and you will see the following success page with a Vercel domain name to your application.

Now if you have new changes to be deployed all you have to do is commit and push your changes to your Github repository Main branch and it will automatically get built and deployed to your server, how cool is that!

If you want to change the domain name to your app you can go to the settings tab on Vercel and there is a whole page to set up and manage your domain.

Peace out ✌️