Deploy UnifAI on Azure

Deploy the Lineaje UnifAI MCP Server on an Azure Linux VM.

Deploy UnifAI on Azure

Hybrid MCP Server Deployment Guide

Deploy the Lineaje UnifAI MCP Server on an Azure Linux VM with Docker Compose.

The standard deployment exposes MCP over HTTPS. Caddy protects the private application container.

Ema and Pay-i are optional integrations. They are not required for base deployment.

1. Architecture overview

Component	Image / runtime	Purpose	Network exposure
combined	lineaje-combined:<tag>	UnifAI MCP server, APIs, and enabled tools	Port 8080, internal only
caddy	caddy:2-alpine	TLS termination and reverse proxy	Port 443

External clients connect through Caddy. Do not expose 8080 through the Azure NSG or host firewall.

MCP client → HTTPS :443 → Caddy TLS proxy → HTTP :8080 → UnifAI MCP server

Endpoint	Protocol	Purpose
/health	GET	Service readiness and health validation
/mcp	Streamable HTTP	MCP-compatible client endpoint

2. Azure requirements

Resource	Minimum
CPU	4 vCPU
Memory	16 GB RAM
Operating system	Ubuntu 22.04 or later
Architecture	x86_64 / amd64
Storage	300 GB

Install Docker Engine 24+, Docker Compose v2, OpenSSH, and the current Azure CLI.

docker --version
docker compose version
az version

3. Identity and network access

Enable a system-assigned managed identity on the VM. Grant it the appropriate Microsoft Foundry inference role.

Cognitive Services User also supports model inference where available.

az vm identity show -g <RESOURCE_GROUP> -n <VM_NAME> --query principalId -o tsv
az role assignment list --assignee <PRINCIPAL_ID> --scope <FOUNDRY_RESOURCE_ID> -o table

Use the managed identity for Foundry authentication. Do not use a long-lived model API key.

Allow inbound HTTPS on 443 only from approved corporate, VPN, or VNet networks. Open 80 only when an HTTP ACME challenge requires it.

Allow outbound HTTPS to:

• Microsoft Foundry: *.services.ai.azure.com, *.openai.azure.com, or the configured model endpoint.

• Lineaje SCIM: https://scim-service.v2.prod.veedna.com.

• Lineaje Data Service: https://data-service-v2-apigw.v2.prod.veedna.com.

• Lineaje Identity Service: https://lineaje-identity-service.v2.prod.veedna.com/lineajeidentity/realms/idp.

• Lineaje S3: https://us-east-1-commercialprod-veedna-opa.s3.us-east-1.amazonaws.com/ for artifact-transfer workflows.

Use destination allowlisting where required.

Azure Instance Metadata Service (IMDS) provides managed-identity tokens to the VM. IMDS is VM-local and needs no firewall allowlist entry.

4. TLS configuration

Caddy terminates HTTPS.

For controlled testing, set:

SITE_ADDRESS=:443

Caddy uses its local certificate authority. Trust its generated CA or allow the test certificate.

For production, set a resolvable FQDN:

SITE_ADDRESS=unifai.example.com

Use an approved certificate configuration. Open 80 if the certificate flow needs HTTP validation.

5. Before you begin

Confirm the VM meets sizing requirements. Confirm 443 is restricted. Verify managed-identity access, DNS, TLS, required configuration values, and rollback availability.

Do not start production deployment when TLS, inbound ranges, identity permissions, or authentication configuration are unknown.

6. Deploy UnifAI

Connect and run preflight checks:

ssh -i <keyfile.pem> azureuser@<VM_PUBLIC_IP>
uname -m
lsb_release -ds
docker --version
docker compose version
free -h
df -h

Transfer and extract the provided release bundle:

Download Hybrid UnifAI Server Bundle

tar -xzf lineaje-deploy-llm-remediaiton-v7.tar.gz
cd lineaje-deploy-llm-remediaiton-v7

