erseco/alpine-omeka-s repository overview

⁠Omeka S on Alpine Linux

A lightweight and secure Omeka S setup for Docker, built on Alpine Linux. This image is optimized for performance and size, making it an ideal choice for development and production environments.

Repository: https://github.com/erseco/alpine-omeka-s⁠

⁠Key Features

• Lightweight: Built on the erseco/alpine-php-webserver base image for a minimal footprint (+/- 70MB).
• Performant: Uses PHP-FPM with an ondemand process manager to optimize resource usage.
• Secure: Services run under a non-privileged user (nobody). Logs are directed to the container's STDOUT.
• Multi-Arch Support: amd64, arm/v6, arm/v7, arm64, ppc64le, s390x.
• Configurable: Easily configure the container using environment variables.
• Extensible: Automatically install themes and modules on startup.
• SQLite (experimental): Run Omeka S in a single container, without a database service, for development, demos and CI.
• Simple & Transparent: Follows the KISS principle for easy understanding and customization.

⁠Usage

Here is a minimal docker-compose.yml example to get you started:

---
services:
  mariadb:
    image: mariadb:lts
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=omeka_s
      - MYSQL_DATABASE=omeka_s
      - MYSQL_USER=omeka_s
      - MYSQL_PASSWORD=omeka_s
    volumes:
      - mariadb_data:/var/lib/mysql

  omeka-s:
    image: erseco/alpine-omeka-s:latest
    build:
      context: .
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      # Omeka S Installation Details
      OMEKA_ADMIN_EMAIL: [email protected]
      OMEKA_ADMIN_PASSWORD: PLEASE_CHANGEME
      OMEKA_SITE_TITLE: "My Omeka S Site"
      # Database Connection
      DB_HOST: mariadb
      DB_NAME: omeka_s
      DB_USER: omeka_s
      DB_PASSWORD: omeka_s
    volumes:
      - omeka_data:/var/www/html/volume
    depends_on:
      - mariadb

volumes:
  mariadb_data: null
  omeka_data: null

To start the services, run:

docker compose up

Once the container is running, Omeka S will be installed and accessible at http://localhost:8080.

⁠Image tags

Use a minor tag (4.2) to get the image fixes and features as they land, or a vX.Y.Z tag to pin a build.

⁠Configuration

You can configure the container using the following environment variables in your docker-compose.yml file.

⁠Build Arguments

Pinning OMEKA_CLI_VERSION keeps image builds reproducible while still allowing explicit CLI upgrades (update OMEKA_CLI_SHA256 with it).

⁠Omeka S Installation

Note: The Omeka S installation will only run if OMEKA_ADMIN_EMAIL, OMEKA_ADMIN_PASSWORD, and OMEKA_SITE_TITLE are all set.

⁠Automatic CSV Import

If you specify the OMEKA_CSV_IMPORT_FILE environment variable, the container will automatically import data from the given CSV file at startup.

Example:

environment:
  OMEKA_CSV_IMPORT_FILE: /path/to/your/data.csv

The CSV file should be mounted into the container. For example, you can add this to your docker-compose.yml:

volumes:
  - ./my-data.csv:/path/to/your/data.csv

CSV Format Recommendations:

• Encoding: The file must be UTF-8 encoded.
• Headers: Use headers that match Omeka S properties, like dcterms:title, dcterms:creator, etc., for automatic mapping.
• For more details, refer to the official Omeka S CSV Import documentation⁠.

⁠Database Connection

⁠PHP & Webserver

⁠Other Configuration variables

jq is available in both hooks, for example to parse omeka-s-cli ... --json output.

⁠Advanced Features

⁠OPcache Configuration for Development

By default, the image uses production-optimized OPcache settings that do not validate file timestamps, which provides maximum performance but prevents code changes from being immediately visible (requires container restart).

For development workflows where you need code changes to be reflected immediately (e.g., when developing Omeka S modules with mounted volumes), you can enable OPcache timestamp validation using either of these methods:

Option 1: Using OPCACHE_ENABLE variable

environment:
  OPCACHE_ENABLE: "0"  # Configures OPcache for development (enables timestamp validation)

