How to Deploy a Laravel App With the Debian 11 Vagrant Box

This article will serve as a guide for deploying a sample laravel app using the Debian 11 vagrant box. The vagrant box can be used as a testing ground before deploying your app to the cloud using a cloud provider such as AWS for your consumers to access the app you built.

To get started, you will have to install vagrant on your local machine. If you are new to vagrant, you can check out this article on how to set one up.

Once you’ve got your machine running, it’s time to install important packages and dependencies that are needed to get the app running in your vagrant box. It should be noted that the vagrant acts as our server.

You can find some very important server requirements to deploy a laravel app here. Also, the following packages will be needed in our vagrant box;

• apache2 => A web server software to access our deployed app from the browser.
• git => A collaboration tool needed to get the app code from its online repository into our local machine.
• composer => A tool for dependency management in PHP.

It is always good practice to create a user for a designated task in Linux. So we start by creating a user for this deployment. To create a user and its password and switch to that user, run this command below.

  sudo useradd -m -s /bin/bash -c "Laravel User" laravelUser  # User Creation
  sudo passwd laravelUser  # User password creation
  sudo usermod -aG sudo laravelUser  # Add user to the sudo group 
  su laravelUser. # Switching to the created user

The next step is to install apache on our local machine, but before then you have to update and upgrade the apt repository on our vagrant box(Debian 11 Linux Distro). To upgrade and update, run this command.

  sudo apt update && sudo apt upgrade

To install apache on your vagrant box and ensure its service always runs immediately after boot, run the following commands.

  sudo apt install apache2 # Installation of Apache
  sudo systemctl enable apache2 # Enabling apache server after boot

At this point, if we curl at our IP address from the vagrant box we should be able to see the official webpage of apache. To see this webpage in the command line, run this set of commands.

  ip a # Command to show your ip address
  curl http://<ip_address> # check for apache server running

Now, we’ve got our web server up and running. Our next task is to install PHP 8.1 and its dependencies in our vagrant box. PHP and its dependencies are needed to run a laravel app. Because PHP 8.1 is not in the default repository of Debian 11 we will have to add the deb.sury.org repository which brings PHP 8.1 and its dependencies to the vagrant box apt repository.

sudo apt-get install ca-certificates apt-transport-https   software-properties-common -y # Packages needed to add the deb.sury repo to our apt repo

Now run this command to add the deb.sury repository to our vagrant apt repository.

  sudo echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/sury-php.list

To ensure the added repository is secured and working properly, the GPG(GNU Privacy Guard) key is downloaded and used to crosscheck with the repository certificate.

To go about this, run this command:

sudo wget -qO - https://packages.sury.org/php/apt.gpg | sudo  apt-key add -

Next, we update and upgrade our apt repository and install PHP 8.1 and it’s dependencies.

  sudo apt update && sudo apt upgrade -y # repo update and upgrade
  sudo apt install php8.1 # install php8.1

Having installed PHP 8.1, we install the PHP dependencies needed for our app.

  sudo apt install php8.1-mysql libapache2-mod-php php8.1-imap php8.1-ldap php8.1-xml php8.1-fpm php8.1-curl php8.1-mbstring php8.1-zip # php dependencies

To manage these dependencies needed by the laravel app, laravel utilises composer for this management. So we install composer into our vagrant machine.

  sudo curl -sS https://getcomposer.org/installer | php

Move the downloaded file to your usr/local/bin folder in other to use the composer command globally.

  sudo mv composer.phar /usr/local/bin/composer 

Our laravel code resides in this GitHub repo which we need to clone into our /var/www/html folder. To clone a project from a GitHub repo you must have git installed on your vagrant machine.

  sudo apt install git -y # install git
  cd /var/www/html # change directory
  sudo git clone https://github.com/f1amy/laravel-realworld-example-app.git # get app code
  cd laravel-realworld-example-app

With the app code in our vagrant box, the laravel app is started by running this command

  sudo composer create-project

Next, we have to set the ownership and permission on our laravel app folder.

  sudo chown -R www-data:www-data /var/www/html/laravel-realworld-example-app/
  sudo chmod -R 775 /var/www/html/laravel-realworld-example-app/

With our apache web server already running in the background, we need to create an apache virtual host configuration file to link our laravel app directory to our web server such that we start seeing the content of our app and not the apache official page.

  sudo vi /etc/apache2/sites-available/laravel.conf

Then add these configuration lines to the created laravel.conf file.

  <VirtualHost *:80 *:3000>
    ServerAdmin [email protected]
    DocumentRoot /var/www/html/laravel-realworld-example-app/public/
     
    <Directory /var/www/html/laravel-realworld-example-app/public/>
            Options Indexes FollowSymLinks
            AllowOverride All
            Require all granted
    </Directory>
     
    LogLevel debug
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
  </VirtualHost>

For the configuration in the laravel.conf file to take effect we will need to run the following command so it gets recognised by the apache server as the required configuration to be used and not its default configuration found in 000-default.conf.

  sudo a2enmod rewrite
  sudo a2ensite laravel.conf

At this point, we can simply reload our apache server and our app will be deployed. To reload our apache server run this command.

  sudo systemctl reload apache2

Our database is not currently synched with the laravel app. For this project, we will use the MySQL database with our app. To get started with the syncing, we’ll install the MySQL package on our laravel app. Run the commands in the home directory of the created user.

  sudo wget https://dev.mysql.com/get/mysql-apt-config_0.8.22-1_all.deb # download mysql repo
  sudo apt install ./mysql-apt-config_0.8.22-1_all.deb # install packages needed for the mysql server
  sudo apt update # updating our apt repository
  sudo apt install mysql-server # installation of the mysql server

Once we have MySQL server installed you will be prompted to create a root password. This password will be needed to get into the MySQL command line in other to create a database table.

To create your database table and user needed for our app;

  sudo mysql -u root -p # use created root password

  ## This commands are run the the mysql commandline ##
  create database laravel; # database creation
  create user 'laravel'@'<ip_address>' identified by 'password'; # user creation
  grant all privileges on laravel.* TO laravel@<ip_address>;  # granting privilege to created user 
  flush privileges;
  quit;
  

Now we have our database set up let’s link it up with our app. This linking will be done in the .env file located in our laravel app directory.

  cd /var/www/html/laravel-realworld-example-app # change directory into app directory if not already in the directory
  sudo mv .env.example .env
  sudo php artisan key:generate
  sudo vi .env

Then add these configuration lines to the created .env file

  APP_URL=http://"your server IP" 
  DB_PORT= "3306" 
  DB_USERNAME= laravel 
  DB_HOST="your server IP" 
  DB_DATABASE= "name of the database you created" 
  DB_PASSWORD= "the mysql password of the laravel user you created in the mysql command line"

Once this is done then migrate data in your database to make it accessible in your app.

  sudo php artisan migrate --seed

Finally, reload your apace once again and you are done.

   sudo systemctl reload apache2

That’s it for this tutorial.

As usual, please let me know if you have any questions or concerns in the comments.

Thank you for reading!

Lead image source