The easiest way to get started with OpnForm is through our official managed service in the Cloud. It takes just 1 minute to try out the builder for free, with high availability, backups, security, and maintenance all managed for you.

​
Overview

OpnForm provides a minimal Docker-based development environment optimized for local development. While the full architecture is detailed in our Docker Deployment guide, the development setup is intentionally lighter and focused on developer experience.

​
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/JhumanJ/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:

​
Initial Setup

After starting the development environment, OpnForm will automatically redirect you to a setup page where you can create your admin account. Simply visit http://localhost:3000/setup and you’ll be guided through the setup process.
Public registration is disabled in the self-hosted version after setup is complete. Use the admin account to invite additional users.

​
Architecture

The development setup is intentionally simplified compared to our Docker Deployment production setup, with a focus on developer experience and faster iteration.

​
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

The development setup includes:

​
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

The development setup includes smart optimizations for faster iteration:
  • 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
In development, nginx handles all Laravel routes (including /, /api/*, /forms/*) through the standard Laravel front controller pattern. The frontend is accessed directly on port 3000, eliminating redundant proxying.

​
File Structure

The development setup mounts your local directories into the containers: 
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

To run commands in the containers: 
# 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

View container 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

The PostgreSQL database is accessible:
  • From containers: host=db
  • From your machine: localhost:5432
  • Default credentials: 
    Host: localhost
Port: 5432
Database: forge
Username: forge
Password: forge

​
Troubleshooting

​
Container Issues

If containers aren’t starting properly: 
# Clean everything and restart
./scripts/docker-setup.sh --dev

​
Frontend Access Issues

If you get 503 errors when accessing the frontend:
1

Use IPv4 address

Always use http://127.0.0.1:3000 instead of http://localhost:3000
localhost can resolve to IPv6 (::1) on some systems, causing connection issues with Docker’s port binding.
2

Check container logs

Verify the Nuxt dev server started successfully: bash docker compose -f docker-compose.dev.yml logs ui Look for: "Dependencies up to date, skipping install" and "➜ Local: http://0.0.0.0:3000/"
3

Restart containers if needed

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

​
Environment Variables

Development mode uses embedded configuration - no .env files needed:
  • 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
To customize variables, edit them directly in docker-compose.dev.yml.

​
Permission Issues

If you encounter 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

If hot reload isn’t working:
  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

If you need to force reinstall dependencies: 
# 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

For production deployments, see our Environment Variables documentation.
Development mode doesn’t use .env files. All configuration is embedded in docker-compose.dev.yml for simplicity. To modify variables, edit the environment: section directly in that file.