Bash scripts¶

Every omeka-s-cli command is a plain shell command with a meaningful exit code, so provisioning an Omeka S instance is a matter of calling them in the right order. This page builds a complete provisioning script that you can adapt.

A provisioning script¶

The script below takes a server with PHP, a database and omeka-s-cli from nothing to a running site: it downloads and installs Omeka S, adds two modules and a theme, creates a user, sets a few settings and creates a site with a permission for that user.

provision.sh

#!/usr/bin/env bash
# Provision an Omeka S instance: download and install the core, add modules, a theme, users, settings
# and a site. Every step checks the current state first, so the script is safe to re-run.
#
# Usage: DB_PASSWORD=... ADMIN_PASSWORD=... ./provision.sh
set -euo pipefail

# ── configuration ────────────────────────────────────────────────────────────
OMEKA_DIR="${OMEKA_DIR:-/var/www/omeka-s}"
DB_HOST="${DB_HOST:-localhost}"
DB_NAME="${DB_NAME:-omeka}"
DB_USER="${DB_USER:-omeka}"
: "${DB_PASSWORD:?set DB_PASSWORD}"
: "${ADMIN_PASSWORD:?set ADMIN_PASSWORD}"

OMEKA_VERSION="4.2.1"
MODULES=("Common:3.4.93" "Log")     # in dependency order; pin a version with <id>:<version>
THEME="freedom"

# ── core ─────────────────────────────────────────────────────────────────────
mkdir -p "$OMEKA_DIR"
if [[ ! -d "$OMEKA_DIR/application" ]]; then
    omeka-s-cli core:download "$OMEKA_DIR" "$OMEKA_VERSION"
fi
cd "$OMEKA_DIR"

omeka-s-cli config:create-db-ini --host "$DB_HOST" --dbname "$DB_NAME" \
    --username "$DB_USER" --password "$DB_PASSWORD"

if ! omeka-s-cli core:status --is-installed; then
    omeka-s-cli core:install --title "Digital Collections" \
        --admin-name "Site Admin" --admin-email admin@example.org \
        --admin-password "$ADMIN_PASSWORD" --time-zone Europe/Brussels
fi
if omeka-s-cli core:status --needs-migration; then
    omeka-s-cli core:migrate
fi

# ── modules and theme ────────────────────────────────────────────────────────
# a module that is already downloaded is left alone, and installing an installed module is a no-op
for module in "${MODULES[@]}"; do
    omeka-s-cli module:download "$module"
    omeka-s-cli module:install "${module%%:*}"
done
omeka-s-cli theme:download "$THEME"

# ── users, settings and site ─────────────────────────────────────────────────
omeka-s-cli user:add editor@example.org "Erin Editor" editor --ignore-existing

omeka-s-cli config:set installation_title "Digital Collections"
omeka-s-cli config:set administrator_email admin@example.org

omeka-s-cli site:add "Collections" --slug collections --theme "$THEME" --default --ignore-existing
omeka-s-cli site:set-permission collections editor@example.org editor

Run it as the user that owns the web root, with the secrets in the environment, for example sudo -u www-data DB_PASSWORD=... ADMIN_PASSWORD=... ./provision.sh.

Make every step safe to re-run¶

A provisioning script runs again and again: after a failure halfway, when you add a module to the list, or on every deployment. The script above can run any number of times, because each step either checks first or is harmless when there is nothing to do:

Step	How it is safe to repeat
`core:download`	only runs when the directory has no Omeka S yet
`config:create-db-ini`	rewrites the same file with the same values
`core:install`	guarded by `core:status --is-installed`
`core:migrate`	guarded by `core:status --needs-migration`
`module:download`, `theme:download`	an existing module or theme is left alone (a warning, exit code 0)
`module:install`	installing an installed module does nothing
`user:add`, `site:add`	`--ignore-existing` skips an existing user or site
`config:set`, `site:set-permission`	set the value, whatever it was

Changing a pinned version

module:download does not replace a module that is already there, even when you pin a different version. To move to another version, use module:update, or module:download <id>:<version> --force followed by module:upgrade <id>.

To remove things idempotently, the delete commands take --ignore-not-found, which skips a resource that is already gone instead of failing.

Check the result¶

The status commands answer through their exit code or as JSON, which makes checks in scripts and CI jobs short. A few checks for the instance the script built:

omeka-s-cli core:status --is-ready
omeka-s-cli user:exists editor@example.org
omeka-s-cli module:list --json | jq -e 'map(select(.state == "active") | .id) | index("Log")'
omeka-s-cli site:list --json | jq -e '.[] | select(.slug == "collections")'

Next steps¶

Each command group has its own page with the details, under Commands in the navigation.
To describe the instance in a file instead of a script, see Blueprints.