Docker Deployment

The easiest way to get started with OpnForm is through our official managed service in the Cloud. It takes just 1 minute to start building forms with the free plan, 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

Clone the repository:

git clone https://github.com/OpnForm/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: bash git config core.autocrlf false And check/fix the artisan script before running setup: bash # Using Git Bash or WSL dos2unix api/artisan Otherwise, Docker containers may hang at “Waiting for DB to be ready” during startup.

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
Access your OpnForm instance at http://localhost

Configure your public instance URL

The setup script creates the environment files, but it cannot know the public domain where your instance will be available. Before configuring OIDC, OAuth, or using the instance in production, set the public URL in both files:

File	Required variables
`api/.env`	`APP_URL` and `FRONT_URL`
`client/.env`	`NUXT_PUBLIC_APP_URL` and `NUXT_PUBLIC_API_BASE`

For example, an instance available at https://forms.example.com uses https://forms.example.com for APP_URL, FRONT_URL, and NUXT_PUBLIC_APP_URL, plus https://forms.example.com/api for NUXT_PUBLIC_API_BASE. After changing these variables, recreate the containers; docker compose restart does not load new environment values.

docker compose down
docker compose up -d

See Public instance URL for the complete example and OIDC SSO Configuration before setting up SSO.

If a reverse proxy is in front of OpnForm

When Caddy, Traefik, Cloudflare, or another reverse proxy forwards traffic to the Docker ingress, set TRUSTED_PROXIES in api/.env to the IP address or CIDR range from which that proxy connects to the ingress. This lets OpnForm use the real client IP for OIDC and other rate limits.

# Example only: use the actual address or CIDR of your own reverse proxy.
TRUSTED_PROXIES=192.0.2.10,2001:db8:1234::/48

Leave it empty when users connect directly to the Docker ingress. Do not set it to *: doing so would make a direct client-provided forwarding header trustworthy and allow rate-limit bypasses. Recreate the API container after changing it.

Initial Setup

After deployment, OpnForm will automatically redirect you to a setup page where you can create your admin account. Simply visit http://localhost 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. Free self-hosted instances are limited to 2 users total across the instance; activate a self-hosted Enterprise license to add more users.

A self-hosted Enterprise license is optional. Core self-hosted OpnForm works without a license, including OIDC within the free 2-user limit. Adding more users and advanced Enterprise features require license activation. See Self-hosted License.

Architecture

Components

Frontend
Backend
Workers
Databases
Proxy

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

Pull latest changes:
git pull origin main

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

Get Started

Features

Deployment

Self-hosted Enterprise

Configuration

Embedding

Quick Start

Configure your public instance URL

If a reverse proxy is in front of OpnForm

Initial Setup

Architecture

Components

Docker Images

Building Custom Images

Custom Configuration

Environment Variables

Maintenance

Updates

Monitoring

Troubleshooting

Container Issues

Database Issues

Cache Issues

Permission Issues

​Quick Start

​Configure your public instance URL

​If a reverse proxy is in front of OpnForm

​Initial Setup

​Architecture

​Components

​Docker Images

​Building Custom Images

​Custom Configuration

​Environment Variables

​Maintenance

​Updates

​Monitoring

​Troubleshooting

​Container Issues

​Database Issues

​Cache Issues

​Permission Issues

Quick Start

Configure your public instance URL

If a reverse proxy is in front of OpnForm

Initial Setup

Architecture

Components

Docker Images

Building Custom Images

Custom Configuration

Environment Variables

Maintenance

Updates

Monitoring

Troubleshooting

Container Issues

Database Issues

Cache Issues

Permission Issues