Skip to main content
Filebright uses Docker Compose to orchestrate multiple services for easy deployment. This guide covers the complete Docker setup including all services, configuration, and management.

​
Architecture overview

The Docker Compose setup includes five services:
  • app - PHP-FPM application server (Laravel backend)
  • web - Nginx web server (reverse proxy)
  • worker - Queue worker for background jobs
  • db - PostgreSQL database
  • frontend - React frontend (served by Nginx)
All services communicate through a dedicated bridge network (filebright_net).

​
Prerequisites

1

Install Docker

Install Docker Engine 20.10+ and Docker Compose v2.0+ on your system. Visit docker.com for installation instructions.
2

Clone the repository

git clone <repository-url>
cd filebright
3

Configure environment

Copy the example environment file and update the configuration:
cp backend/.env.example backend/.env
Set required environment variables in backend/.env:
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:your-generated-key
DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
DB_DATABASE=filebright
DB_USERNAME=user
DB_PASSWORD=secure_password
Generate a new APP_KEY using php artisan key:generate or set a strong random value.

​
Service configuration

​
App service (PHP-FPM)

The main application server runs PHP 8.4-FPM in Alpine Linux for minimal footprint.
docker-compose.yml
app:
  build:
    context: ./backend
    dockerfile: Dockerfile
  container_name: filebright_app
  restart: unless-stopped
  working_dir: /var/www
  env_file: ./backend/.env
  volumes:
    - ./backend/storage:/var/www/storage
    - ./backend/php.ini:/usr/local/etc/php/conf.d/custom.ini
  depends_on:
    db:
      condition: service_healthy
The app service uses a multi-stage build to optimize image size and includes MongoDB support via PECL extension.
Key features:
  • Multi-stage build process for optimized image size
  • Composer dependencies installed with --no-dev --optimize-autoloader
  • Automatic migration execution on container start
  • Health check dependency ensures database is ready

​
Web service (Nginx)

Nginx serves as a reverse proxy to the PHP-FPM application server.
docker-compose.yml
web:
  image: nginx:alpine
  container_name: filebright_web
  restart: unless-stopped
  ports:
    - "8000:80"
  volumes:
    - ./backend/public:/var/www/public
    - ./backend/nginx/default.conf:/etc/nginx/conf.d/default.conf
Port mapping:
  • Host port 8000 maps to container port 80
  • Backend API accessible at http://localhost:8000
Configuration highlights:
  • Maximum upload size: 100MB (client_max_body_size 100M)
  • FastCGI connection to app:9000
  • Static file serving from /var/www/public

​
Worker service

Processes queued jobs in the background (emails, file processing, etc.).
docker-compose.yml
worker:
  build:
    context: ./backend
    dockerfile: Dockerfile
  container_name: filebright_worker
  restart: unless-stopped
  command: ["php", "artisan", "queue:work"]
  volumes:
    - ./backend/storage:/var/www/storage
The worker service uses the same Docker image as the app service but runs php artisan queue:work instead of PHP-FPM.

​
Database service (PostgreSQL)

PostgreSQL Alpine provides the relational database.
docker-compose.yml
db:
  image: postgres:alpine
  container_name: filebright_db
  restart: unless-stopped
  environment:
    POSTGRES_DB: ${DB_DATABASE:-filebright}
    POSTGRES_USER: ${DB_USERNAME:-user}
    POSTGRES_PASSWORD: ${DB_PASSWORD:-secret}
  ports:
    - "5432:5432"
  volumes:
    - filebright_db_data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-user} -d ${DB_DATABASE:-filebright}"]
    interval: 10s
    timeout: 5s
    retries: 5
Volume mount:
  • Named volume filebright_db_data persists database data
  • Survives container restarts and rebuilds
Health check:
  • Uses pg_isready to verify database availability
  • App service waits for healthy status before starting

​
Frontend service

Serves the React frontend built with Vite.
docker-compose.yml
frontend:
  build:
    context: ./frontend
    dockerfile: Dockerfile
  container_name: filebright_frontend
  restart: unless-stopped
  ports:
    - "80:80"
Build process:
  • Stage 1: Node 22 Alpine builds the application (npm run build)
  • Stage 2: Nginx Alpine serves static files from /usr/share/nginx/html
Port mapping:
  • Host port 80 maps to container port 80
  • Frontend accessible at http://localhost

​
Starting the application

1

Build images

Build all Docker images:
docker compose build
This builds the app, worker, and frontend services from their respective Dockerfiles.
2

Start services

Start all services in detached mode:
docker compose up -d
Docker Compose will:
  1. Create the filebright_net network
  2. Create the filebright_db_data volume
  3. Start the database and wait for health check
  4. Start app, worker, web, and frontend services
3

Verify deployment

Check that all services are running:
docker compose ps
Expected output shows all five services with “Up” status.
4

View logs

Monitor application logs:
docker compose logs -f

​
Managing the application

​
Stop services

docker compose stop

​
Restart services

docker compose restart

​
Stop and remove containers

docker compose down
This removes containers and networks but preserves volumes. Database data in filebright_db_data persists.

​
Remove volumes

To completely remove all data including the database: 
docker compose down -v
This permanently deletes all database data. Use with caution.

​
Running artisan commands

Execute Laravel artisan commands in the app container: 
docker compose exec app php artisan migrate

​
Volume management

​
Storage volume

The ./backend/storage directory is mounted to both app and worker services: 
volumes:
  - ./backend/storage:/var/www/storage
This directory contains:
  • Uploaded files
  • Application logs
  • Cache files
  • Session data
The entrypoint script automatically sets correct permissions (www-data:www-data) on container start.

​
Database volume

PostgreSQL data persists in the named volume filebright_db_data: 
# List volumes
docker volume ls

# Inspect volume
docker volume inspect filebright_db_data

# Backup volume
docker run --rm -v filebright_db_data:/data -v $(pwd):/backup alpine tar czf /backup/db-backup.tar.gz -C /data .

​
Custom PHP configuration

Customize PHP settings by editing backend/php.ini:
backend/php.ini
upload_max_filesize = 100M
post_max_size = 100M
memory_limit = 256M
max_execution_time = 300
Changes require container restart: 
docker compose restart app worker

​
Network configuration

All services communicate through the filebright_net bridge network: 
networks:
  filebright_net:
    driver: bridge
Services can reference each other by service name:
  • app:9000 - PHP-FPM application
  • db:5432 - PostgreSQL database
  • frontend:80 - React frontend

​
Troubleshooting

​
Container won’t start

Check container logs for errors: 
docker compose logs app
Common issues:
  • Missing or invalid .env file
  • Database connection failure
  • Port conflicts (8000, 80, 5432 already in use)

​
Database connection errors

Verify database health: 
docker compose exec db pg_isready -U user -d filebright
Check environment variables match between .env and docker-compose.yml.

​
Permission errors

The entrypoint script should handle permissions automatically. If issues persist: 
docker compose exec app chown -R www-data:www-data /var/www/storage /var/www/bootstrap/cache
docker compose exec app chmod -R 775 /var/www/storage /var/www/bootstrap/cache

​
Queue jobs not processing

Check worker service status and logs: 
docker compose ps worker
docker compose logs -f worker
Restart worker if needed: 
docker compose restart worker

​
Next steps

Production deployment

Configure Filebright for production environments

Configuration

Learn about environment variables and settings

Build docs developers (and LLMs) love

Get started for freeTalk to us