SecureAnyCloud
Deployment guide

OpenRefine

Overview

OpenRefine is a free, open source power tool for working with messy data. You import tabular data (CSV, TSV, Excel, JSON, XML) into a project workbench. You then explore it with facets and filters, clean and normalise values with GREL, Jython or Clojure expressions, cluster near-duplicate entries, and reconcile your data against external sources such as Wikidata, all through a browser-based interface. Every change is recorded as a reproducible operation history. OpenRefine is released under the BSD 3-Clause licence.

This SecureAnyCloud image runs OpenRefine 3.10 on Ubuntu 24.04 on Azure. OpenRefine assumes a single trusted local user and ships with no built-in authentication of its own, so the image never exposes it directly. The server is bound to loopback only (127.0.0.1:3333, headless) and fronted by nginx on port 80 with HTTP Basic Auth, so the workbench is never reachable without a credential.

At first boot, openrefine-firstboot.service generates a unique per-VM Basic Auth password, reloads nginx, proves an authenticated round trip, and writes the password to /root/openrefine-credentials.txt (mode 0600, root only). No default login is baked into the image.

What you get:

  • OpenRefine 3.10.1 (official Linux distribution), pinned and sha256-verified, installed under /opt/openrefine
  • OpenJDK 17 headless runtime (OpenRefine requires Java 11 to 21), with the JVM heap pinned to a conservative 2 GB maximum so that OpenRefine fits alongside the OS and nginx on a Standard_B2s
  • openrefine.service, a systemd unit that runs the workbench as the unprivileged openrefine user, bound to loopback with a hardened service sandbox
  • openrefine-firstboot.service, a systemd one-shot that generates the per-VM HTTP Basic Auth password, reloads nginx, proves an authenticated round trip and writes /root/openrefine-credentials.txt
  • nginx on port 80, reverse proxying to the loopback-bound OpenRefine listener, with HTTP Basic Auth and an unauthenticated /healthz for load balancer probes
  • The OpenRefine project workbench, reachable at http://<vm-ip>/ after you sign in
  • Ubuntu 24.04 LTS base, patched at build time
  • The Azure Linux Agent for cloud integration and SSH key injection
  • 24/7 SecureAnyCloud support with a guaranteed 24 hour response SLA

Prerequisites

You need an active Azure subscription, an SSH public key, a VNet with a subnet in the target region, and a subscription to the OpenRefine 3.10 on Ubuntu 24.04 listing on Azure Marketplace.

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM) for evaluation and small to medium datasets. For large datasets and heavier transforms, use Standard_D2s_v5 or larger and raise the JVM heap in /opt/openrefine/openrefine-3.10.1/refine.ini (REFINE_MEMORY).

1

Deploy from the Azure Portal

Search the Azure Marketplace for OpenRefine, select the SecureAnyCloud publisher entry, and click Create.

Configure the network security group (NSG) to allow TCP 22 from your management IP and TCP 80 from your client IPs. The OpenRefine server is bound to loopback, so only nginx on port 80 is exposed.

HTTP Basic Auth protects the workbench. For any deployment beyond a private network, put a TLS-terminating reverse proxy in front of port 80 so that credentials and data are encrypted in transit.

2

Deploy from the Azure CLI

RG="openrefine-prod"; LOCATION="eastus"; VM_NAME="openrefine-01" IMAGE_URN="sac1647283583153:openrefine:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name or-vnet --address-prefix 10.90.0.0/16 --subnet-name or-subnet --subnet-prefix 10.90.1.0/24 az network nsg create -g "$RG" --name or-nsg az network nsg rule create -g "$RG" --nsg-name or-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name or-nsg --name allow-http --priority 110 \
  --source-address-prefixes "<your-client-cidr>" --destination-port-ranges 80 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:openrefine:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name or-vnet --subnet or-subnet --nsg or-nsg --public-ip-sku Standard
3

Connect over SSH

ssh azureuser@<vm-ip>

openrefine.service and nginx.service start automatically. On the first boot, openrefine-firstboot.service generates the per-VM Basic Auth password.

4

Verify the OpenRefine service

sudo systemctl is-active openrefine.service nginx.service
sudo test -f /var/lib/sac/data/openrefine-firstboot.done && echo FIRSTBOOT_DONE

Both services should report active, and the first-boot sentinel should be present.

5

Inspect the listeners and runtime

The OpenRefine server is bound to 127.0.0.1:3333, and nginx serves it on port 80. Nothing but nginx listens on a public interface. The JVM heap is pinned in refine.ini.

sudo ss -tln | grep -E ':80 |:3333' grep -E 'REFINE_MEMORY|REFINE_MIN_MEMORY' /opt/openrefine/openrefine-3.10.1/refine.ini

The output shows nginx on port 80, OpenRefine on loopback port 3333, and the pinned 2 GB maximum heap.

6

Retrieve the access password

The image generates the per-VM HTTP Basic Auth password at first boot and stores it in a root-only file. Read it with sudo:

sudo cat /root/openrefine-credentials.txt

The file lists the sign-in user, the per-VM password and the endpoint URLs:

OPENREFINE_HTTP_USER=admin OPENREFINE_BASIC_AUTH_PASSWORD=<OPENREFINE_BASIC_AUTH_PASSWORD> OPENREFINE_URL=http://<vm-ip>/ OPENREFINE_HEALTHZ=http://<vm-ip>/healthz OPENREFINE_LOCAL_HTTP=http://127.0.0.1:3333/
7

