Artificial Intelligence (AI) Azure

Argilla on Ubuntu 24.04 on Azure User Guide

| Product: Argilla on Ubuntu 24.04 LTS on Azure

Overview

This image runs Argilla 2.8.0, the open source data annotation and curation platform for building high quality datasets for Natural Language Processing and Large Language Models, on Ubuntu 24.04 LTS. Data, machine learning and domain teams label, review and curate text, chat and multi field records through a collaborative web interface and a full REST API and Python SDK, organised into workspaces with owner, admin and annotator roles. It is the human feedback and dataset layer teams use to prepare data for fine tuning, RLHF and DPO alignment, and model evaluation.

cloudimg delivers Argilla fully installed and reverse proxied behind nginx, with the uvicorn application server, the required background worker, a memory tuned single node Elasticsearch search backend and Redis already configured and managed by systemd, so a complete annotation platform is operational within minutes of launch.

What is included:

  • Argilla 2.8.0 (argilla-server) installed into a dedicated Python virtual environment at /opt/argilla/venv
  • A single node Elasticsearch 8.x record and vector search backend, bound to loopback with a 512 MB heap tuned for the recommended VM size
  • Redis backing the background job queue, and a dedicated worker process (argilla-worker.service) that Argilla 2.x needs to process dataset and record operations
  • uvicorn serving the FastAPI application on 127.0.0.1:6900, fronted by nginx on port 80
  • SQLite relational metadata at /var/lib/argilla, so no external database is required
  • Five systemd units enabled and active: elasticsearch, redis-server, argilla-server, argilla-worker and nginx
  • Secure by default: Argilla's well known default accounts and API key are never created. On first boot a unique owner password, a unique REST API key and a fresh token signing key are generated, and the owner credentials written to a root only file
  • A fully patched Ubuntu 24.04 LTS base with unattended security upgrades enabled
  • 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is the recommended size for evaluation and small teams; Elasticsearch is the memory intensive component, so for larger datasets choose a size with more memory. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web interface. The application server, Elasticsearch and Redis all bind to loopback only, so they are never exposed. Argilla serves plain HTTP on port 80; for production or shared access, terminate TLS in front of it with your own domain (see the final step).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Argilla by cloudimg, and select Create. On Basics 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). Then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name argilla \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

# Open the HTTP port so you can reach the web interface
az vm open-port --resource-group <your-rg> --name argilla --port 80 --priority 900

Step 3 - Retrieve the per VM owner credentials

Nothing secret is baked into the image. Argilla ships well known default accounts (the argilla user with password 1234 and API key argilla.apikey); this image never creates them. On the very first boot, a one shot service (argilla-firstboot.service) generates a fresh token signing key, a unique owner password and a unique REST API key, all unique to your instance, and writes the owner credentials to /root/argilla-credentials.txt, readable only by root. SSH in as azureuser and read them:

$ sudo cat /root/argilla-credentials.txt
# Argilla - generated on first boot by argilla-firstboot.service.
# These credentials are unique to THIS VM. Store them somewhere safe.

argilla.url=http://20.121.193.93/
argilla.owner.user=owner
argilla.owner.pass=<ARGILLA_OWNER_PASSWORD>
argilla.api.key=<ARGILLA_API_KEY>

# Canonical keys consumed by the cloudimg smoke verifier + guide substitution:
ARGILLA_OWNER_PASSWORD=<ARGILLA_OWNER_PASSWORD>
ARGILLA_API_KEY=<ARGILLA_API_KEY>

The argilla-firstboot.service one shot is ordered before the application services, so the web UI only ever starts once every per VM secret has been generated. The values above are an example; your instance will have its own unique credentials.

The argilla first boot service is enabled and its script header describing the per VM secret and owner rotation

Step 4 - Confirm the services are running

Check that Elasticsearch, Redis, the Argilla application, the background worker and nginx are all active:

sudo systemctl is-active elasticsearch redis-server argilla-server argilla-worker nginx

All five report active. The application server binds to loopback only (127.0.0.1:6900), as do Elasticsearch (127.0.0.1:9200) and Redis (127.0.0.1:6379); nginx publishes the interface on port 80:

sudo ss -tlnp | grep -E ':80 |:6900 |:9200 |:6379 '

The five Argilla services reporting active and the listening ports, nginx on 80 and the application, Elasticsearch and Redis on loopback

Step 5 - Confirm the API and the secure default

