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.

Looking to develop OpnForm locally? Check out our Docker Development Setup guide which provides hot-reload and other development features.

​
Quick Start

  1. Clone the repository: 
    git clone https://github.com/JhumanJ/OpnForm.git
cd OpnForm

Important for Windows Users: Ensure script files maintain LF (Unix-style) line endings. If you’re using Windows, configure Git to preserve line endings:

git config core.autocrlf false

And check/fix the artisan script before running setup:

# Using Git Bash or WSL
dos2unix api/artisan

Otherwise, Docker containers may hang at “Waiting for DB to be ready” during startup.

  1. Run the setup script:

    chmod +x scripts/docker-setup.sh
./scripts/docker-setup.sh

    The script will:

    • Create necessary environment files
    • Pull required Docker images
    • Start all containers in production mode
    • Display access information

  2. Access your OpnForm instance at http://localhost

​
Initial Login

After deployment, use these credentials to access the app:

  • Email: admin@opnform.com
  • Password: password

You will be prompted to change your email and password after your first login.

Public registration is disabled in the self-hosted version. Use the admin account to invite additional users.

​
Architecture

​
Components

The Nuxt frontend service:

  • Server-Side Rendered application
  • Built with Vue 3 and Tailwind CSS
  • Handles dynamic rendering and client-side interactivity
  • Optimized for production performance

​
Docker Images

OpnForm provides pre-built Docker images for easy deployment:

​
Building Custom Images

While we recommend using the official images, you can build custom images if needed:

# Build all images
docker compose build

# Or build specific images
docker build -t opnform-api:local -f docker/Dockerfile.api .
docker build -t opnform-ui:local -f docker/Dockerfile.client .

​
Custom Configuration

Create a docker-compose.override.yml to customize your deployment:

services:
  api:
    image: opnform-api:local
    environment:
      PHP_MEMORY_LIMIT: 1G
  ui:
    image: opnform-ui:local
  ingress:
    volumes:
      - ./custom-nginx.conf:/etc/nginx/conf.d/default.conf

​
Environment Variables

For detailed information about environment variables and how to update them in Docker, see our Environment Variables documentation.

​
Maintenance

​
Updates

  1. Pull latest changes:

    git pull origin main

  2. Update containers:

    docker compose pull
docker compose up -d

​
Monitoring

View container logs:

# All containers
docker compose logs -f

# Specific container
docker compose logs -f api

Monitor container health:

docker compose ps

​
Troubleshooting

​
Container Issues

If containers aren’t starting:

# View detailed logs
docker compose logs -f

# Recreate containers
docker compose down
docker compose up -d

​
Database Issues

If database connections fail:

# Check database status
docker compose exec db pg_isready

# View database logs
docker compose logs db

If the API container is stuck on “Waiting for DB to be ready”:

# Check for line ending issues in the artisan script
# The file should use LF (Unix) line endings, not CRLF (Windows)

# Fix line endings on Unix/Mac:
sed -i 's/\r$//' api/artisan

# Fix line endings on Windows (using Git Bash or WSL):
dos2unix api/artisan

Line Ending Issue: When using Git or code editors on Windows, line endings in the artisan script may be converted from LF (Unix-style) to CRLF (Windows-style). This prevents the Docker container from properly executing the script, causing it to hang at “Waiting for DB to be ready”. Always ensure script files maintain LF line endings.

​
Cache Issues

Clear various caches:

# Clear application cache
docker compose exec api php artisan cache:clear

# Clear config cache
docker compose exec api php artisan config:clear

# Clear route cache
docker compose exec api php artisan route:clear

​
Permission Issues

Fix storage permissions:

docker compose exec api chown -R www-data:www-data storage
docker compose exec api chmod -R 775 storage