Verify access control over HTTP

OpenRefine is reachable only through the authenticated nginx proxy. Confirm that an unauthenticated request is rejected, that the per-VM password works and that the command API responds:

PW=$(sudo grep '^OPENREFINE_BASIC_AUTH_PASSWORD=' /root/openrefine-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'no creds: %{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'workbench index: %{http_code}\n' -u "admin:$PW" http://127.0.0.1/
curl -s -u "admin:$PW" http://127.0.0.1/command/core/get-version

The unauthenticated request returns 401. The authenticated workbench index returns 200, and the command API returns the OpenRefine version JSON. The unauthenticated /healthz endpoint stays open for load balancer probes.

8

Open the workbench in a browser

Open http://<vm-ip>/ from your workstation. This assumes the NSG allows TCP 80.

Your browser prompts for HTTP Basic Auth. Sign in with user admin and the per-VM password from /root/openrefine-credentials.txt. OpenRefine opens on the Create Project screen, where you choose a data source.

9

Create a project by importing data

On This Computer, choose a data file (CSV, TSV, Excel, JSON or XML) and click Next. OpenRefine shows a parsing preview where you confirm the column separator, header rows and value types.

Click Create Project. Your data loads into the project workbench as a grid of rows and columns.

10

Explore the data grid

The workbench shows your data as an editable grid. Each column header has a dropdown menu of operations. The Facet / Filter panel on the left is where you slice and clean the data.

OpenRefine is built to fix inconsistencies like those in a sample import of customer contacts: mixed spellings of the same country, and inconsistent casing and whitespace.

11

Facet and filter

Open a column's dropdown menu and choose Facet, Text facet to see every distinct value in that column with a count. In the sample import, the country column reveals eight variants of what should be a handful of countries (United Kingdom, uk, U.K., France, FR, Germany, germany, Deutschland).

Click Cluster to let OpenRefine group near-duplicate values automatically, or click a value to filter the grid to just those rows.

12

Clean and transform with GREL

Open a column menu and choose Edit cells, Transform to run a GREL expression across every cell, with a live before-and-after preview. For example, value.trim().toTitlecase() normalises casing and strips stray whitespace.

OpenRefine records transforms in the operation history, so you can undo them or replay the whole cleanup on a fresh dataset.

13

Export the cleaned data

When the data is clean, use the Export menu at the top right to write it out as CSV, TSV, Excel, JSON, HTML or a custom template. You can also export the operation history as JSON, so the same cleanup can be applied to future imports.

Projects are stored in the workspace at /var/lib/openrefine.

14

Server components

These are the key paths on the VM:

  • OpenRefine install: /opt/openrefine/openrefine-3.10.1
  • Launcher: /opt/openrefine/openrefine-3.10.1/refine
  • Heap config: /opt/openrefine/openrefine-3.10.1/refine.ini
  • Workspace and projects: /var/lib/openrefine
  • Systemd unit: /etc/systemd/system/openrefine.service
  • First-boot script: /usr/local/sbin/openrefine-firstboot.sh
  • First-boot service: /etc/systemd/system/openrefine-firstboot.service
  • Credentials file: /root/openrefine-credentials.txt (mode 0600)
  • First-boot sentinel: /var/lib/sac/data/openrefine-firstboot.done
  • nginx site: /etc/nginx/sites-available/sac-openrefine
  • Basic Auth file: /etc/nginx/.openrefine_htpasswd
15

Managing the service

sudo systemctl status openrefine.service --no-pager | head -6 sudo journalctl -u openrefine.service --no-pager | tail -5

To restart the workbench after you change the heap or options, run sudo systemctl restart openrefine.service.

16

Security recommendations

  • Rotate the Basic Auth password. Regenerate /etc/nginx/.openrefine_htpasswd with sudo htpasswd -B /etc/nginx/.openrefine_htpasswd admin, reload nginx, and store the password in your secrets manager.
  • Keep the OpenRefine listener on loopback. Leave it as shipped, expose only nginx on port 80, and put TLS in front of it with Azure Application Gateway or nginx with a real certificate.
  • Restrict the NSG. Allow port 80 only from trusted client networks, because a data cleaning workbench often holds sensitive data.
  • Make the workbench public only if intended. To do so, remove the auth_basic lines from /etc/nginx/sites-available/sac-openrefine and reload nginx.
  • Back up the workspace. Back up /var/lib/openrefine, or take Azure disk snapshots, so your projects and operation histories are preserved.
  • Raise the JVM heap for large datasets. Increase it in refine.ini (REFINE_MEMORY) and use a larger VM size accordingly.
  • Patch the OS monthly. Run sudo apt-get update && sudo apt-get upgrade && sudo reboot.
17

Support and licensing

OpenRefine is licensed under the BSD 3-Clause licence. There are no per-node, per-CPU or per-GB fees.

SecureAnyCloud produces this image. It is not affiliated with, endorsed by or sponsored by the OpenRefine project. OpenRefine is a trademark of its respective owner and is used here only to describe the software included in the image.

SecureAnyCloud provides commercial support for this image separately from the upstream project.

Email: sales@secureanycloud.com

Website: secureanycloud.com

Support hours: 24/7 with a guaranteed 24 hour response SLA

Deploy on Azure

Launch OpenRefine 3.10 Data Cleaning Workbench on Ubuntu 24.04 with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Launch OpenRefine 3.10 Data Cleaning Workbench on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure