Install Laravel On Ubuntu Server: A Step-by-Step Guide

by Team 55 views
Install Laravel on Ubuntu Server: A Step-by-Step Guide

Hey guys! Today, we're diving into how to get Laravel up and running on your Ubuntu server. Whether you're deploying a brand-new application or moving an existing one, this guide will walk you through each step to ensure a smooth installation. Let's get started!

Prerequisites

Before we jump into installing Laravel, let's make sure we have everything we need. This part is super important, so don't skip it!

1. Ubuntu Server

Obviously, you'll need an Ubuntu server. I recommend using the latest LTS (Long Term Support) version, which is usually the most stable. You can grab the Ubuntu Server ISO from the official Ubuntu website and install it on your machine or virtual server.

2. SSH Access

You'll need SSH access to your server. This allows you to remotely connect and run commands. If you're using a cloud provider like AWS, Digital Ocean, or Google Cloud, you'll typically have SSH access configured by default. If you're on a local server, make sure SSH is enabled and you know how to connect.

3. Basic Linux Knowledge

Some basic Linux command-line knowledge will be helpful. You should be comfortable navigating directories, editing files, and running commands using the terminal. Don't worry if you're not a Linux guru; this guide will provide the commands you need.

4. LAMP or LEMP Stack

Laravel needs a web server, a database, and PHP to run. You can choose between a LAMP (Linux, Apache, MySQL, PHP) or a LEMP (Linux, Nginx, MySQL, PHP) stack. For this guide, I'll assume you're using a LEMP stack because Nginx is often preferred for its performance and efficiency. If you haven't set up your stack yet, follow the next section to get it installed.

Setting Up the LEMP Stack

If you don't already have a LEMP stack, let's get that sorted out. Here’s how to install Nginx, MySQL, and PHP on your Ubuntu server.

1. Install Nginx

First, let’s install Nginx. Open your terminal and run these commands:

sudo apt update
sudo apt install nginx

After the installation, start and enable Nginx to make sure it runs automatically on boot:

sudo systemctl start nginx
sudo systemctl enable nginx

You can check if Nginx is running by visiting your server’s IP address in a web browser. You should see the default Nginx welcome page.

2. Install MySQL

Next up is MySQL. Install it with:

sudo apt install mysql-server

During the installation, you'll be prompted to set a root password. Make sure to choose a strong password and remember it. After the installation, secure your MySQL installation by running:

sudo mysql_secure_installation

Follow the prompts to set a root password, remove anonymous users, disallow remote root login, and remove the test database. This is a crucial step for securing your database.

3. Install PHP and Extensions

Now, let's install PHP and the necessary extensions for Laravel. Run:

sudo apt install php php-fpm php-mysql php-cli php-mbstring php-xml php-curl php-gd php-intl composer

Here’s what each extension does:

  • php-fpm: PHP FastCGI Process Manager, required for Nginx to handle PHP requests.
  • php-mysql: Allows PHP to communicate with MySQL databases.
  • php-cli: PHP command-line interpreter.
  • php-mbstring: For handling multi-byte strings.
  • php-xml: For working with XML documents.
  • php-curl: For making HTTP requests.
  • php-gd: For image processing.
  • php-intl: For internationalization support.
  • composer: A dependency manager for PHP.

4. Configure Nginx to Use PHP-FPM

Now that PHP is installed, you need to configure Nginx to use PHP-FPM to process PHP files. Create a new Nginx server block configuration file for your Laravel application. For example, if your application is named my-laravel-app, create a file at /etc/nginx/sites-available/my-laravel-app:

sudo nano /etc/nginx/sites-available/my-laravel-app

Add the following configuration:

server {
    listen 80;
    server_name your_server_ip_or_domain;
    root /var/www/my-laravel-app/public;

    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php7.4-fpm.sock; # Adjust the PHP version if needed
    }

    location ~ /\.ht {
        deny all;
    }
}

Important: Replace your_server_ip_or_domain with your server’s IP address or domain name, and /var/www/my-laravel-app/public with the actual path to your Laravel application's public directory. Also, adjust the fastcgi_pass directive to match your PHP version (e.g., php8.1-fpm.sock if you're using PHP 8.1).

Next, enable the server block by creating a symbolic link from the sites-available directory to the sites-enabled directory:

sudo ln -s /etc/nginx/sites-available/my-laravel-app /etc/nginx/sites-enabled/

Remove the default Nginx configuration file to avoid conflicts:

sudo rm /etc/nginx/sites-enabled/default

Finally, test the Nginx configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Installing Laravel