The bundle can include run_on_vm.sh. The script loads the bundled image, starts configured services, and waits up to 150 seconds for GET /health to return HTTP 200. It prints container logs and exits with an error when health validation fails.

Configure and protect the environment file:

Download Hybrid Environment Configuration

unzip -o lineaje.env.zip
chmod 600 .env.azure
nano .env.azure

Setting	Value / guidance
UNIFAI_MODE	hybrid
LLM_API_URL	Customer's Azure AI Foundry project endpoint
LLM_API_VERSION	2025-05-01
AZURE_OPENAI_API_VERSION	2025-05-01
UNIFAI_EVAL_MODEL	Customer's Foundry deployment name
UNIFAI_REMED_MODEL	Customer's Foundry deployment name
UNIFAI_DETECTION_MODEL	Customer's Foundry deployment name
SITE_ADDRESS	localhost, 127.0.0.1, <VM_PUBLIC_IP>
DEFAULT_SNI	<VM_PUBLIC_IP>

The three model settings require the Foundry deployment name. Do not use a model version or date.

LLM_API_VERSION and AZURE_OPENAI_API_VERSION are required. Without them, Foundry requests can fail and scans may report 0 violations.

Treat the completed .env.azure file as a secret. Never commit, email, or share it in screenshots.

Environment configuration reference

# --- Mode ---
UNIFAI_MODE=hybrid
UNIFAI_FORCE_S3_ARCHIVE_UPLOAD=false

# --- Azure AI Foundry ---
UNIFAI_INFERENCE_BACKEND=azure_foundry_gpt
LLM_API_URL=https://<FOUNDRY_RESOURCE>.services.ai.azure.com/api/projects/<FOUNDRY_PROJECT>
LLM_API_VERSION=2025-05-01
AZURE_OPENAI_API_VERSION=2025-05-01

UNIFAI_EVAL_MODEL=<FOUNDRY_DEPLOYMENT_NAME>
UNIFAI_REMED_MODEL=<FOUNDRY_DEPLOYMENT_NAME>
UNIFAI_DETECTION_MODEL=<FOUNDRY_DEPLOYMENT_NAME>

AZURE_IMDS_RESOURCE=https://ai.azure.com

# --- Lineaje SaaS endpoints ---
SCIM_SERVICE_URL=https://scim-service.v2.prod.veedna.com
SCM_SERVICE_URL=https://scm-service.v2.prod.veedna.com
S3_BUCKET=us-east-1-commercialprod-veedna-opa
DATA_SERVICE_BASE_URL=https://data-service-v2-apigw.v2.prod.veedna.com
KEYCLOAK_BASE=https://lineaje-identity-service.v2.prod.veedna.com/lineajeidentity/realms/idp

# --- Server / TLS ---
COMBINED_IMAGE=lineaje-combined:local
COMBINED_HTTP_PORT=8080
SITE_ADDRESS=localhost, 127.0.0.1, <VM_PUBLIC_IP>
DEFAULT_SNI=<VM_PUBLIC_IP>
OAUTH_ENABLED=false

# --- Runtime guardrail library ---
GR_DB_PATH=/data/gr_policies.db
GR_FAIL_MODE=closed
GR_SEED_FILE=/config/seed_demo.yaml

# --- Optional: Ema Azure Blob poller ---
# BLOB_ACCOUNT_URL=<BLOB_ACCOUNT_URL>
# BLOB_CONTAINER=<BLOB_CONTAINER>
# BLOB_SAS_TOKEN=<BLOB_SAS_TOKEN>
# BLOB_INCOMING_PREFIX=<INPUT_PATH>/
# BLOB_OUTPUT_PREFIX=<OUTPUT_PATH>/
# BLOB_TENANT_ID=<BLOB_TENANT_ID>
# BLOB_ENVIRONMENT=production
# BLOB_POLL_INTERVAL=300
# BLOB_MAX_ATTEMPTS=3

# --- Optional: Pay-i FinOps reporting ---
# PAYI_API_KEY=
# PAYI_CATEGORY=system.openai
# PAYI_USECASE_NAME=<USE_CASE_NAME>
# PAYI_TIMEOUT_S=5