The version endpoint is public and confirms the server is ready. Argilla requires a valid API key for everything else, and the well known upstream default key argilla.apikey is rejected on this image, because that account is never created. This is the secure default.

curl -s http://localhost/api/v1/version

curl -s -o /dev/null -w 'HTTP %{http_code}\n' -H 'X-Argilla-Api-Key: argilla.apikey' http://localhost/api/v1/me

The version endpoint returns the running version, and the request with the default key returns HTTP 401.

The version endpoint returning 2.8.0, the per VM key authenticating, and the upstream default key argilla.apikey being rejected with 401

Step 6 - Sign in to the web UI

Browse to http://<vm-ip>/ and sign in as owner with the password from /root/argilla-credentials.txt. Argilla opens on its sign in page.

The Argilla sign in page served on port 80

After signing in you land on Your datasets, the home that lists every dataset you can access, with import options for Hugging Face and the Python SDK. The screenshots in this guide show Argilla populated with a small example dataset created during the build; a freshly deployed instance starts empty and ready for you to create your own.

The Argilla datasets home after signing in, showing an example customer feedback dataset with its fields and record count

Step 7 - Annotate records

Open a dataset to enter the annotation view. Argilla shows one record at a time, with the record's fields on the left and the dataset's questions on the right. Here a customer message is classified with a single label question, positive, neutral or negative; annotators submit, save as draft or discard, and a progress bar tracks completion. Argilla also supports token and span labelling, ranking and preference, and free form feedback questions.

The Argilla annotation view showing a record's text on the left and a sentiment label question with positive, neutral and negative options on the right

Each dataset's structure is configured under Dataset settings, where you edit the annotation guidelines, the fields, the questions and the task distribution. You define these when you create a dataset from the Python SDK.

The Argilla dataset settings page showing the general tab with the dataset info, task distribution and annotation guidelines

Step 8 - Use the REST API and Python SDK

Argilla exposes a complete REST API under /api/v1/. Use the API key from /root/argilla-credentials.txt in the X-Argilla-Api-Key header to call any endpoint. Read the key into a shell variable and confirm your identity and workspaces:

curl -s -H 'X-Argilla-Api-Key: <ARGILLA_API_KEY>' http://localhost/api/v1/me

curl -s -H 'X-Argilla-Api-Key: <ARGILLA_API_KEY>' http://localhost/api/v1/me/workspaces

The /api/v1/me endpoint returns the owner user, and /api/v1/me/workspaces returns the default workspace.

The REST API returning the owner identity, the default workspace and the example dataset when called with the per VM API key

The Python SDK is the primary way to create datasets and log records. Install it anywhere with pip install argilla, then connect with your instance URL and API key and define a dataset's fields and questions:

import argilla as rg

client = rg.Argilla(api_url="http://<vm-ip>", api_key="<ARGILLA_API_KEY>")

settings = rg.Settings(
    guidelines="Classify the sentiment of each message.",
    fields=[rg.TextField(name="text")],
    questions=[rg.LabelQuestion(name="sentiment", labels=["positive", "neutral", "negative"])],
)
dataset = rg.Dataset(name="my-dataset", workspace="default", settings=settings)
dataset.create()
dataset.records.log([rg.Record(fields={"text": "The onboarding was smooth."})])

Interactive API documentation is available at http://<vm-ip>/api/v1/docs.

Step 9 - Enable HTTPS with your own domain

Argilla ships on plain HTTP on port 80 so it works immediately. For production, point a DNS record at the VM's public IP and terminate TLS in front of it. A common approach is to obtain a certificate with certbot and reverse proxy through nginx, or to place Azure Application Gateway in front of the VM. The nginx site lives at /etc/nginx/sites-available/argilla; after editing it, reload nginx:

$ sudo systemctl reload nginx

Administration and support

Argilla's application configuration lives in /etc/argilla/argilla.env, and the per VM token signing key in /etc/argilla/secret.env. Manage additional users with the bundled CLI wrapper, for example sudo argilla-manage database users create --username analyst --role annotator --workspace default. The application, worker and search backend are managed with sudo systemctl restart argilla-server argilla-worker and sudo systemctl status elasticsearch.

This image is a repackaged open source software product with additional charges for cloudimg support services. Our engineers provide 24/7 support for deployment, upgrades, TLS termination, SSO integration, scaling the search backend and dataset workflows. Argilla is a trademark of its respective owner; use of the name here is purely to identify the software this image packages.