opnform-host-nginx/NGINX_SETUP.md

OpnForm Nginx Setup Guide

This guide explains how to set up OpnForm with a host-level nginx configuration.

Architecture Overview

The modified setup removes the main nginx ingress container and exposes services directly:

• UI Service: Exposed on port 7655 (HTTP)
• API Service: Exposed on port 7654 (HTTP via minimal nginx container)
• Database: PostgreSQL (internal only)
• Redis: Cache service (internal only)

Key Changes from Default Setup

1. Removed YAML anchors - Each container now has its own explicit configuration to avoid conflicts
2. Removed main ingress container - Your host nginx handles all routing
3. Added minimal api-nginx - Small nginx container just to convert FastCGI to HTTP for the API
4. Custom ports - Using 7654-7655 range to avoid conflicts

Setup Steps

1. Stop any existing containers

docker compose down
docker compose -f docker-compose.dev.yml down

2. Run the setup script

./scripts/docker-setup.sh

3. Verify services are running

docker compose ps

You should see:

• opnform-api (healthy)
• opnform-api-nginx (healthy)
• opnform-api-worker (running)
• opnform-api-scheduler (running)
• opnform-client (healthy)
• opnform-redis (healthy)
• opnform-db (healthy)

4. Configure your host nginx

Copy the example configuration:

sudo cp nginx-host-example.conf /etc/nginx/sites-available/forms.portnimara.dev
sudo ln -s /etc/nginx/sites-available/forms.portnimara.dev /etc/nginx/sites-enabled/

Edit the file to adjust:

• SSL certificate paths
• Server name if different
• Any other site-specific settings

5. Test nginx configuration

sudo nginx -t

6. Reload nginx

sudo systemctl reload nginx

Troubleshooting

Port already in use

If you get "port already allocated" errors:

1. Check what's using the ports:

   sudo lsof -i :7654
   sudo lsof -i :7655
   

2. Stop conflicting services or change the ports in docker-compose.yml

API not responding

1. Check the api-nginx logs:

   docker logs opnform-api-nginx
   

2. Verify the API container is running:

   docker logs opnform-api
   

UI not loading

1. Check the client logs:

   docker logs opnform-client
   

2. Ensure the client/.env file has correct API URL settings

Port Reference

• 7654: API (HTTP) - proxied through api-nginx to PHP-FPM
• 7655: UI (HTTP) - Nuxt.js frontend
• 9000: PHP-FPM (internal only, FastCGI protocol)
• 5432: PostgreSQL (internal only)
• 6379: Redis (internal only)

Security Notes

1. Ports are bound to 127.0.0.1 only, not exposed to external network
2. All traffic should go through your host nginx with SSL
3. The minimal api-nginx container only handles FastCGI conversion, no SSL termination

Default Credentials

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

Important: Change these immediately after first login!