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.
• 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.

⁠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.

⁠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

⁠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"

⁠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