Skip to content
Klutch.sh Docs

Deploying a KBIN App

Introduction

KBIN is an open-source federated content platform built with PHP and Symfony. Deploying KBIN with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for user-generated content—all orchestrated from klutch.sh/app. This guide covers installation, repository preparation, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for performance and durability.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your KBIN code/config (GitHub is the only supported git source)
  • Docker familiarity and PHP 8.1+ knowledge
  • PostgreSQL (or MySQL) and Redis credentials
  • Storage for media uploads and cache

For onboarding, see the Quick Start.

Architecture and ports

  • KBIN serves HTTP; set the internal container port to 8080.
  • PostgreSQL and Redis should run as separate Klutch.sh TCP apps. Expose them on port 8000 and connect internally on 5432 (Postgres) and 6379 (Redis).
  • Persistent storage is required for media uploads and cache directories.

Repository layout

kbin/
├── public/                 # Web root
├── var/                    # Cache, logs (mount parts as needed)
├── media/                  # User uploads (mount as volume)
├── Dockerfile              # Must be at repo root for auto-detection
├── composer.json
├── composer.lock
└── .env.example            # Template only; no secrets

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

Installation (local) and starter commands

Install dependencies and test locally before pushing to GitHub:

Terminal window
composer install --no-dev --optimize-autoloader
php bin/console doctrine:migrations:migrate --no-interaction
php -S 0.0.0.0:8080 -t public

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
php bin/console doctrine:migrations:migrate --no-interaction
exec php -S 0.0.0.0:8080 -t public

Make it executable with chmod +x start.sh.

Dockerfile for KBIN (production-ready)

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

FROM php:8.2-apache


RUN apt-get update && apt-get install -y \
    libpng-dev libjpeg-dev libfreetype6-dev libzip-dev libicu-dev libonig-dev git unzip \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install pdo_pgsql pdo_mysql gd intl zip opcache \
    && a2enmod rewrite \
    && rm -rf /var/lib/apt/lists/*


WORKDIR /var/www/html


COPY . /var/www/html


RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer && \
    composer install --no-dev --optimize-autoloader && \
    chown -R www-data:www-data /var/www/html


ENV PORT=8080


EXPOSE 8080
CMD ["apache2-foreground"]

Notes:

  • Include pdo_pgsql or pdo_mysql depending on your database; the example installs both.
  • Keep media/ writable and on a volume.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • APP_ENV=prod
  • APP_SECRET=<secure-app-secret>
  • DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<db> (or mysql://)
  • REDIS_URL=redis://<user>:<password>@<host>:<port>
  • APP_URL=https://example-app.klutch.sh
  • MAILER_DSN=<mailer-dsn> (if sending mail)
  • PORT=8080

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=composer install --no-dev --optimize-autoloader
  • NIXPACKS_START_CMD=php -S 0.0.0.0:8080 -t public
  • NIXPACKS_INSTALL_PKGS="php82 php82Extensions.pdo_pgsql php82Extensions.pdo_mysql php82Extensions.intl php82Extensions.gd php82Extensions.zip"

These keep KBIN compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

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

  • /var/www/html/media — user uploads.
  • /var/www/html/var/cache — cache (optional; improves warm starts).
  • /var/www/html/var/log — logs (optional).

Ensure these paths are writable inside the container.

Deploy KBIN on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for KBIN.
  3. Set the internal port to 8080.
  4. Add the environment variables above (database, Redis, app secret, mailer, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /var/www/html/media (and /var/www/html/var/cache or /var/www/html/var/log if used), choosing sizes that fit your content and cache needs.
  6. Deploy. Your KBIN instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For PostgreSQL/Redis on Klutch.sh, create separate TCP apps, expose them on port 8000, and point DATABASE_URL or REDIS_URL to those endpoints (internal ports 5432/6379).

Health checks and production tips

  • Add a lightweight status route or reuse an existing page for uptime monitoring.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Keep dependencies pinned and update intentionally to avoid regressions.
  • Monitor storage usage on media/cache volumes and resize before they fill.
  • Back up your database and media regularly; do not rely on container filesystems for durability.

KBIN on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage for media, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8080 for the app (8000 externally for TCP databases or caches), you can run a reliable federated content platform without extra YAML or workflow overhead.