Laravel Docker Ubuntu Guide: Step-by-Step Setup for Modern Development

Laravel is a popular PHP framework renowned for its elegant syntax and powerful features. Docker is a containerization platform that allows developers to package applications and their dependencies into isolated environments. Combining Laravel with Docker on Ubuntu streamlines development, ensures consistency across environments, and simplifies deployment. In this guide, you’ll learn how to set up a Laravel development environment using Docker and Docker Compose on Ubuntu, from scratch to running application.

Prerequisites

Before you begin, make sure your system meets the following requirements:

• Ubuntu 22.04 or later (other versions may work with minor adjustments)
• At least 2 GB of RAM and 10 GB of free disk space
• Access to a terminal with sudo privileges
• Basic familiarity with the command line

You’ll also need:

• Docker installed
• Docker Compose installed
• Git installed

The Docker images used in this guide are sourced from Docker Hub to ensure a streamlined and consistent environment setup.

Installing Docker and Docker Compose on Ubuntu

1. Update your package index:

sudo apt-get update && sudo apt-get upgrade -y

2. Install required packages:

sudo apt-get install apt-transport-https ca-certificates curl software-properties-common -y

3. Add Docker’s official GPG key and repository:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg –dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo “deb [arch=$(dpkg –print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list

4. Install Docker Engine and Docker Compose:

sudo apt-get update sudo apt-get install docker-ce docker-compose -y

5. Verify installation:

docker –version docker-compose –version

6. (Optional) Run Docker as a non-root user:

sudo usermod -aG docker $USER newgrp docker

Note: Running Docker as a non-root user allows you to execute Docker commands with the same permissions as your current user on the host machine. This helps ensure that files created by containers have the correct ownership and avoids file permission issues.

Setting Up a New Laravel Project

You can create a new Laravel project in several ways. Here’s how to do it using Composer:

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

Or, if you prefer cloning an existing repository:

git clone https://github.com/laravel/laravel.git my-app cd my-app composer install

These steps will download and set up the application code required for the rest of this guide.

Navigate to your project directory:

cd my-app

Configuring the Laravel Environment

Laravel uses a .env file for environment-specific configuration. To set it up:

cp .env.example .env

Edit the .env file to configure your database connection for Docker. For example:

DB_CONNECTION=mysql DB_HOST=db DB_PORT=3306 DB_DATABASE=laravel DB_USERNAME=laravel_user DB_PASSWORD=secret

These values will match the settings in your Docker Compose file.

Creating the Dockerfile

A Dockerfile defines your application’s runtime environment. Here, you will create a custom image for your application. Create a Dockerfile in your project root with the following content:

FROM php:8.2-fpm # Install system dependencies RUN apt-get update && apt-get install -y \ git \ curl \ libpng-dev \ libonig-dev \ libxml2-dev \ zip \ unzip # Install PHP extensions RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd # Get Composer COPY –from=composer:latest /usr/bin/composer /usr/bin/composer # Create system user ARG user=laravel ARG uid=1000 RUN useradd -G www-data,root -u $uid -d /home/$user $user RUN mkdir -p /home/$user/.composer && chown -R $user:$user /home/$user WORKDIR /var/www USER $user

This Dockerfile builds a Docker image based on the official PHP-FPM image, tailored for Laravel development. It installs necessary PHP extensions, Composer, and sets up a non-root user for development. This custom image will be used as the application container in your Docker Compose setup.

Configuring Nginx for Laravel

To configure Nginx for your Laravel application, create a folder for your Nginx configuration:

mkdir -p docker-compose/nginx

Create a file named app.conf inside this folder. This will be your Nginx configuration file. Add the following content:

server { listen 80; index index.php index.html; error_log /var/log/nginx/error.log; access_log /var/log/nginx/access.log; root /var/www/public; location ~ .php$ { try_files $uri =404; fastcgi_split_path_info ^(.+.php)(/.+)$; fastcgi_pass app:9000; fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; } location / { try_files $uri $uri/ /index.php?$query_string; gzip_static on; } }

This configuration ensures Nginx serves your Laravel application and forwards PHP requests to the app container. With this setup, the nginx service is properly configured to serve your application within the Docker environment.

Writing the docker-compose.yml File

Create a Docker Compose YAML file in your project root:

version: “3.7” services: app: build: context: ./ dockerfile: Dockerfile args: user: laravel uid: 1000 image: laravel-app container_name: laravel-app restart: unless-stopped working_dir: /var/www/ volumes: – ./:/var/www networks: – laravel db: image: mysql:8.0 container_name: laravel-db restart: unless-stopped environment: MYSQL_DATABASE: laravel MYSQL_ROOT_PASSWORD: secret MYSQL_PASSWORD: secret MYSQL_USER: laravel_user volumes: – dbdata:/var/lib/mysql/ networks: – laravel nginx: image: nginx:alpine container_name: laravel-nginx restart: unless-stopped ports: – 8000:80 volumes: – ./:/var/www – ./docker-compose/nginx:/etc/nginx/conf.d/ networks: – laravel networks: laravel: driver: bridge volumes: dbdata:

This YAML file defines three services, each running in a separate container: the Laravel app, the db service using the official mysql image, and nginx services to serve the application and handle web traffic. All services are connected via an app network for secure communication and easier management in a multi-container Docker environment.

Building and Running the Containers

1. Build the Docker images:

Run the following command to build the Docker image:

docker-compose build app

2. Start the containers:

Run the following command to start the containers:

docker-compose up -d

3. Check container status:

docker-compose ps

You should see all three services running.

Finalizing the Laravel Setup Inside Docker

1. Install Composer dependencies:

To install your PHP dependencies, run composer install inside the container:

docker-compose exec app composer install

This command will run composer within the app container, ensuring all required dependencies are set up in your Docker environment.

After installing dependencies, note that the app service runs a php-fpm server, which processes your PHP code before serving it via Nginx.

2. Generate the application key:

docker-compose exec app php artisan key:generate

3. Run database migrations (optional):

docker-compose exec app php artisan migrate

Accessing Your Laravel Application

Open your browser and navigate to:

http://localhost:8000

If everything is set up correctly, you’ll see the Laravel web application welcome page. If not, check container logs for errors, such as the following error related to database connection or user authentication (e.g., “Access denied for user ‘root’@’app.my-project_app-network'”):

docker-compose logs nginx docker-compose logs app

Managing Your Dockerized Laravel Environment

Here are some useful Docker Compose commands:

• Stop the environment:
  docker-compose down
• Pause services:
  docker-compose pause
• Resume services:
  docker-compose unpause
• View logs:
  docker-compose logs [service]
• Execute commands inside containers:
  docker-compose exec app php artisan [command]

Automate Your Laravel Docker Setup with CTO2B

Setting up Docker for Laravel can be time-consuming and error-prone, especially for teams or newcomers. That’s why we created CTO2B – a tool that automates the entire process. With just a few clicks, you can generate a fully configured Docker environment for your Laravel projects on Ubuntu. Save time, avoid common pitfalls, and get started building faster. Try CTO2B today and supercharge your Laravel development workflow!

Conclusion

By following this guide, you’ve set up a modern Laravel development environment on Ubuntu using Docker and Docker Compose. This approach ensures consistency, simplifies onboarding, and makes your workflow more efficient. You can now focus on building your application without worrying about local dependency conflicts or manual environment setup.

This setup can also be extended to deploy Laravel in a production environment. Deploying Laravel with Docker ensures a consistent deployment process from development to production, making it easier to manage and scale your application.