Girder

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a subnet in the target region.

Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting size. Scale up for larger catalogues, many concurrent users or heavy upload volumes.

Configure the NSG to allow inbound 22/tcp from your management network and 80/tcp (HTTP) from your users. Add 443/tcp if you enable HTTPS. MongoDB and Redis listen on localhost only, so no database or broker port is exposed.

The filesystem assetstore stores data on the OS disk. Choose a disk size that suits the volume of data you plan to store, or add an Amazon S3 assetstore (Step 9).

Step 1 - Deploy from the Azure Marketplace

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

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

Select Review + create, then Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:girder-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name girder \
  --image sac1647283583153:girder-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open port 80 to reach the web interface:

az vm open-port --resource-group <your-rg> --name girder --port 80 --priority 900

Step 3 - Connect to your VM

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

ssh azureuser@<vm-public-ip>

Step 4 - Retrieve the first-boot administrator credentials

On first boot, girder-firstboot.service generates a fresh MongoDB password and enables database authentication. It also creates a single site administrator with a random password, provisions the filesystem assetstore, and writes everything to a root-only file. Read the file with:

sudo cat /root/girder-credentials.txt

The file lists the instance URL, the administrator login and password, and the MongoDB user and password. These values are unique to this VM and are not stored anywhere else. Save the administrator password somewhere safe.

Step 5 - Confirm the services are healthy

The database, broker, application server, task worker and web server are managed by systemd and start on boot. Confirm that they are active:

systemctl is-active mongod redis-server girder girder-worker nginx

Then check that the REST API answers and reports the Girder release:

curl -s http://127.0.0.1/api/v1/system/version | python3 -m json.tool

Step 6 - Sign in to the web interface

Browse to http://<vm-public-ip>/ and choose Log In in the top right. Enter the administrator login and password from Step 4.

You arrive at the Collections view, the top of Girder's data hierarchy. A fresh instance has no collections yet. The left-hand navigation offers Collections, Groups, Users, My Folders and the Admin console.

Step 7 - Create a collection and upload data

Click Create collection, give it a name and description, and choose whether it is public. Open the collection, use the folder button to create folders inside it, then use the green upload button to add files.

Girder stores each uploaded file as an item containing one or more files, and shows sizes, download and preview actions for every row.

To attach metadata, select a folder or item and open the Metadata panel. Arbitrary key/value metadata is indexed and searchable from the header search box.

Step 8 - Drive Girder from the REST API

Every operation in the interface is a REST call, documented interactively at http://<vm-public-ip>/api/v1. Authenticate with HTTP Basic to obtain a token, then pass it as the Girder-Token header.

This example reads the administrator password straight from the root-only credentials file, so you can paste it as is:

PASS=$(sudo grep '^girder.admin.pass=' /root/girder-credentials.txt | cut -d= -f2-)
TOKEN=$(curl -s -u "admin:$PASS" http://127.0.0.1/api/v1/user/authentication \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["authToken"]["token"])')
curl -s -H "Girder-Token: $TOKEN" "http://127.0.0.1/api/v1/collection?limit=0" \
  | python3 -c 'import json,sys; [print(c["name"]) for c in json.load(sys.stdin)]'

Creating a collection from the API follows the same pattern:

PASS=$(sudo grep '^girder.admin.pass=' /root/girder-credentials.txt | cut -d= -f2-)
TOKEN=$(curl -s -u "admin:$PASS" http://127.0.0.1/api/v1/user/authentication \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["authToken"]["token"])')
COLLECTION_ID=$(curl -s -H "Girder-Token: $TOKEN" -X POST \
  --data-urlencode "name=API Example" --data-urlencode "description=Created from the REST API" \
  http://127.0.0.1/api/v1/collection | python3 -c 'import json,sys; print(json.load(sys.stdin)["_id"])')
echo "collection id: $COLLECTION_ID"

For bulk transfers, Kitware also publishes an official Python client (pip install girder-client) that wraps the same API.

Step 9 - Manage assetstores

Girder separates the catalogue from the storage behind it. The image provisions a filesystem assetstore at /var/lib/girder/assetstore and marks it current, so uploads work with no setup. List the assetstores from the API:

PASS=$(sudo grep '^girder.admin.pass=' /root/girder-credentials.txt | cut -d= -f2-)
TOKEN=$(curl -s -u "admin:$PASS" http://127.0.0.1/api/v1/user/authentication \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["authToken"]["token"])')
curl -s -H "Girder-Token: $TOKEN" http://127.0.0.1/api/v1/assetstore \
  | python3 -c 'import json,sys; [print("name=%s type=%s current=%s root=%s" % (a["name"], a["type"], a["current"], a.get("root"))) for a in json.load(sys.stdin)]'

In the web interface, open Admin console, then Assetstores. There you can see capacity, add a second filesystem assetstore, or add an Amazon S3 assetstore for object storage.

Setting a different assetstore as current changes where new uploads are written. Existing files stay where they are. Import data pulls files that already exist in an assetstore into the Girder hierarchy without copying them.

Security model

This image ships with no login, no database credential and no data. Girder has no built-in accounts, and its API refuses to grant administrator rights to a self-registered user. The only administrator that can exist is the one that first boot creates.

Both girder.service and nginx.service stay offline until first boot has finished, so the platform is never reachable before its administrator exists. A wrong password is rejected, and only the generated per-VM password authenticates:

PASS=$(sudo grep '^girder.admin.pass=' /root/girder-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w "wrong password -> HTTP %{http_code}\n" \
  -u "admin:WrongGuess-123" http://127.0.0.1/api/v1/user/authentication
curl -s -o /dev/null -w "per-VM password -> HTTP %{http_code}\n" \
  -u "admin:$PASS" http://127.0.0.1/api/v1/user/authentication

A wrong password returns HTTP 401. The correct per-VM password returns HTTP 200 with an authentication token.

MongoDB runs with authentication enabled and is bound to the loopback interface, so it cannot be reached from the network:

sudo ss -tln | grep -E '27017|6379'

Both the database and the Redis task broker listen only on 127.0.0.1.

Close self-registration

Girder ships with its upstream default registration policy of open, so anyone who can reach the instance can create an ordinary account. Self-registered users never receive administrator rights and see only public data. On an internet-facing deployment you will usually still want registration closed.

Open Admin console, then Server configuration. Set Registration policy to Closed and save. From then on only an administrator can create accounts, from Admin console, then Users.

Enable HTTPS with a custom domain

Point a DNS A record at your VM's public IP and allow 443/tcp in the NSG. Then install a certificate with Certbot, which edits the nginx site in place and keeps the proxy settings Girder needs:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Girder's web client calls the API on the same origin it was served from, so no application setting changes when you move to HTTPS.

Maintenance

• Logs: use journalctl -u girder for the application server, journalctl -u girder-worker for background tasks, /var/log/nginx/ for the web server and /var/log/mongodb/mongod.log for the database.
• Database backups: dump the catalogue with sudo mongodump --uri "$(sudo grep '^GIRDER_MONGO_URI=' /etc/girder/girder.env | cut -d= -f2-)" --out /var/backups/girder. Back up /var/lib/girder/assetstore alongside it, because a restore needs both the catalogue and the file content.
• Storage: the filesystem assetstore grows on the OS disk. Attach and mount a data disk, or add an Amazon S3 assetstore, before you approach the disk limit.
• OS updates: unattended security upgrades are enabled, so the base OS keeps patching itself.
• Restarting: run sudo systemctl restart girder girder-worker after any configuration change in /etc/girder/girder.env.

Support

SecureAnyCloud provides 24/7 technical support for this Girder image by email (sales@secureanycloud.com) and live chat. Support covers deployment, first-boot credentials, collections and folders, access control and groups, filesystem and Amazon S3 assetstores, the REST API and Python client, HTTPS setup, MongoDB administration and backups, and upgrades.

For billing or subscription questions, contact sales@secureanycloud.com.

Deploy on Azure

Launch Girder 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