With the LEMP stack set up, we can now install Laravel. These steps involve downloading the Laravel installer and creating a new project.

1. Install Composer

If you haven't already, install Composer globally. Composer is a dependency manager for PHP, and Laravel uses it to manage its dependencies. Download and install Composer using these commands:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer

2. Create a New Laravel Project

Navigate to the directory where you want to create your Laravel project. For example, /var/www/:

cd /var/www/

Use Composer to create a new Laravel project:

sudo composer create-project --prefer-dist laravel/laravel my-laravel-app

Replace my-laravel-app with your desired project name. Composer will download Laravel and all its dependencies. This might take a few minutes depending on your internet connection.

3. Set Directory Permissions

After creating the project, you need to set the correct directory permissions. Laravel requires the storage and bootstrap/cache directories to be writable by the web server. Run these commands:

sudo chown -R www-data:www-data /var/www/my-laravel-app/storage
sudo chown -R www-data:www-data /var/www/my-laravel-app/bootstrap/cache
sudo chmod -R 775 /var/www/my-laravel-app/storage
sudo chmod -R 775 /var/www/my-laravel-app/bootstrap/cache

These commands change the ownership of the storage and bootstrap/cache directories to the www-data user and group (which is the user Nginx runs under) and set the permissions to allow the web server to write to these directories.

4. Generate Application Key

Next, generate the application key. This key is used by Laravel to encrypt sensitive data. Navigate to your Laravel project directory:

cd /var/www/my-laravel-app

Run the following command to generate the application key:

sudo php artisan key:generate

5. Configure the Database

Configure your database settings in the .env file. Open the .env file:

sudo nano .env

Update the database connection details to match your MySQL configuration:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password

Replace your_database_name, your_database_user, and your_database_password with your actual database credentials. Make sure the database exists in MySQL. You can create it using the MySQL command-line client:

mysql -u root -p

Enter your MySQL root password, and then run:

CREATE DATABASE your_database_name;
CREATE USER 'your_database_user'@'localhost' IDENTIFIED BY 'your_database_password';
GRANT ALL PRIVILEGES ON your_database_name.* TO 'your_database_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

6. Run Migrations

Run the database migrations to create the necessary tables. This assumes you have set up your database correctly in the .env file. From your Laravel project directory, run:

sudo php artisan migrate

This will create all the tables defined in your migration files.

Final Steps

Almost there! Just a few more tweaks to ensure everything is running smoothly.

1. Configure Nginx Root Directory

Make sure your Nginx configuration points to the public directory of your Laravel application. This is where the index.php file is located, which is the entry point for your application. Double-check your Nginx configuration file (/etc/nginx/sites-available/my-laravel-app) and ensure the root directive is set correctly:

root /var/www/my-laravel-app/public;

2. Restart Nginx and PHP-FPM

Restart Nginx and PHP-FPM to apply all the changes:

sudo systemctl restart nginx
sudo systemctl restart php7.4-fpm # Adjust the PHP version if needed

3. Access Your Laravel Application

Open your web browser and navigate to your server’s IP address or domain name. You should see your Laravel application's welcome page. If you encounter any issues, check the Laravel logs in the storage/logs directory for error messages.

Troubleshooting

Sometimes, things don't go as planned. Here are a few common issues and how to fix them.

1. 500 Internal Server Error

If you see a 500 Internal Server Error, it usually indicates a server-side issue. Check the Laravel logs in the storage/logs directory for detailed error messages. Common causes include incorrect file permissions, missing PHP extensions, or errors in your code.

2. File Permissions Issues

Incorrect file permissions can prevent Laravel from writing to the storage and bootstrap/cache directories. Make sure the www-data user has write access to these directories:

sudo chown -R www-data:www-data /var/www/my-laravel-app/storage
sudo chown -R www-data:www-data /var/www/my-laravel-app/bootstrap/cache
sudo chmod -R 775 /var/www/my-laravel-app/storage
sudo chmod -R 775 /var/www/my-laravel-app/bootstrap/cache

3. Missing PHP Extensions

If Laravel requires a PHP extension that is not installed, you'll see an error message in the logs. Install the missing extension using apt:

sudo apt install php-your-missing-extension

4. Database Connection Errors

Double-check your database credentials in the .env file and make sure the database server is running. Also, ensure that the database user has the necessary privileges to access the database.

Conclusion

And that’s it! You’ve successfully installed Laravel on your Ubuntu server. With your LEMP stack configured and Laravel up and running, you’re ready to start building amazing web applications. Remember to keep your server and dependencies updated for security and performance. Happy coding, guys!