Skip to content
Klutch.sh Docs

Deploying a Magento App

Introduction

Magento is a powerful open-source e-commerce platform built on PHP. Deploying Magento with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for media and caches—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample configuration, and production tips.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Magento code (GitHub is the only supported git source)
  • Docker familiarity and PHP 8.1+ knowledge
  • Database credentials (MySQL/MariaDB) and Redis for cache/session
  • Storage for media, var/cache, and generated assets

For onboarding, see the Quick Start.

Architecture and ports

  • Serve Magento over HTTP; set the internal container port to 8080 (adjust if your start command differs).
  • MySQL/MariaDB and Redis should run as separate Klutch.sh TCP apps. Expose them on port 8000 and connect internally on 3306 (MySQL/MariaDB) and 6379 (Redis).
  • Persistent storage is required for pub/media, var/, and recommended for generated/.

Repository layout

magento/
├── app/                    # Magento application code
├── pub/                    # Public assets
├── var/                    # Cache, sessions, reports (mount as volume)
├── generated/              # Generated classes (optional 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 run locally before pushing to GitHub:

Terminal window
composer install --no-dev --optimize-autoloader
bin/magento setup:upgrade
bin/magento cache:flush
php -S 0.0.0.0:8080 -t pub

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
bin/magento setup:upgrade
exec php -S 0.0.0.0:8080 -t pub

Make it executable with chmod +x start.sh.

Dockerfile for Magento (production-ready)

Place this Dockerfile at the repository 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 libxml2-dev libonig-dev libxslt1-dev git unzip \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install pdo_mysql gd intl zip opcache soap xsl bcmath \
    && 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 && \
    bin/magento setup:di:compile && \
    bin/magento setup:static-content:deploy -f && \
    chown -R www-data:www-data /var/www/html


ENV PORT=8080


EXPOSE 8080
CMD ["apache2-foreground"]

Notes:

  • Includes common Magento extensions; adjust if you add Elasticsearch or additional PHP modules.
  • Ensure writable permissions for pub/media, var/, and generated/.

Environment variables (Klutch.sh)

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

  • PORT=8080
  • DB_HOST=<db-host>
  • DB_NAME=<db-name>
  • DB_USER=<db-user>
  • DB_PASSWORD=<db-password>
  • DB_PREFIX= (optional)
  • REDIS_HOST=<redis-host>
  • REDIS_PORT=6379
  • MAGENTO_MODE=production
  • MAGENTO_BASE_URL=https://example-app.klutch.sh
  • ADMIN_EMAIL, ADMIN_USER, ADMIN_PASSWORD (for initial admin setup)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=composer install --no-dev --optimize-autoloader && bin/magento setup:di:compile && bin/magento setup:static-content:deploy -f
  • NIXPACKS_START_CMD=php -S 0.0.0.0:8080 -t pub
  • NIXPACKS_INSTALL_PKGS="php82 php82Extensions.pdo_mysql php82Extensions.intl php82Extensions.gd php82Extensions.zip php82Extensions.soap php82Extensions.xsl php82Extensions.bcmath"

These keep Magento 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/pub/media — required for media and uploads.
  • /var/www/html/var — cache, sessions, reports.
  • /var/www/html/generated — optional if you want to persist generated classes.

Ensure these paths are writable inside the container.

Deploy Magento 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 Magento.
  3. Set the internal port to 8080.
  4. Add the environment variables above (database, Redis, Magento base URL, admin credentials, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /var/www/html/pub/media, /var/www/html/var, and optionally /var/www/html/generated, selecting sizes that fit your catalog and cache needs.
  6. Deploy. Your Magento store will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For MySQL/Redis on Klutch.sh, create separate TCP apps, expose them on port 8000, and point Magento env vars to those endpoints (internal ports 3306/6379).

Sample configuration snippet

Example app/etc/env.php snippet using environment variables (inject via your deployment):

return [
    'backend' => ['frontName' => 'admin'],
    'db' => [
        'connection' => [
            'default' => [
                'host' => getenv('DB_HOST'),
                'dbname' => getenv('DB_NAME'),
                'username' => getenv('DB_USER'),
                'password' => getenv('DB_PASSWORD'),
                'model' => 'mysql4',
                'engine' => 'innodb',
                'initStatements' => 'SET NAMES utf8;',
            ],
        ],
    ],
    'cache' => [
        'frontend' => [
            'default' => [
                'backend' => 'Cm_Cache_Backend_Redis',
                'backend_options' => ['server' => getenv('REDIS_HOST'), 'port' => getenv('REDIS_PORT')],
            ],
        ],
    ],
];

Health checks and production tips

  • Add a reverse proxy probe to / or a lightweight status page to verify availability.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Keep image tags and PHP extension versions pinned; upgrade intentionally with backups.
  • Monitor disk usage on media/cache volumes and resize before they fill.
  • Back up your database and media regularly; do not rely on container storage alone.
  • Tune Redis caching and Magento modes (production) for performance.

Magento on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage for media and cache, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 8080 configured, you can launch a scalable store without extra YAML or workflow overhead.