Skip to main content

​
Introduction

Macuin uses Docker to provide a consistent, isolated development environment across different machines. The application runs in a multi-container setup orchestrated by Docker Compose, ensuring all services work together seamlessly.

​
Multi-Container Architecture

The Macuin platform is built on a microservices-inspired architecture with four main containers:

Nginx

Web server and reverse proxy handling HTTP requests

Laravel App

PHP-FPM container running the Laravel application

PostgreSQL

Database service for persistent data storage

Node

Frontend asset compilation with Vite

​
Architecture Diagram

┌─────────────────────────────────────────────────────┐
│                   Host Machine                      │
│                                                     │
│  ┌───────────────────────────────────────────────┐ │
│  │        Docker Network (laravel_network)       │ │
│  │                                               │ │
│  │  ┌──────────┐      ┌──────────────┐          │ │
│  │  │  Nginx   │─────>│  Laravel App │          │ │
│  │  │  :80     │      │  PHP 8.3-FPM │          │ │
│  │  └────┬─────┘      └──────┬───────┘          │ │
│  │       │                   │                   │ │
│  │       │                   └──────────┐        │ │
│  │       │                              │        │ │
│  │  ┌────▼────┐                  ┌──────▼─────┐ │ │
│  │  │  Node   │                  │ PostgreSQL │ │ │
│  │  │  :5173  │                  │   :5432    │ │ │
│  │  └─────────┘                  └────────────┘ │ │
│  │                                               │ │
│  └───────────────────────────────────────────────┘ │
│       │              │                │            │
│    Port 8000     Port 5173        Port 5432        │
└───────┼──────────────┼────────────────┼────────────┘
        │              │                │
    HTTP Access    Vite Dev         Database
                   Server           Access

​
Service Dependencies

The containers have a specific startup order managed by Docker Compose:
  1. PostgreSQL starts first with health checks
  2. Laravel App waits for PostgreSQL to be healthy
  3. Nginx starts after the Laravel app is ready
  4. Node runs independently for frontend assets
The dependency chain ensures the database is ready before Laravel attempts to connect, preventing connection errors during startup.

​
Networking

All services communicate through a dedicated Docker bridge network called laravel_network. This provides:
  • Service Discovery: Containers can reach each other by service name (e.g., app, postgres)
  • Isolation: The network is isolated from other Docker containers
  • DNS Resolution: Automatic DNS resolution for service names

​
Inter-Service Communication

  • Nginx → Laravel App: fastcgi_pass app:9000 (PHP-FPM)
  • Laravel App → PostgreSQL: DB_HOST=postgres on port 5432
  • Host → Nginx: localhost:8000 (mapped to container port 80)
  • Host → Vite: localhost:5173 (hot module replacement)

​
Benefits of Docker Setup

Consistency

Same environment across development, staging, and production

Isolation

Dependencies contained without affecting host system

Quick Setup

New developers can start with a single command

Version Control

Infrastructure as code in version control

​
Key Advantages

Development Speed
  • No manual installation of PHP, PostgreSQL, or Node
  • Pre-configured services with optimal settings
  • Hot reloading for both backend and frontend
Reliability
  • Health checks ensure services are ready before dependent services start
  • Automatic restart on failure
  • Consistent behavior across team members
Scalability
  • Easy to add new services (Redis, queue workers, etc.)
  • Can scale individual services independently
  • Simple to replicate for testing environments

​
Port Mappings

The following ports are exposed to the host machine:
ServiceContainer PortHost PortPurpose
Nginx808000Web application access
PostgreSQL54325432Database connections
Node (Vite)51735173Frontend dev server & HMR
Make sure these ports are available on your host machine before starting the containers.

​
Data Persistence

Two named volumes ensure data persists across container restarts:
  • postgres_data: Stores PostgreSQL database files
  • node_modules: Caches Node.js dependencies for faster builds

​
Next Steps

Configuration

Learn how to customize Docker settings

Services

Detailed documentation for each service

Build docs developers (and LLMs) love

Get started for freeTalk to us