Installation

This guide provides comprehensive instructions for installing and configuring Macuin Laravel, a SaaS e-commerce platform for automotive parts.

Architecture Overview

Macuin Laravel uses a containerized architecture with Docker Compose orchestrating multiple services:

Service	Image	Description	Port
Nginx	`nginx:1.27-alpine`	Web server handling HTTP requests	8000
Laravel App	`php:8.3-fpm` (custom)	PHP-FPM running Laravel 12	internal
PostgreSQL	`postgres:16-alpine`	Database server	5432
Node	`node:22-alpine`	Frontend asset compilation with Vite	5173

Prerequisites

Required Software

Before installing Macuin Laravel, ensure you have the following installed on your system:

Docker

Container runtime engineDownload Docker

Docker Desktop

Docker management interface (recommended)Download Docker Desktop

Docker Compose

Multi-container orchestration toolIncluded with Docker Desktop

Git

Version control systemDownload Git

System Requirements

OS: Linux, macOS, or Windows with WSL2
RAM: Minimum 4GB, recommended 8GB+
Disk Space: At least 5GB free space
Ports: 8000, 5432, and 5173 must be available

Installation Steps

Clone the Repository

Clone the Macuin Laravel repository from GitHub:

git clone https://github.com/usuario/macuin-laravel.git
cd macuin-laravel

Verify the project structure:

ls -la

You should see files including:

docker-compose.yml
composer.json
.env.example
docker/ directory

Build and Start Containers

Build the Docker images and start all services:

docker compose up -d --build

This command will:

Build the custom PHP 8.3-FPM container with PostgreSQL extensions
Pull official images for Nginx, PostgreSQL, and Node.js
Create a bridge network for service communication
Start all containers in detached mode

The initial build process may take 5-10 minutes depending on your internet connection.

Verify all containers are running:

docker ps

You should see 4 containers:

laravel_nginx
laravel_app
laravel_postgres
laravel_node

Install PHP Dependencies

Access the Laravel application container:

docker exec -it laravel_app bash

Install Composer dependencies:

composer install

This installs Laravel 12 and all required packages including:

Laravel Framework
Laravel Tinker
PHPUnit for testing
Laravel Pint for code formatting

The container has Composer 2 pre-installed and configured.

Configure Environment Variables

Create your environment configuration file:

cp .env.example .env

The .env file is automatically configured for Docker by the docker-compose.yml environment variables, but you should verify the settings:

.env

APP_NAME=Macuin
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret

In production, change DB_PASSWORD to a strong, unique password and set APP_DEBUG=false.

Generate Application Key

Generate a unique application encryption key:

php artisan key:generate

This updates the APP_KEY in your .env file. This key is used for:

Session encryption
Password hashing
Secure cookie encryption

Run Database Migrations

Execute database migrations to create the schema:

php artisan migrate

This creates all necessary tables in the PostgreSQL database.

The PostgreSQL service includes a health check that ensures the database is ready before the app container starts.

Exit Container

Exit the Laravel container:

exit

Access the Application

Open your browser and navigate to:

http://localhost:8000

You should see the Macuin Laravel application homepage.

Environment Variables

Application Configuration

.env

# Application Identity
APP_NAME=Macuin
APP_ENV=local          # Environment: local, staging, production
APP_KEY=               # Generated by php artisan key:generate
APP_DEBUG=true         # Enable debug mode (disable in production)
APP_URL=http://localhost:8000

# Localization
APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

Database Configuration

.env

# PostgreSQL Database (configured by docker-compose.yml)
DB_CONNECTION=pgsql
DB_HOST=postgres       # Container name from docker-compose.yml
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret     # Change in production!

The database credentials are defined in both .env and docker-compose.yml. Ensure they match for proper connectivity.

Session & Cache Configuration

.env

# Session Management
SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=false

# Cache Configuration
CACHE_STORE=database
QUEUE_CONNECTION=database

Logging

.env

# Logging Configuration
LOG_CHANNEL=stack
LOG_STACK=single
LOG_LEVEL=debug        # Options: debug, info, notice, warning, error

Mail Configuration

.env

# Mail Settings
MAIL_MAILER=log        # Logs emails instead of sending (development)
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Frontend Assets

.env

# Vite Configuration
VITE_APP_NAME="${APP_NAME}"

Docker Configuration

Container Details

The docker-compose.yml defines the following services:

PostgreSQL Service

docker-compose.yml

postgres:
  image: postgres:16-alpine
  container_name: laravel_postgres
  environment:
    POSTGRES_DB: laravel
    POSTGRES_USER: laravel
    POSTGRES_PASSWORD: secret
  ports:
    - "5432:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U laravel -d laravel"]
    interval: 5s
    timeout: 3s
    retries: 20

The health check ensures the database is ready before dependent services start.

Laravel App Service

docker-compose.yml

app:
  build:
    context: .
    dockerfile: docker/php/Dockerfile
    args:
      UID: "1000"
      GID: "1000"
  container_name: laravel_app
  working_dir: /var/www/html
  volumes:
    - ./:/var/www/html
  environment:
    DB_CONNECTION: pgsql
    DB_HOST: postgres
    DB_PORT: 5432
    DB_DATABASE: laravel
    DB_USERNAME: laravel
    DB_PASSWORD: secret
  depends_on:
    postgres:
      condition: service_healthy

The custom Dockerfile installs:

PHP 8.3-FPM
PostgreSQL PDO extensions
Composer 2
Git, curl, unzip, zip

Nginx Service

docker-compose.yml

nginx:
  image: nginx:1.27-alpine
  container_name: laravel_nginx
  ports:
    - "8000:80"
  volumes:
    - ./:/var/www/html:ro
    - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
  depends_on:
    - app

