Docker Development Setup

Documentation Index

Fetch the complete documentation index at: https://docs.opnform.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Prerequisites

• Docker and Docker Compose installed on your machine
• Git installed
• Basic understanding of Docker concepts

​

Quick Start

1. Clone the repository:
   git clone https://github.com/OpnForm/OpnForm.git
   cd OpnForm
   
2. Run the setup script in development mode:
   chmod +x scripts/docker-setup.sh
   ./scripts/docker-setup.sh --dev
   
   This script will:
   • Pull or build required Docker images
   • Start all containers in development mode with embedded configuration
   • Display access information
   Development mode doesn’t require .env files - all configuration is embedded in docker-compose.dev.yml for simplicity.
3. Access your development environment:
   • Frontend: http://localhost:3000 (direct access to Nuxt dev server)
   • API: http://localhost/api (proxied through nginx)

​

Initial Setup

​

Architecture

​

Key Simplifications

• No .env Files: All configuration embedded in docker-compose.dev.yml - no environment file generation needed
• Direct Frontend Access: Frontend runs on port 3000 with direct access, bypassing nginx proxy
• Lightweight nginx: Only handles API routes and Laravel backend, eliminating redundant frontend proxying
• Simplified networking: Fewer moving parts, cleaner logs, easier debugging

​

Differences from Production

• No Redis: Uses file-based caching and sessions instead
  • Simpler setup
  • No additional service to maintain
  • Slightly slower but sufficient for development
• No Queue Workers: Uses synchronous job processing
  • Jobs run immediately in the main process
  • Easier debugging of background tasks
  • No need to restart workers after code changes
• No Scheduler: Scheduled tasks don’t run automatically
  • Run scheduled tasks manually when needed
  • Less resource usage
  • Cleaner logs
• Embedded Configuration: No .env files needed
  • All variables set directly in docker-compose.dev.yml
  • Includes secure development keys (APP_KEY, JWT_SECRET)
  • Pre-configured mail settings using log driver
  • Immediate startup without setup scripts

​

Development Features

​

Frontend Development

• Hot Module Replacement (HMR): Changes to Vue components and styles are instantly reflected without page reload
• Vue DevTools: Full integration for component inspection and state management debugging (learn more)
• Source Maps: Enabled for easier debugging
• Fast Refresh: Preserves component state during updates
• Error Overlay: Displays errors directly in the browser

​

Backend Development

• PHP Hot Reload: Changes to PHP files are immediately available
• Xdebug Integration: Ready for step-by-step debugging
• Artisan Commands: Direct access to Laravel’s CLI tools

​

Performance Optimizations

• Smart Dependency Install: Automatically detects when package.json has changed and only reinstalls when necessary
  • First startup: Full npm install (2-3 minutes)
  • Subsequent startups: “Dependencies up to date, skipping install” (5 seconds)
  • Automatic detection when dependencies change
• Persistent Node Modules: Dependencies stored in Docker volumes to avoid reinstallation
• Fast Container Restarts: Skip dependency installation on container restart

​

Development URLs

• Frontend: http://localhost:3000
  • Direct access to Nuxt dev server with HMR
  • Vue DevTools available
  • All client-side routing handled directly
• API: http://localhost/api
  • Lightweight nginx proxy to Laravel API
  • Routes all backend requests through Laravel’s front controller
  • PHP-FPM processing for server-side logic
  • Supports file uploads and long requests

​

File Structure

OpnForm/
├── api/                    # Laravel API (mounted to api container)
│   ├── vendor/            # Preserved in container
│   └── storage/           # Mounted for logs and uploads
├── client/                # Nuxt frontend (mounted to ui container)
│   └── node_modules/      # Preserved in container
└── docker/                # Docker configuration files

​

Common Tasks

​

Running Commands

# Laravel Artisan commands
docker compose -f docker-compose.dev.yml exec api php artisan [command]

# NPM commands
docker compose -f docker-compose.dev.yml exec ui npm [command]

# Database commands
docker compose -f docker-compose.dev.yml exec db psql -U forge

​

Accessing Logs

# All containers
docker compose -f docker-compose.dev.yml logs -f

# Specific container (e.g., frontend)
docker compose -f docker-compose.dev.yml logs -f ui

​

Database Access

• From containers: host=db
• From your machine: localhost:5432
• Default credentials:
  Host: localhost
  Port: 5432
  Database: forge
  Username: forge
  Password: forge
  

​

Troubleshooting

​

Container Issues

# Clean everything and restart
./scripts/docker-setup.sh --dev

​

Frontend Access Issues

docker compose -f docker-compose.dev.yml restart ui

​

Environment Variables

• APP_KEY and JWT_SECRET: Pre-configured development keys
• Database: Defaults to forge/forge credentials
• Mail: Uses log driver for development
• Storage: Local filesystem with public visibility

​

Permission Issues

# Fix storage permissions
docker compose -f docker-compose.dev.yml exec api chmod -R 775 storage

# Fix vendor permissions
docker compose -f docker-compose.dev.yml exec api chmod -R 775 vendor

​

HMR Issues

1. Check browser console for WebSocket errors
2. Ensure ports 3000 and 24678 are available
3. Try restarting the UI container:
   docker compose -f docker-compose.dev.yml restart ui
   

​

Dependency Installation Issues

# Remove the install marker to force reinstall
docker compose -f docker-compose.dev.yml exec ui rm -f node_modules/.install-complete

# Or clear the entire volume
docker volume rm opnform_client_node_modules

​

Environment Variables