Do not set LINEAJE_POLICY_DIR; it points the server at demo policies.

Start the base runtime:

bash run_on_vm.sh

Always start a newly downloaded release with run_on_vm.sh. Running docker compose up alone does not load the image included with the release and may start an older image already present on the VM.

Only combined and caddy are required for the standard deployment.

7. Validate the deployment

Run the local health check:

curl -k -i https://localhost/health

Expected result: HTTP 200.

The response typically includes status: "ok" and routines_registered. Confirm routines_registered is at least 1.

curl -sk -o /dev/null -w "%{http_code}\n" https://<VM_PUBLIC_IP>/enforce

404 means the current server version is running. 405 means an older server version is still running.

Opening https://<VM_PUBLIC_IP>/mcp in a browser may return 405 Method Not Allowed. A normal curl request can do the same. This is expected because the MCP endpoint accepts scanner requests, not browser GET requests.

From an approved network:

curl -i https://<FQDN_OR_VM_IP>/health

Use the FQDN and normal certificate validation in production.

Review runtime logs:

docker compose --env-file .env.azure logs --tail=100 combined caddy

Resolve crash loops, port bind failures, authentication failures, and upstream connectivity errors before continuing.

Deployment is successfully verified when /health reports healthy and /enforce returns 404.

Next Steps

After you deploy the Hybrid UnifAI MCP Server and verify its health, choose the SCM platform to connect:

1. Deploy Hybrid UnifAI MCP Server.

2. Verify server health.

3. Choose GitHub Actions or Azure Pipelines in Azure DevOps.

4. Configure the selected pipeline to use the Hybrid MCP Server.

5. Run the scan.

The SCM pages contain the platform-specific configuration. Do not duplicate it here.

Smoke-test credentials

Use a valid Lineaje credential for authenticated checks:

• A Lineaje access token from Settings → API.

• A Lineaje personal access token, when supported by the deployment.

Replace https://localhost with the deployed FQDN or public IP for remote tests.

8. Connect an MCP client

Use the Streamable HTTP endpoint:

https://<FQDN>/mcp

Claude Code

Add this to ~/.claude/settings.json or .claude/settings.json:

