Containerize Avalúo Vehicular with Docker Compose

Docker is the recommended way to deploy Avalúo Vehicular in any environment — local, staging, or production. The included configuration bundles everything the application needs into a single, self-contained image: an Nginx web server, PHP 8.4-FPM for application processing, a Laravel Queue Worker for background jobs, and SQLite for persistence. Two helper scripts — docker.sh for Linux/Mac and docker.ps1 for Windows — wrap all common Docker Compose operations into short, memorable commands so you never have to remember the underlying docker-compose syntax.

Architecture Overview

The Dockerfile uses a four-stage multi-stage build to produce a lean, production-ready image:

Stage	Base Image	Purpose
`composer-builder`	`composer:2.7`	Installs PHP production dependencies with optimized autoloader
`wayfinder-generator`	`php:8.4-cli-alpine`	Runs `php artisan wayfinder:generate` to produce typed route helpers
`frontend-builder`	`node:20-alpine`	Runs `npm ci` and `vite build` to compile React/TypeScript/TailwindCSS assets
`production`	`php:8.4-fpm-alpine`	Final image — copies artifacts from all previous stages; no dev dependencies included

The final image installs Nginx and Supervisor directly onto the PHP-FPM Alpine base and copies pre-compiled assets from each builder stage, keeping the image footprint small.

Supervisor is the process manager inside the container. It starts and monitors three long-running processes simultaneously:

PHP-FPM — handles PHP request processing
Nginx — serves static assets and proxies PHP requests to FPM
Laravel Queue Worker — processes background jobs; configured to restart automatically on failure

The entrypoint script at docker/entrypoint.sh bootstraps the container before handing control to Supervisor.

Quick Start

Windows (PowerShell)
Linux / Mac (Bash)

Run First-Time Setup

The setup command creates .env.docker (if missing), builds the Docker image, starts the container, generates APP_KEY, and runs all migrations in one step:

.\docker.ps1 setup

Start the Application

On subsequent runs, start the already-built container directly:

.\docker.ps1 start

The application will be available at http://localhost:8080.

Make the Script Executable

Grant execute permission to the helper script (one-time step):

chmod +x docker.sh

Run First-Time Setup

The setup command creates .env.docker (if missing), builds the Docker image, starts the container, generates APP_KEY, and runs all migrations in one step:

./docker.sh setup

Start the Application

On subsequent runs, start the already-built container directly:

./docker.sh start

The application will be available at http://localhost:8080.

Management Commands

Both docker.sh and docker.ps1 expose the same set of commands:

Command	Linux/Mac	Windows	Description
`setup`	`./docker.sh setup`	`.\docker.ps1 setup`	First-time setup: build, start, key:generate, migrate
`build`	`./docker.sh build`	`.\docker.ps1 build`	Build the Docker image
`start`	`./docker.sh start`	`.\docker.ps1 start`	Start containers in detached mode
`stop`	`./docker.sh stop`	`.\docker.ps1 stop`	Stop and remove containers
`restart`	`./docker.sh restart`	`.\docker.ps1 restart`	Restart running containers
`logs`	`./docker.sh logs`	`.\docker.ps1 logs`	Tail live container logs (`Ctrl+C` to exit)
`migrate`	`./docker.sh migrate`	`.\docker.ps1 migrate`	Run `php artisan migrate --force` inside the container
`fresh`	`./docker.sh fresh`	`.\docker.ps1 fresh`	Reset the database — destroys all data
`optimize`	`./docker.sh optimize`	`.\docker.ps1 optimize`	Clear caches then rebuild config, route, and view caches
`shell`	`./docker.sh shell`	`.\docker.ps1 shell`	Open an interactive `sh` shell inside the container
`status`	`./docker.sh status`	`.\docker.ps1 status`	Show `docker-compose ps` and `supervisorctl status`
`artisan`	`./docker.sh artisan <cmd>`	`.\docker.ps1 artisan <cmd>`	Run any Artisan command (e.g. `artisan make:controller Foo`)
`rebuild`	`./docker.sh rebuild`	`.\docker.ps1 rebuild`	Stop, rebuild with `--no-cache`, and restart
`clean`	`./docker.sh clean`	`.\docker.ps1 clean`	Remove containers, volumes, and the `avaluo-app` image

Docker Compose Direct Usage

For CI/CD pipelines or environments where you want to drive Docker Compose without the helper scripts, use the underlying commands directly:

# Build the multi-stage image
docker-compose build

# Start the container in the background
docker-compose up -d

# Generate APP_KEY (required on first deploy)
docker-compose exec app php artisan key:generate --force

# Run database migrations
docker-compose exec app php artisan migrate --force

To update a running deployment after a code change:

docker-compose down
git pull
docker-compose build
docker-compose up -d
docker-compose exec app php artisan migrate --force
docker-compose exec app php artisan optimize:clear

Persistent Volumes

The docker-compose.yml mounts three host directories into the container so that critical data survives container rebuilds and restarts:

Host Path	Container Path	Contents
`./database/database.sqlite`	`/var/www/html/database/database.sqlite`	SQLite database file — all application data
`./storage/logs`	`/var/www/html/storage/logs`	Laravel application logs
`./storage/app`	`/var/www/html/storage/app`	User-uploaded files (vehicle images, generated PDFs)

These mounts are defined in docker-compose.yml and are independent of the container image. Running docker.sh clean or docker-compose down -v will remove named volumes, but these bind-mount paths on the host are never deleted automatically.

Environment Variables

Container environment is configured through .env.docker, which is loaded as env_file in docker-compose.yml. The following variables are the most important to review before your first deployment:

Variable	Default	Description
`APP_ENV`	`production`	Application environment mode
`APP_DEBUG`	`false`	Disable debug output in production
`APP_URL`	`http://localhost:8080`	Public URL used for generating links
`DB_CONNECTION`	`sqlite`	Database driver (SQLite is the only supported driver)

APP_KEY is not set in .env.docker by default. Without it, Laravel cannot decrypt cookies or sessions and will throw a No application encryption key has been specified error. Always run one of the following after building the image for the first time:

# Via helper script (recommended)
./docker.sh setup      # Linux/Mac — runs key:generate automatically
.\docker.ps1 setup     # Windows — runs key:generate automatically

# Or manually via Docker Compose
docker-compose exec app php artisan key:generate --force

Health Check

The container exposes a /health endpoint via Nginx. Docker Compose polls it every 30 seconds (interval: 30s, timeout: 10s, retries: 3, start_period: 40s) to determine container health. You can check it manually at any time:

curl http://localhost:8080/health

To inspect the status of all processes managed by Supervisor inside the running container:

docker-compose exec app supervisorctl status

A healthy container will show php-fpm, nginx, and the Laravel queue worker all in RUNNING state.

Introducción

Instalación

Configuración

Características

Administración

Containerize Avalúo Vehicular with Docker Compose

Architecture Overview

Quick Start

Management Commands

Docker Compose Direct Usage

Persistent Volumes

Environment Variables

Health Check

Build docs developers (and LLMs) love

Introducción

Instalación

Configuración

Características

Administración

Documentation Index

​Architecture Overview

​Quick Start

​Management Commands

​Docker Compose Direct Usage

​Persistent Volumes

​Environment Variables

​Health Check

Build docs developers (and LLMs) love

Architecture Overview

Quick Start

Management Commands

Docker Compose Direct Usage

Persistent Volumes

Environment Variables

Health Check