Option 2: Using APPLICATION_ENV variable

environment:
  APPLICATION_ENV: development  # Auto-enables timestamp validation

When either OPCACHE_ENABLE=0 or APPLICATION_ENV=development is set, the container will configure OPcache to validate file timestamps on every request (opcache.validate_timestamps=1 and opcache.revalidate_freq=0), allowing code changes to be immediately visible without restarting the container.

Production mode (default):

• opcache.enable=1
• opcache.validate_timestamps=0 (no timestamp checking for maximum performance)

Development mode:

• opcache.enable=1
• opcache.validate_timestamps=1 (checks files on every request)
• opcache.revalidate_freq=0 (no delay in revalidation)

⁠Installing Modules and Themes

This image includes the Omeka-S-CLI⁠ tool, which simplifies the management of modules and themes. You can automatically install them by providing space-separated names in the OMEKA_MODULES and OMEKA_THEMES environment variables.

Example:

environment:
  OMEKA_THEMES: "default"
  OMEKA_MODULES: "Common EasyAdmin"

⁠Omeka S Blueprints

A blueprint is a declarative JSON file describing modules, themes, files, vocabularies, resource templates, users, sites and settings, following the shared Omeka S blueprint specification⁠. The same file can be used with Omeka S Playground⁠.

Set OMEKA_BLUEPRINT to a path inside the container or a URL:

environment:
  OMEKA_BLUEPRINT: /blueprint.json
volumes:
  - ./blueprint.json:/blueprint.json:ro

See examples/blueprint.json⁠:

{
  "$schema": "https://omeka-s-contrib.github.io/omeka-s-blueprints/schema/v0/blueprint-schema.json",
  "modules": [{ "name": "Common", "state": "activate" }],
  "settings": { "installation_title": "Omeka S Blueprint Site" }
}

How it works:

• Omeka S is installed first from the OMEKA_* installation variables, which are required. The blueprint is then applied on top with omeka-s-cli blueprint:deploy --skip core --force.
• It runs on every start. Deploy is idempotent: existing modules, themes, users and sites are skipped, and settings are re-applied.
• It runs before OMEKA_THEMES, OMEKA_MODULES and OMEKA_CSV_IMPORT_FILE, which keep working.
• If the blueprint cannot be applied (the bundled omeka-s-cli has no blueprint:deploy, Omeka S is not installed, the file or URL cannot be read, or the deploy fails), OMEKA_BLUEPRINT_ON_ERROR decides: abort (default) stops the container, warn logs a warning and starts without it. Use warn with restart: unless-stopped to avoid a restart loop.
• The blueprint's install block is ignored: the core is installed from the OMEKA_* variables. Keep OMEKA_ADMIN_EMAIL, OMEKA_ADMIN_NAME and OMEKA_ADMIN_PASSWORD (and OMEKA_SITE_TITLE, OMEKA_LOCALE, OMEKA_TIMEZONE) in line with install so the container and the Playground end up with the same administrator.
• omeka-s-cli applies modules, themes, files, vocabularies, resource templates, users, sites (with their permissions) and settings. It validates but does not apply items and itemSets, and it ignores users[].settings.
• Playground-only fields (login, landingPage, debug, phpConstants) go under x-playground, which the container ignores.
• Blueprints may contain passwords (users[].password). Do not commit production credentials; create those users out of band instead.

⁠SQLite (experimental)

With DB_DRIVER: pdo_sqlite, Omeka S stores its data in a SQLite file in the volume, so the omeka-s container is all you need:

services:
  omeka-s:
    image: erseco/alpine-omeka-s:4.2
    ports:
      - "8080:8080"
    environment:
      OMEKA_ADMIN_EMAIL: [email protected]
      OMEKA_ADMIN_PASSWORD: PLEASE_CHANGEME
      OMEKA_SITE_TITLE: "Omeka S SQLite Demo"
      DB_DRIVER: pdo_sqlite
    volumes:
      - omeka_data:/var/www/html/volume

volumes:
  omeka_data:

How it works:

