Omeka S

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Omeka S by SecureAnyCloud, and select Create.

On the Basics tab, pick your subscription, resource group, region and size (Standard_B2s or larger). Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTPS (443).

Select Review + create, then Create.

SecureAnyCloud images carry a Marketplace purchase plan. Accept its terms once per subscription, then create the VM and open HTTPS:

az vm image terms accept --urn sac1647283583153:omeka-s-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-omeka-rg \
  --name omeka-s \
  --image sac1647283583153:omeka-s-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group my-omeka-rg --name omeka-s --port 443 --priority 900

Connect to the VM over SSH, using the public IP address of your VM:

ssh azureuser@<vm-public-ip>

First boot generates this VM's secrets and only then opens the web server. If the web server is running, the installation is ready. Check the three services:

systemctl is-active mariadb php8.3-fpm apache2

All three report active:

active active active

Confirm that Omeka S answers over HTTPS on the VM itself. The image ships a self-signed certificate, so -k is expected here until you install your own certificate in Step 11:

curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/login

That prints 200. Only SSH and HTTPS are reachable from off the VM. The database and PHP-FPM deliberately are not:

sudo ss -lnt | grep -E ':(22|80|443|3306) ' | sort

LISTEN 0 4096 [::]:22 [::]:* LISTEN 0 4096 0.0.0.0:22 0.0.0.0:* LISTEN 0 511 *:443 *:* LISTEN 0 511 *:80 *:* LISTEN 0 80 127.0.0.1:3306 0.0.0.0:*

MariaDB appears only on 127.0.0.1:3306. PHP-FPM does not appear at all: it listens on a UNIX socket, not a TCP port.

Every secret on this VM is generated on its first boot and written to a file that only root can read. Nothing here is shared with any other deployment. Print the file as an administrator:

sudo cat /root/omeka-s-credentials.txt

# sac :: Omeka S credentials
# Generated on this VM's first boot. This file is readable only by root. # Sign in at OMEKA_S_URL with the e-mail address and password below, then change # both under your user account (top left) and set your real administrator e-mail # under Settings. OMEKA_S_URL=https://<vm-public-ip>/ omeka-s.admin.email=admin@example.com omeka-s.admin.pass=<unique to this VM> omeka-s.db.name=omeka_s omeka-s.db.user=omeka omeka-s.db.pass=<unique to this VM>

Omeka S signs users in by e-mail address. Its first administrator is admin@example.com, an address you replace with your own after signing in.

The database password is the one Omeka S itself uses. It is stored in /var/www/omeka-s/config/database.ini, readable only by root and the web server. You can check that it works the same way Omeka S connects:

MYSQL_PWD="$(sudo grep '^omeka-s.db.pass=' /root/omeka-s-credentials.txt | cut -d= -f2-)" mariadb -u omeka omeka_s -Nse "SELECT value FROM setting WHERE id = 'version';"

That prints "4.2.1", the schema version of your database.

Browse to https://<vm-public-ip>/login. Your browser warns about the self-signed certificate. Accept it to continue, or install your own certificate first (Step 11).

Sign in with the e-mail address admin@example.com and the omeka-s.admin.pass value from Step 5. The admin dashboard opens with the resource and site management menus.

Before anything else, make the account yours:

• Select Administrator (top left). Change the Email to your own address and the Password to one you choose. Passwords on this image must be at least 12 characters and mix upper case, lower case and a number.
• Open Settings. Set Administrator email to the address outgoing mail should come from, and set the Installation title to your institution's name.

Omeka S keeps one collection and publishes it through sites. Choose Sites > Add site. Give the site a Title and a URL slug (for example harbour), then select Add.

Next, choose Items > Add new item. Fill in Title and Description (Dublin Core). Open the Media tab, select Upload and pick an image. On the Sites tab, check that your site is listed, then select Add.

Omeka S stores the original file and generates its thumbnails, which appear beside the item's metadata. The item is published immediately on the public site at https://<vm-public-ip>/s/<slug>/item/<id>, where any visitor can browse and search the collection without signing in.

JPEG, PNG, GIF and WebP uploads get thumbnails. Other formats, such as PDF and TIFF, are stored and can be downloaded but are shown with a generic icon.

