NADA on Ubuntu 24.04 on Azure User Guide

Overview

NADA is the open source microdata cataloguing platform developed by the International Household Survey Network (IHSN) and the World Bank. National statistics offices, central banks, and research institutions use it to publish survey, census, and administrative data holdings as a searchable online catalogue, documented with DDI CodeBook and Dublin Core metadata, with controlled access policies for the data itself. The cloudimg image installs NADA 5.6 on Apache 2.4, MySQL 8.0, and PHP 8.3, all from Ubuntu 24.04 noble with no third party APT repositories. The catalogue database is provisioned, the upstream migrations are applied, and the first administrator is created for you at first boot, so there is no installer wizard to click through and none reachable. The MySQL root, application database, and administrator passwords, the admin API key, and the application encryption key are all rotated per instance at first boot, so nothing ships with a known secret.

What is included:

• NADA 5.6 from the official release at /var/www/html/nada (the tree root is the document root)
• Apache 2.4.x with mod_rewrite enabled, vhost at /etc/apache2/sites-available/nada.conf
• MySQL 8.0.x with a nada database and nada application user (per VM password)
• PHP 8.3.x with the mysqli, xsl, xml, mbstring, gd, curl, zip, and intl extensions
• A single site administrator created at first boot, with a per VM password and admin API key
• The new NADA 5.6 Vue admin interface, indicator and time series support, and built in analytics
• nada-firstboot.service provisioning the catalogue and rotating every secret per VM
• Host agnostic URLs: the catalogue renders on the VM public IP or any domain you point at it
• Apache and MySQL enabled and auto starting on boot
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key, and a VNet with a subnet. Standard_B2s (2 vCPU, 4 GB RAM) is a comfortable starting point for most catalogues; move up to a D2s or D4s size for large collections or heavy search traffic. Open inbound ports 80 and 443 (and 22 to your management network) on the network security group. MySQL listens only on loopback and is never exposed.

Step 1: Deploy and connect

Launch the image from the Azure Marketplace, then connect over SSH as azureuser:

ssh azureuser@<vm-ip>

On the very first boot the web server intentionally waits while nada-firstboot.service provisions the catalogue database, applies the upstream migrations, and generates the per VM credentials; the site comes up automatically a few seconds later.

Step 2: Verify the services

Confirm Apache and MySQL are active and listening. MySQL is bound to loopback only:

sudo systemctl is-active apache2.service mysql.service
sudo ss -ltn | grep -E ':80 |:3306 '

Expected output:

active
active
LISTEN 0      151        127.0.0.1:3306       0.0.0.0:*
LISTEN 0      511                *:80               *:*

Step 3: Check the versions

The public version API reports the installed NADA release:

curl -s http://127.0.0.1/index.php/api/version
php -v | head -1
mysql --version
apache2 -v | head -1

Expected output:

{"version":"5.6"}
PHP 8.3.6 (cli) (built: Jul 16 2026 18:30:41) (NTS)
mysql  Ver 8.0.46-0ubuntu0.24.04.3 for Linux on x86_64 ((Ubuntu))
Server version: Apache/2.4.58 (Ubuntu)

Step 4: Inspect the catalogue database

The schema and upstream migrations are applied and a single administrator exists, stored with a bcrypt password hash, so there is no default or shared login. Read the application database password from the root only credentials file, then inspect the tables and the administrator:

DB_PASS=$(sudo grep '^NADA_DB_PASSWORD=' /root/nada-credentials.txt | cut -d= -f2-)
sudo mysql -unada -p"$DB_PASS" nada -e "SELECT COUNT(*) AS nada_tables FROM information_schema.tables WHERE table_schema='nada'"
sudo mysql -unada -p"$DB_PASS" nada -e "SELECT u.username, u.active, LEFT(u.password,4) AS hash, r.name AS role FROM users u JOIN user_roles ur ON ur.user_id=u.id JOIN roles r ON r.id=ur.role_id"

Expected output:

+-------------+
| nada_tables |
+-------------+
|          90 |
+-------------+
+----------+--------+------+-------+
| username | active | hash | role  |
+----------+--------+------+-------+
| admin    | 1      | $2a$ | admin |
+----------+--------+------+-------+

Step 5: Read the administrator credentials

The per VM credentials are written to a root only file. Read it to pick up the administrator email and password for signing in, and the admin API key for scripted publishing:

sudo cat /root/nada-credentials.txt

Keep this file secure. Change the administrator password from the Users area once you have signed in for the first time.

Step 6: Sign in

Confirm the catalogue is serving locally, then browse to http://<vm-ip>/ in your browser, click Login, and sign in with the NADA_ADMIN_EMAIL and NADA_ADMIN_PASSWORD from Step 5 (NADA asks for the email first, then the password):

curl -sL -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1/

Expected output:

HTTP 200

Step 7: The admin dashboard

After signing in, open Site administration (or browse to http://<vm-ip>/index.php/admin) to reach the NADA 5.6 Vue dashboard. It summarises the catalogue, collections, licensed requests, and users, and links to every management area: studies, citations, users and roles, menus, reports, and site settings.

Step 8: Publish your first study through the API

Every catalogue operation is also available through the REST API, and the image pre provisions a personal admin API key (the NADA_API_KEY value in the credentials file), so tools like PyNADA and NADAR work immediately. Create a survey study from the command line:

API_KEY=$(sudo grep '^NADA_API_KEY=' /root/nada-credentials.txt | cut -d= -f2-)
curl -s -X POST -H "X-API-KEY: $API_KEY" -H 'Content-Type: application/json' \
  -d '{"repositoryid":"central","published":1,"overwrite":"yes","study_desc":{"title_statement":{"idno":"DEMO-HBS-2026","title":"Household Budget Survey 2026"},"study_info":{"abstract":"Household budget survey measuring income, expenditure, and living conditions.","nation":[{"name":"Example Country","abbreviation":"EXC"}]},"authoring_entity":[{"name":"National Statistics Office"}]}}' \
  http://127.0.0.1/index.php/api/datasets/create/survey/DEMO-HBS-2026

The response reports "status":"success" with the new dataset. Confirm it is findable through the public search API:

curl -s "http://127.0.0.1/index.php/api/catalog/search?keywords=household"

The result includes "idno":"DEMO-HBS-2026" with its title and metadata. In the browser, the study now appears in the catalogue with its DDI metadata rendered, searchable by keyword, country, and year:

Step 9: Browse a study page

Each study renders its full DDI documentation: identification, producers and sponsors, data collection, and downloadable DDI/XML and JSON metadata. Use the study page tabs to attach microdata files, external resources, and an access policy (direct download, licensed access with an application workflow, or enclave only listing).

Step 10: Components

Step 11: Security and next steps

• Change the administrator password from the Users area after your first sign in, and add accounts for your catalogue curators with the roles they need.
• Rotate the API key from the admin interface if you prefer one you generated yourself; the pre provisioned key can be revoked there at any time.
• Enable HTTPS by installing certbot and requesting a certificate: sudo apt-get install -y certbot python3-certbot-apache then sudo certbot --apache.
• Restrict the network security group so that ports 80 and 443 are open only to your users, and port 22 only to your management network.
• Move the datafiles directory outside the web root for defence in depth once you are in production, following the upstream security guidance, and take regular backups of the nada database and /var/www/html/nada/datafiles.
• Configure email (SMTP or the SendGrid driver) in application/config/email.php and auth.local.php so registration and access request notifications can be sent.
• Patch the OS regularly with sudo apt-get update and sudo apt-get upgrade.

Licensing

NADA is distributed under the MIT licence (the licence text ships in the image at /usr/share/doc/nada/license.txt) and is free to use commercially. cloudimg packages and supports the image; support is available 24/7 at support@cloudimg.co.uk. All product and company names are trademarks or registered trademarks of their respective holders and their use does not imply affiliation or endorsement.