Skip to content
Klutch.sh Docs

Deploying an OpnForm App

Introduction

OpnForm is an open-source form builder built on Laravel and Vue/React. Deploying OpnForm with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for uploads and cache—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your OpnForm code and Dockerfile (GitHub is the only supported git source)
  • MySQL/PostgreSQL database (deploy as a Klutch.sh TCP app on port 8000; connect on native port)
  • Redis (optional) for queues/cache (deploy as TCP on port 8000; connect on 6379)
  • Domain and TLS for secure access

For onboarding, see the Quick Start.

Architecture and ports

  • OpnForm serves HTTP on internal port 8000; choose HTTP traffic.
  • Database and Redis run externally over TCP.
  • Persistent storage is required for uploads and cache.

Repository layout

opnform/
├── Dockerfile              # Must be at repo root for auto-detection
├── composer.json
├── package.json
├── .env.example            # Template only; no secrets
└── storage/                # Laravel storage (persist)

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
composer install --no-dev
php artisan key:generate
php artisan migrate --force
npm install
npm run build
php artisan serve --host 0.0.0.0 --port 8000

Dockerfile for OpnForm (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM php:8.2-fpm-alpine AS backend


WORKDIR /var/www/html


RUN apk add --no-cache git zip unzip libpng-dev libjpeg-turbo-dev libzip-dev oniguruma-dev icu-dev \
    && docker-php-ext-configure gd --with-jpeg \
    && docker-php-ext-install pdo pdo_mysql pdo_pgsql gd intl zip opcache


COPY composer.json composer.lock ./
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
RUN composer install --no-dev --optimize-autoloader


COPY . .
RUN php artisan config:cache && php artisan route:cache && php artisan view:cache


FROM node:18-alpine AS frontend
WORKDIR /app
COPY package.json pnpm-lock.yaml* yarn.lock* package-lock.json* ./
RUN corepack enable
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build


FROM nginx:alpine


ENV PORT=8000


WORKDIR /var/www/html
COPY --from=backend /var/www/html /var/www/html
COPY --from=frontend /app/public /var/www/html/public


RUN apk add --no-cache bash \
    && rm -rf /etc/nginx/conf.d/default.conf


COPY ./nginx.conf /etc/nginx/conf.d/default.conf


EXPOSE 8000
CMD ["nginx", "-g", "daemon off;"]

Example nginx.conf (place alongside Dockerfile):

server {
    listen 8000;
    server_name _;
    root /var/www/html/public;


    add_header X-Frame-Options SAMEORIGIN;
    add_header X-Content-Type-Options nosniff;


    index index.php index.html;


    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }


    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

Notes:

  • Pin image versions for stability; adjust DB extensions (pdo_pgsql or pdo_mysql) to match your database.
  • Ensure PHP-FPM socket path matches your base image; adjust fastcgi_pass if needed.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • APP_ENV=production
  • APP_URL=https://example-app.klutch.sh
  • APP_KEY=<generated via php artisan key:generate>
  • Database (choose one):
    • MySQL: DB_CONNECTION=mysql, DB_HOST=<host>, DB_PORT=3306, DB_DATABASE=<db>, DB_USERNAME=<user>, DB_PASSWORD=<password>
    • PostgreSQL: DB_CONNECTION=pgsql, DB_PORT=5432, plus host/db/user/password
  • Redis (optional): REDIS_HOST=<redis-host>, REDIS_PORT=6379, REDIS_PASSWORD=<password>
  • Storage: FILESYSTEM_DISK=public (or s3), APP_PORT=8000
  • Mail (optional): MAIL_MAILER=smtp, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=composer install --no-dev --optimize-autoloader && php artisan config:cache && php artisan route:cache && php artisan view:cache
  • NIXPACKS_START_CMD=php artisan serve --host 0.0.0.0 --port 8000
  • NIXPACKS_PHP_VERSION=8.2
  • NIXPACKS_NODE_VERSION=18

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/www/html/storage — uploads, cache, logs.
  • /var/www/html/public — built assets if you want to persist them (optional).

Ensure these paths are writable inside the container.

Deploy OpnForm on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile (and nginx.conf) at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8000.
  4. Add the environment variables above, including database, Redis (optional), APP_KEY, and mail settings.
  5. Attach persistent volumes for /var/www/html/storage (and optionally /var/www/html/public) sized for your uploads and cache.
  6. Deploy. Complete any post-deploy migrations via a one-off task: php artisan migrate --force if not run during build.

Sample API usage

List forms (adjust route/token per your setup):

Terminal window
curl -X GET "https://example-app.klutch.sh/api/forms" \
  -H "Authorization: Bearer <token>"
``>


Create a form:


```bash
curl -X POST "https://example-app.klutch.sh/api/forms" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Klutch Feedback","description":"Collect user feedback"}'

Health checks and production tips

  • Add an HTTP probe to / or /health (if you expose one) for readiness.
  • Enforce HTTPS at the edge; forward internally to port 8000.
  • Keep APP_KEY, DB, Redis, and mail credentials in Klutch.sh secrets; rotate them regularly.
  • Monitor storage usage on /var/www/html/storage; resize before it fills.
  • Pin image versions and test upgrades in staging; back up DB and storage before updates.

OpnForm on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8000 configured, and your database connected, you can deliver secure form-building experiences without extra YAML or workflow overhead.