Build out the site under Sites > your site. Use Pages for exhibit and about pages, Navigation for the menu, Resources for which items the site shows, and Theme for its look.

The image contains exactly one account, the global administrator, and no API keys. List the accounts to confirm:

sudo mariadb -t omeka_s -e "SELECT id, email, role, is_active FROM user;"

+----+-------------------+--------------+-----------+ | id | email | role | is_active | +----+-------------------+--------------+-----------+ | 1 | admin@example.com | global_admin | 1 | +----+-------------------+--------------+-----------+

The web server refuses the Omeka S installer and the files that carry configuration, logs and dependency metadata. The sign-in page is served normally:

for p in /login /install /index.php/install /config/database.ini /logs/application.log /composer.lock; do printf '%-24s %s\n' "$p" "$(curl -sk -o /dev/null -w '%{http_code}' https://127.0.0.1$p)"; done

/login 200 /install 403 /index.php/install 403 /config/database.ini 403 /logs/application.log 403 /composer.lock 403

Uploaded media is stored under /var/www/omeka-s/files. The web server serves it as static files and never executes it. To prove this on your own VM, place a PHP file there and request it:

sudo install -d -o www-data -g www-data /var/www/omeka-s/files/original printf '<?php echo "executed";\n' | sudo tee /var/www/omeka-s/files/original/probe.php >/dev/null curl -sk -o /dev/null -w 'probe.php -> %{http_code}\n' https://127.0.0.1/files/original/probe.php
sudo rm -f /var/www/omeka-s/files/original/probe.php

probe.php -> 403

The request is refused outright, so nothing in the file is ever run.

Omeka S builds absolute links from the address a browser uses. This lets it work on the public IP, the private IP or a domain name without configuration.

The one place where this matters for security is the password reset e-mail. If the reset link were built from whatever Host a stranger's browser sent, they could request a reset for one of your users and make the link point at a site they control. On this image, the forgot-password page always uses this VM's own name.

omeka-s-hostname.service runs on every boot. It finds the VM's public IP address (or its private address if it has none) and writes it here:

grep '^Define' /etc/apache2/conf-available/omeka-s-canonical-host.conf

That prints Define OMEKA_S_CANONICAL_HOST followed by your VM's public IP address.

The same service issues the self-signed HTTPS certificate for that address. Because it runs on every boot, an Azure public IP that changes across a stop and start is picked up automatically:

systemctl is-enabled omeka-s-hostname.service && sudo openssl x509 -in /etc/ssl/omeka-s/omeka-s.crt -noout -subject

The session cookie is issued with Secure, HttpOnly and SameSite=Lax and without a Domain attribute, so it works on the bare IP address in every browser.

Omeka S sends password reset links and new-user activation emails. This image does not ship a mail transfer agent, so no mail leaves the VM until you configure one.

Azure blocks outbound port 25 on most subscriptions, so relay through an authenticated SMTP provider on port 587. Add a mail block to /var/www/omeka-s/config/local.config.php, inside the returned array, with your provider's details:

'mail' => [ 'transport' => [ 'type' => 'smtp', 'options' => [ 'name' => 'collections.example.org', 'host' => 'smtp.example.org', 'port' => 587, 'connection_class' => 'login', 'connection_config' => [ 'username' => 'omeka@example.org', 'password' => 'your-smtp-password', 'ssl' => 'tls', ], ], ], ],

Edit the file as root (sudo nano /var/www/omeka-s/config/local.config.php), then reload PHP with sudo systemctl reload php8.3-fpm.

Under Settings, set the Administrator email to an address your provider allows you to send from.

Point a DNS A record at the VM's public IP. Then pin that name so that Apache, and every password reset link Omeka S e-mails, uses it instead of the IP address:

echo 'collections.example.org' | sudo tee /etc/omeka-s/server-name
sudo /usr/local/sbin/omeka-s-hostname.sh

When the name resolves publicly, obtain a Let's Encrypt certificate and point Apache at it:

sudo apt-get update && sudo apt-get install -y certbot
sudo certbot certonly --webroot -w /var/www/omeka-s -d collections.example.org --deploy-hook 'systemctl reload apache2'
sudo sed -i -e 's#/etc/ssl/omeka-s/omeka-s.crt#/etc/letsencrypt/live/collections.example.org/fullchain.pem#' \
  -e 's#/etc/ssl/omeka-s/omeka-s.key#/etc/letsencrypt/live/collections.example.org/privkey.pem#' \
  /etc/apache2/sites-available/omeka-s.conf
sudo systemctl reload apache2

Keep port 80 open in your NSG while certbot validates, because the challenge arrives there and is redirected to HTTPS. Certbot renews the certificate automatically and reloads Apache after each renewal.

Omeka S is extended with modules (for example CSV Import, Mapping, Value Suggest) and themes, published at omeka.org/s.

The application code on this image is owned by root and cannot be modified by the web server, so a stolen administrator session can never be turned into code running on your server. Install add-ons from the shell instead. Check which are present:

ls /var/www/omeka-s/modules /var/www/omeka-s/themes

A new image carries only the default theme. To add a module, download its release zip, unpack it into modules as root and keep it root-owned. For example, install the official CSV Import module:

cd /tmp && curl -fsSLO https://github.com/omeka-s-modules/CSVImport/releases/download/v2.6.2/CSVImport-2.6.2.zip
sudo unzip -q CSVImport-2.6.2.zip -d /var/www/omeka-s/modules/
sudo chown -R root:root /var/www/omeka-s/modules/CSVImport

Then open Modules in the admin, select Install beside the module and configure it. Themes work the same way under /var/www/omeka-s/themes. You choose a theme per site under Sites > your site > Theme.

• No default or shared credential ships in the image. The Omeka S administrator password, the database password and the HTTPS certificate are all generated on this VM's first boot.
• The installer was completed when the image was built. The web server refuses it, as it does config, logs, vendor, the application source and the project's metadata files.
• The web server stays closed until first boot has generated this VM's secrets, so a VM is never reachable half-configured.
• The application code is owned by root and read-only to the web server. Only files (uploads and thumbnails) and logs are writable, and nothing uploaded is ever executed as code.
• Only 22/tcp and 443/tcp are reachable from off the VM. 80/tcp issues a permanent redirect to HTTPS and serves nothing else. MariaDB is bound to 127.0.0.1 and PHP-FPM uses a UNIX socket.
• Password reset links use the name this VM writes for itself, never a browser-supplied host name. The session cookie is Secure, HttpOnly and SameSite=Lax, and only TLS 1.2 and 1.3 are accepted.
• SSH refuses root and password logins. Sign in as azureuser with your key. Ubuntu's unattended security upgrades remain enabled.

Omeka S keeps its state in the MariaDB database and in the files directory, which holds originals and thumbnails. Dump the database and archive the files:

sudo mariadb-dump --single-transaction omeka_s > ~/omeka-s-db-$(date +%F).sql
sudo tar czf ~/omeka-s-files-$(date +%F).tar.gz -C /var/www/omeka-s files config/database.ini config/local.config.php

Copy both files off the VM. Take an Azure disk snapshot before any upgrade.

Ubuntu security updates are applied automatically. Check which Omeka S release is installed:

grep "const VERSION" /var/www/omeka-s/application/Module.php

To move to a later release, back up first (Step 14). Then replace the code while keeping your config, files, modules and themes:

cd /tmp && curl -fsSLO https://github.com/omeka/omeka-s/releases/download/v4.2.2/omeka-s-4.2.2.zip
sudo unzip -q omeka-s-4.2.2.zip -d /tmp/omeka-s-new
sudo rsync -a --delete --exclude config/ --exclude files/ --exclude modules/ --exclude themes/ --exclude logs/ /tmp/omeka-s-new/omeka-s/ /var/www/omeka-s/
sudo chown -R root:root /var/www/omeka-s && sudo chown -R www-data:www-data /var/www/omeka-s/files /var/www/omeka-s/logs
sudo chown root:www-data /var/www/omeka-s/config/*.ini /var/www/omeka-s/config/local.config.php

Replace 4.2.2 with the release you are installing. Then sign in. Omeka S detects the new version and asks you to run its database migration from the admin, which only a signed-in global administrator can do.