{
  "mcpServers": {
    "unifai": {
      "type": "http",
      "url": "https://<FQDN>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Verify with:

claude mcp list

Cursor

Create .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "unifai": {
      "url": "https://<FQDN>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "unifai": {
      "type": "http",
      "url": "https://<FQDN>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Use supported secret storage or environment-variable substitution. Never commit bearer tokens.

Optional Ema integration

Ema is not required for MCP deployment. Enable it only for runtime-event ingestion.

Configure Azure Blob Storage and provide:

BLOB_ACCOUNT_URL=<AZURE_BLOB_ACCOUNT_URL>
BLOB_CONTAINER=<CONTAINER_NAME>
BLOB_INCOMING_PREFIX=<INPUT_PATH>/
BLOB_OUTPUT_PREFIX=<OUTPUT_PATH>/
BLOB_SAS_TOKEN=<SAS_TOKEN>

Do not include a leading ? when the deployment expects a raw SAS token.

blob-poller reads incoming runtime logs, submits them to UnifAI, and writes violations.json to the configured output path.

docker compose --env-file .env.azure up -d blob-poller
docker compose --env-file .env.azure logs -f blob-poller

Confirm incoming objects are detected, processed, and written to the expected output path.

Optional Pay-i integration

Pay-i is not required for UnifAI deployment or MCP functionality.

Configure it only for FinOps reporting and model-cost attribution:

PAYI_API_KEY=<PAYI_API_KEY>
PAYI_CATEGORY=<CATEGORY>
PAYI_RESOURCE=<RESOURCE>
PAYI_USECASE_NAME=<USE_CASE_NAME>
PAYI_TIMEOUT_S=<TIMEOUT>

PAYI_CATEGORY identifies the configured model or provider category. PAYI_RESOURCE adds an optional attribution identifier. PAYI_USECASE_NAME groups UnifAI activity under a logical use case. PAYI_TIMEOUT_S sets the reporting-request timeout.

Leave PAYI_API_KEY unset or empty to disable the integration.

10. Operations

Check status and logs

docker compose --env-file .env.azure ps
docker compose --env-file .env.azure logs -f combined caddy

If Ema is enabled:

docker compose --env-file .env.azure logs -f blob-poller

Restart, stop, and start

docker compose --env-file .env.azure restart combined caddy
docker compose --env-file .env.azure stop combined caddy
docker compose --env-file .env.azure start combined caddy

Restart blob-poller separately when Ema is enabled.

After restarts, validate /health and repeat MCP tool discovery.

Upgrade and rollback

For upgrades, retain the prior bundle, back up .env.azure, compare configuration keys, then validate health and MCP access.

For rollback, use the prior release directory:

docker compose --env-file .env.azure up -d combined caddy
curl -k -i https://localhost/health

Rollback succeeds when /health returns HTTP 200 and MCP authentication and tool discovery work again.

Docker Compose prefixes volume names with the directory where it runs. Check the actual volume name before investigating rollback state:

docker volume ls | grep gr_data

Troubleshooting

Symptom	Likely cause	Corrective action
Cannot reach 443	Compose status, NSG, firewall, Caddy listener	Start Caddy and correct routing rules
/health fails locally	Logs, container health, image architecture, environment	Resolve the application or configuration issue
TLS error	SITE_ADDRESS, DNS, Caddy logs	Correct DNS or certificate configuration
MCP 401 or 403	Token, identity reachability, system clock	Use a valid credential
Foundry authorization fails	VM identity, role, scope	Assign the correct inference role
Container restarts	Docker logs, memory, disk, environment	Resolve the first fatal error
Scan completes in roughly 15–20 seconds and reports 0 violations	Required Foundry API-version settings are missing	Add LLM_API_VERSION=2025-05-01 and AZURE_OPENAI_API_VERSION=2025-05-01, then recreate or restart the server
stubs_only is reported and no remediation PR is created	An older server image or version is running	Run bash run_on_vm.sh again from the new v7 release folder, then verify that /enforce returns 404

Useful diagnostics

docker compose --env-file .env.azure ps
docker compose --env-file .env.azure logs --tail=200 combined caddy
docker inspect $(docker compose --env-file .env.azure ps -q combined)
ss -lntp | grep -E '(:443|:8080)'
df -h
free -h

Appendix: Optional Azure Container Registry delivery

Use ACR only when the deployment pulls the application image.

Build and push the release image from a machine with Docker, Azure CLI access, and permission to push to the registry:

ACR_NAME=<ACR_NAME> IMAGE_TAG=<RELEASE_TAG> deploy/build_and_push.sh

The resulting image reference follows this format:

<acr-name>.azurecr.io/lineaje-combined:<release-tag>

From the VM, authenticate, pull the selected release, and start the core runtime:

az acr login --name <ACR_NAME>
docker pull <acr-name>.azurecr.io/lineaje-combined:<release-tag>
docker compose --env-file .env.azure up -d combined caddy

For air-gapped delivery, build and export the image before transferring it to the VM:

docker build -t lineaje-combined:<release-tag> .
docker save lineaje-combined:<release-tag> | gzip > lineaje-combined.tar.gz

Use immutable release tags or image digests in production.

Deployment acceptance checklist

• VM sizing and architecture meet requirements.

• Inbound 443 is restricted to approved networks.

• Port 8080 is not externally exposed.

• Managed identity has the required Foundry role.

• Required platform and Foundry endpoints are reachable.

• .env.azure is protected.

• combined and caddy are running.

• Local and remote /health checks succeed.

• An MCP client authenticates and discovers tools.

• The current and rollback releases are recorded.

• Optional integrations are validated when enabled.

Deployment is complete when UnifAI is healthy, HTTPS works, and an approved MCP client discovers tools through /mcp.