Skip to content
Klutch.sh Docs

Deploying an Omeka App

Introduction

Omeka is an open-source web publishing platform for sharing digital collections and archives. Deploying Omeka with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for uploads and configuration—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Omeka code and Dockerfile (GitHub is the only supported git source)
  • A MySQL/MariaDB database (deploy as a Klutch.sh TCP app on port 8000 and connect on 3306)
  • Domain and TLS for secure access

For onboarding, see the Quick Start.

Architecture and ports

  • Omeka runs on PHP/Apache; set the internal container port to 8080 and choose HTTP traffic.
  • Database runs separately on TCP; connect on 3306.
  • Persistent storage is required for uploaded files and configuration.

Repository layout

omeka/
├── Dockerfile                 # Must be at repo root for auto-detection
├── files/                     # Uploaded files (persist)
├── config/                    # Config (persist)
└── README.md

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
docker build -t omeka-local .
docker run -p 8080:8080 --env-file .env omeka-local

Dockerfile for Omeka (production-ready)

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

FROM php:8.1-apache


ENV APACHE_HTTP_PORT_NUMBER=8080


WORKDIR /var/www/html


RUN apt-get update && apt-get install -y --no-install-recommends \
    libpng-dev libjpeg-dev libzip-dev libxml2-dev unzip git \
    && docker-php-ext-configure gd --with-jpeg \
    && docker-php-ext-install gd mysqli zip intl xmlrpc soap opcache \
    && a2enmod rewrite \
    && sed -i 's/80/${APACHE_HTTP_PORT_NUMBER}/g' /etc/apache2/ports.conf /etc/apache2/sites-available/000-default.conf \
    && rm -rf /var/lib/apt/lists/*


COPY . .


RUN mkdir -p files config && chown -R www-data:www-data /var/www/html


EXPOSE 8080
CMD ["apache2-foreground"]

Notes:

  • Add PHP extensions if your plugins require them.
  • Keep files/ and config/ writable; mount them as volumes.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • OMEKA_BASE_URL=https://example-app.klutch.sh
  • DB_HOST=<db-host>
  • DB_PORT=3306
  • DB_NAME=<db-name>
  • DB_USER=<db-user>
  • DB_PASSWORD=<db-password>
  • DB_DRIVER=mysqli
  • APACHE_HTTP_PORT_NUMBER=8080
  • Optional SMTP: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_SECURE

If you deploy without the Dockerfile and need Nixpacks overrides (PHP):

  • NIXPACKS_PHP_VERSION=8.1
  • NIXPACKS_START_CMD=apache2-foreground

Attach persistent volumes

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

  • /var/www/html/files — uploaded media and assets.
  • /var/www/html/config — configuration and settings.

Ensure these paths are writable inside the container.

Deploy Omeka 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.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including database and optional SMTP settings.
  5. Attach persistent volumes for /var/www/html/files and /var/www/html/config sized for your media and configuration.
  6. Deploy. Complete the Omeka web installer at https://example-app.klutch.sh and connect to your database.

Sample usage

Check reachability:

Terminal window
curl -I https://example-app.klutch.sh

After setup, manage collections, items, and exhibits via the web UI or REST API (if enabled).

Health checks and production tips

  • Add an HTTP probe to / or a lightweight status route once configured.
  • Enforce HTTPS at the edge; forward internally to port 8080.
  • Keep DB and SMTP credentials in Klutch.sh secrets; rotate them regularly.
  • Monitor volume usage for files/ and config/; resize before they fill.
  • Pin image versions and test upgrades in staging; back up data and DB before updates.

Omeka 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 8080 configured, and MySQL/MariaDB connected, you can publish digital collections without extra YAML or workflow overhead.