Local Setup

Developer

Overview

The production environment executes directly on the host operating system and does not rely on a containerized infrastructure.

For local development, however, Docker is the reccomended local-development environment. While the application can technically run directly on a machine’s host layer, potential runtime version disparities and dependency drift make manual environment duplication unreliable. Subsequent development teams should treat the provided Docker configurations as the canonical local environment.

Useful references:

• Docker Get Started Guide
• Docker Compose Documentation

---

Prerequisites & Stack Specifications

The recommended local ecosystem requires the following system tools:

• Docker Desktop
• Docker Compose
• Git

The application environment expects and isolates the following specific stack layers:

• PHP 7.3–8.x
• Laravel 8 Framework
• PostgreSQL
• PostGIS Spatial Extension

---

Example Local Docker Configuration

The project does not include a standardized Docker configuration in the repository.

During this engagement, local development infrastructure fell outside the contracted scope. The inherited project did not provide a reproducible development environment, so V&B created an internal Docker configuration to make local development practical and consistent while implementing the contracted work.

The following configuration is provided as a working reference implementation rather than an official or required deployment standard. Future maintainers are free to improve or replace it, but it successfully supported day-to-day development throughout this engagement.

docker-compose.yml

services:
  app:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - .:/app
    env_file:
      - .env
    depends_on:
      - db

  db:
    image: postgis/postgis:15-3.4
    environment:
      POSTGRES_DB: autosplash
      POSTGRES_USER: laravel
      POSTGRES_PASSWORD: laravel
    volumes:
      - pgdata_legacy:/var/lib/postgresql/data
    ports:
      - "5433:5432"

volumes:
  pgdata_legacy:

docker/nginx.conf

server {
    listen 8001;
    server_name _;

    root /app/public;
    index index.php index.html;

    client_max_body_size 100M;

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

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

docker/supervisord.conf

[supervisord]
nodaemon=true
logfile=/var/log/supervisor/supervisord.log

[program:php-fpm]
command=/usr/local/sbin/php-fpm
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:nginx]
command=/usr/sbin/nginx -g "daemon off;"
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

Reference Only

This configuration is included as a proven development baseline that was successfully used throughout the engagement. It is not presented as the only valid Docker setup, nor as a recommendation for production infrastructure.

Future Improvements

The reference Docker configuration is intentionally minimal and exists solely as a proven local development environment.

Teams intending to adopt Docker for production deployments should treat it as a starting point rather than a finished production architecture. Typical improvements include:

• multi-stage image builds
• pinned image digests
• non-root container users
• health checks
• restart policies
• secrets management
• production PHP-FPM and Nginx tuning
• image vulnerability scanning
• centralized logging and monitoring

None of these were part of the engagement scope, as the production environment did not use containerized infrastructure.

Required Environment Configurations

Firebase Service Credentials

The repository intentionally excludes the authoritative Firebase service account credentials file for security reasons.

Before the application runtime can resolve dependencies successfully, the following configuration file must be manually placed into the project root directory:

autosplash-4207b-firebase-adminsdk-fbsvc-e1b19c127b.json

Without the presence of this file, Firebase-dependent features—specifically customer mobile OTP validation sequences and real-time messaging subsystems—will fail to initialize.

---

First-Time Bootstrap Sequence

To initialize a fresh repository clone locally, commands must be executed within the container shell in the following precise structural order to ensure dependencies exist before framework hooks are fired:

# 1. Install runtime dependencies
composer install

# 2. Initialize application security keys
php artisan key:generate

# 3. Build structural database layers and seed essential records
php artisan migrate
php artisan db:seed

Critical Seed Data Note

The application strictly requires database seeders to accompany migrations during startup. During the platform stabilization phase, several missing foundational seeds were corrected and integrated because portions of the inherited codebase implicitly depend on core lookups existing out of the box. Running migrations without executing db:seed will result in incomplete database states and unpredictable logic failures.

---

Running the Application

To orchestrate and spin up the localized ecosystem, execute the standard Compose instruction from the root folder:

docker compose up --build

(Note: Depending on your specific local engine version, you may alternatively use docker-compose up --build).

The orchestration engine mounts the project directory directly into the active application container runtime while exposing an isolated PostgreSQL data layer through designated network ports.

---

Database & Spatial Topologies

Local database operations run on PostgreSQL paired with the PostGIS spatial extension. The supplied development file provisions the data container using the following explicit parameters:

db:
  image: postgis/postgis:15-3.4
  environment:
    POSTGRES_DB: autosplash
    POSTGRES_USER: laravel
    POSTGRES_PASSWORD: laravel

Strategic Importance of PostGIS

The PostGIS extension is a structural system requirement. Core booking sequences depend directly on specialized geographic spatial calculations (PolygonModel) to assess coverage limits and match user locations with active service perimeters. Attempting to execute the application without a properly provisioned PostGIS extension will cause location queries to error out.

---

Local Infrastructure Layout

The repository includes specific configurations designed exclusively to build a reproducible local development sandbox:

• docker-compose.yml
• docker/nginx.conf
• docker/supervisord.conf

These configurations serve solely to streamline local developer onboarding and mirror the application dependencies uniformly. They are distinct from, and independent of, the host-level parameters utilized in the production server architecture.

---

Deployment Optimization Script

The repository includes an optimized server deployment helper utility located within the project files:

#!/bin/bash

# Ensure local tree reflects the branch state cleanly
git reset --hard HEAD
git pull

# Install production-ready dependency structures
composer update --no-dev --optimize-autoloader --no-interaction

# Execute pending database migrations safely
php artisan migrate --force

# Clear out any conflicting runtime state caches
php artisan optimize:clear

# Build highly performant compiled caches for production operations
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan optimize

This helper script is designed to safely automate upstream server updates by ensuring a synchronized repository state, applying schema updates, clearing lingering memory files, and compiling unified Laravel caching schemas to optimize server response times.

---

Operational Troubleshooting & Known Constraints

Host-Level Version Irregularities

Running this application directly on a host machine rather than utilizing the provided container ecosystem may surface runtime errors arising from dependency constraints. Docker is provided as the definitive mitigation for version management.

Missing Cryptographic Keys & Configs

The system environment will fail to manage active sessions or processes if the required Firebase service account JSON structural file is omitted from the application root.

Container File System Ownership Permissions

Depending on your host operating system’s filesystem engine (e.g., specific Linux or macOS permission groupings), files generated internally by the Docker container may inherit root-level execution permissions. If your editor or local package manager encounters write restrictions, reset the working directory ownership mapping using your system’s chown configuration utilities.

---

Runtime Integration Summary

The primary functional modules driving the application ecosystem are explicitly detailed below:

• Laravel 8 Core Monolith
• PostgreSQL Database Engine
• PostGIS Geographic Extension
• Google Firebase Auth Services
• Stripe Payment Processing API
• Amazon S3 Asset Storage
• Twilio Communication Services
• Xero Accounting Integration
• Laravel WebSockets Server

For package update procedures, the composer.json schema is the authoritative reference for version ranges and core dependencies.

---

Handover Transition Guidelines

This deployment documentation establishes the baseline local configuration designed to minimize downstream engineering overhead. Incoming engineering resources are strongly encouraged to utilize the provided container system to ensure uniform behavior and significantly accelerate onboarding timelines.