Nginx proxies requests to the Laravel app container on port 9000 (PHP-FPM).

Node Service

docker-compose.yml

node:
  image: node:22-alpine
  container_name: laravel_node
  working_dir: /var/www/html
  volumes:
    - ./:/var/www/html
    - node_modules:/var/www/html/node_modules
  ports:
    - "5173:5173"
  command: sh -lc "chown -R 1000:1000 /var/www/html/node_modules && npm ci || npm i && npm run dev -- --host 0.0.0.0 --port 5173 --strictPort"

Automatically runs Vite development server for hot module replacement.

Development Workflow

Composer Scripts

The project includes helpful Composer scripts:

# Inside laravel_app container
composer setup

# This runs:
# - composer install
# - Copy .env.example to .env
# - Generate application key
# - Run migrations
# - Install npm dependencies
# - Build frontend assets

Useful Docker Commands

docker ps

Laravel Artisan Commands

Common Artisan commands for development:

# Run migrations
php artisan migrate

# Rollback migrations
php artisan migrate:rollback

# Fresh migration (drops all tables)
php artisan migrate:fresh

# Seed database
php artisan db:seed

Troubleshooting

Port Already in Use

Problem: Error message “port is already allocated” when running docker compose up.Solution:

Check which process is using the port:

# Linux/macOS
lsof -i :8000

# Windows
netstat -ano | findstr :8000

Stop the conflicting process or modify docker-compose.yml to use different ports:
```
nginx:
  ports:
    - "8080:80"  # Change 8000 to 8080
```

Database Connection Failed

Problem: Laravel cannot connect to PostgreSQL database.Solution:

Verify containers are running:
```
docker ps
```

Check PostgreSQL health:

docker exec -it laravel_postgres pg_isready -U laravel

Verify environment variables match in .env and docker-compose.yml:
- DB_HOST=postgres (container name)
- DB_DATABASE=laravel
- DB_USERNAME=laravel
- DB_PASSWORD=secret
Restart services:
```
docker compose restart
```

Permission Denied Errors

Problem: Permission errors when accessing files inside containers.Solution:

The PHP container runs as user appuser (UID 1000, GID 1000)

Fix file permissions on host:

sudo chown -R $USER:$USER .
chmod -R 755 storage bootstrap/cache

Inside container:

docker exec -it laravel_app bash
chmod -R 775 storage bootstrap/cache

Composer Install Fails

Problem: composer install fails with memory errors or network issues.Solution:

Increase PHP memory limit:

docker exec -it laravel_app bash
COMPOSER_MEMORY_LIMIT=-1 composer install

Clear Composer cache:
```
composer clear-cache
composer install
```
Try with verbose output:
```
composer install -vvv
```

npm/Node Issues

Problem: Frontend assets not compiling or Vite not starting.Solution:

Check Node container logs:
```
docker logs laravel_node
```

Rebuild node_modules:

docker exec -it laravel_node sh
rm -rf node_modules package-lock.json
npm install
npm run dev

Restart Node container:
```
docker compose restart node
```

Container Won't Start

Problem: Container exits immediately or won’t start.Solution:

Check container logs:
```
docker logs laravel_app
```
Verify Docker resources (CPU, memory, disk space)

Rebuild containers from scratch:

docker compose down -v
docker compose build --no-cache
docker compose up -d

Migrations Fail

Problem: Database migrations fail or tables not created.Solution:

Ensure PostgreSQL is healthy:

docker exec -it laravel_postgres pg_isready -U laravel -d laravel

Check database connection:

docker exec -it laravel_app bash
php artisan db:show

Run migrations with verbose output:
```
php artisan migrate -vvv
```
Fresh migration if needed:
```
php artisan migrate:fresh
```

Next Steps

Now that you have Macuin Laravel installed, you can:

Configure Features

Set up mail, cache, and queue configurations

Develop Features

Start building your automotive parts e-commerce features

Run Tests

Execute PHPUnit tests with composer test

Deploy to Production

Prepare for production deployment

For development, use composer dev inside the container to run all development servers concurrently with hot reloading.

Get Started

Docker Setup

Features

Components

Architecture Overview

Prerequisites

Required Software

Docker

Docker Desktop

Docker Compose

Git

System Requirements

Installation Steps

Environment Variables

Application Configuration

Database Configuration

Session & Cache Configuration

Logging

Mail Configuration

Frontend Assets

Docker Configuration

Container Details

Development Workflow

Composer Scripts

Useful Docker Commands

Laravel Artisan Commands

Troubleshooting

Next Steps

Configure Features

Develop Features

Run Tests

Deploy to Production

Build docs developers (and LLMs) love

Get Started

Docker Setup

Features

Components

​Architecture Overview

​Prerequisites

​Required Software

Docker

Docker Desktop

Docker Compose

Git

​System Requirements

​Installation Steps

​Environment Variables

​Application Configuration

​Database Configuration

​Session & Cache Configuration

​Logging

​Mail Configuration

​Frontend Assets

​Docker Configuration

​Container Details

​Development Workflow

​Composer Scripts

​Useful Docker Commands

​Laravel Artisan Commands

​Troubleshooting

​Next Steps

Configure Features

Develop Features

Run Tests

Deploy to Production

Build docs developers (and LLMs) love

Architecture Overview

Prerequisites

Required Software

System Requirements

Installation Steps

Environment Variables

Application Configuration

Database Configuration

Session & Cache Configuration

Logging

Mail Configuration

Frontend Assets

Docker Configuration

Container Details

Development Workflow

Composer Scripts

Useful Docker Commands

Laravel Artisan Commands

Troubleshooting

Next Steps