• Omeka S has no SQLite support of its own. The image downloads the official Omeka S release, as usual, and patches it at build time with the SQLite support of the ateeducacion/omeka-s⁠ fork, as alpine-moodle⁠ does (see scripts/apply-sqlite-support.sh⁠): develop with PR #2⁠, 4.2.x with PR #5⁠ and 4.1.x with PR #4⁠. Older versions have no SQLite, and the container stops if DB_DRIVER=pdo_sqlite is set on them. MySQL and MariaDB keep working as before on the patched images.
• At startup, the container does not wait for DB_HOST. It writes a database.ini with driver = "pdo_sqlite" and the DB_SQLITE_PATH file, and installs Omeka S into it. The file must be inside /var/www/html/volume, so it survives the container.
• OMEKA_THEMES, OMEKA_MODULES and OMEKA_CSV_IMPORT_FILE work as usual. Modules that run MySQL-specific SQL may fail to install.

Limitations:

• OMEKA_BLUEPRINT does not work yet: the bundled omeka-s-cli connects to MySQL to check the installation, and fails with The database name is required.
• There is no migration between SQLite and MySQL/MariaDB.

⁠Advanced Management with omeka-s-cli

For more advanced tasks, you can use omeka-s-cli directly within the container. This allows you to list, install, uninstall, and manage modules and themes.

Example Commands:

• List all installed modules:

  docker compose exec omeka-s omeka-s-cli module:list
  

  Copy

• Install a new theme:

  docker compose exec omeka-s omeka-s-cli theme:download foundation
  

  Copy

After changing the version, rebuild the image:

docker compose build omeka-s

⁠Automatic CSV Import (OMEKA_CSV_IMPORT_FILE)

If you set OMEKA_CSV_IMPORT_FILE, the container will import data at startup using the CSVImport module and the bundled import_cli.php. The importer is configured as an upsert:

• If an item with the same title (dcterms:title) already exists, it will be updated.
• If not found, a new item will be created.

⁠How to enable

services:
  omeka-s:
    environment:
      # ...
      OMEKA_CSV_IMPORT_FILE: /data/sample_data.csv
    volumes:
      - ./data:/data:ro

⁠Expected CSV format

• Encoding: UTF-8 (no BOM).
• Delimiter: , (comma).
• Quote: " (double quote).
• Escape: \ (backslash).
• Header row: required.

Minimum headers supported by the default mapping included in this image:

Upsert behavior:

• Action: update
• Identifier property: dcterms:title
• If no match by title: create

If multiple items share the same title, the module’s default lookup can update the first match. Prefer unique titles for deterministic results.

⁠Example CSV

dcterms:title,dcterms:creator,dcterms:description,media_url
Eiffel Tower,Gustave Eiffel,"A wrought-iron lattice tower in Paris, France.",https://upload.wikimedia.org/wikipedia/commons/a/a8/Tour_Eiffel_Wikimedia_Commons.jpg
Mona Lisa,Leonardo da Vinci,"A portrait painting by the Italian Renaissance artist.",https://upload.wikimedia.org/wikipedia/commons/thumb/e/ec/Mona_Lisa%2C_by_Leonardo_da_Vinci%2C_from_C2RMF_retouched.jpg/800px-Mona_Lisa%2C_by_Leonardo_da_Vinci%2C_from_C2RMF_retouched.jpg
Statue of Liberty,Frédéric Auguste Bartholdi,"A neoclassical sculpture on Liberty Island, New York Harbor.",https://upload.wikimedia.org/wikipedia/commons/a/a1/Statue_of_Liberty_7.jpg

⁠What the importer does under the hood

• Loads Omeka S and the CSVImport module.

• Authenticates using the admin configured during installation.

• Reads the header row to build the column list.

• Applies a built-in mapping:

  • dcterms:title → property id 1
  • dcterms:creator → property id 2
  • dcterms:description → property id 4
  • media_url → ingester url

• Dispatches CSVImport\Job\Import with:

  • action=update
  • identifier_property=dcterms:title
  • action_unidentified=create
  • batches of rows_by_batch=20

⁠Running Commands as Root

If you need to run commands as root inside the container (e.g., to install system packages), use docker compose exec:

docker compose exec --user root omeka-s sh