Appendix Materials

Deployment Manual, User Guide, Development Blogs, and Monthly Videos

Page Map

Quick links to sections on this page.

User Manual

This repository includes a full user manual for the Virtual Situation Room. The manual documents platform navigation, analyst workflows, and visual references.

Open the User Manual

Deployment Manual

Step 1 — Repository

Full repository steps:

Fork or clone the GitHub repository into your own account: git clone <repo-url> and create a deployment branch: git checkout -b deploy/my-environment.
Copy the sample environment file: cp .env.example .env and populate all required keys. See the repository README for descriptions of each variable and any provider-specific values (Mapbox token, Azure resource endpoints, etc.).

Install dependencies and run local checks (recommended):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py test

Commit configuration changes (do NOT commit secrets) and push to your deployment branch to trigger CI/CD workflows once secrets are configured in GitHub.

Backend Deployment

Required Azure configuration: this backend requires provisioning and configuration of the following services — Azure Database for PostgreSQL, Azure AI (multi-service) resource, Azure Blob Storage, and an App Service host. See the provider docs below:

Create an Azure App Service

Steps:

Choose a plan: B1 for development; Standard or Premium for production and to enable deployment slots.
Set the publish option to Code when creating the App Service.
Select Python 3.12 as the runtime stack (or the runtime matching your environment).
Optionally connect the App Service to your GitHub repo to enable continuous deployment via GitHub Actions or use publish profile deployment.

Notes: when connecting GitHub, ensure the deployment branch is correct and that required build environment variables are provided as repository secrets.

Configure environment variables

Steps:

Open the Azure Portal for your App Service resource.
Navigate to Settings → Configuration and add Application settings. Add each key/value from your local `.env` into App Settings (do NOT store raw secrets in source control).
Prefer referencing production secrets from Azure Key Vault and use managed identities to surface them to App Service when possible.

Add startup script

Set the startup command in Settings → Configuration → Stack settings (Stack settings / Startup command):

gunicorn --bind=0.0.0.0 --timeout 600 --workers 2 --worker-class uvicorn.workers.UvicornWorker djangoBackend.vsrBackend.asgi:application

Adjust the number of workers for production load and monitor logs in Application Insights/Log stream to confirm the process is healthy.

Add deployment slots

By default the App Service has a single production slot.
Add a staging slot (requires Standard/Premium plan) to enable zero-downtime swaps.

Frontend Deployment

Required configuration: the frontend is deployed to Azure Static Web Apps and must be configured with build-time environment variables so it can reach the backend. Ensure the backend App Service is configured with CORS to allow the frontend origin. Key variables include VITE_API_BASE_URL, VITE_CHATBOT_API_BASE_URL, and VITE_MAPBOX_TOKEN.

Create an Azure Static Web App

Steps:

Create the Static Web App in the Azure Portal and connect it to the frontend repository and branch used for the build.
Configure the build artifact location and, if applicable, the folder containing the frontend sources (for this repo, point to the `website-template` folder or the static build output directory).

Configure build-time environment variables

Steps:

In the Static Web App configuration, add environment variables required at build time. Typical keys:
- VITE_API_BASE_URL — the backend base URL used by the frontend
- VITE_CHATBOT_API_BASE_URL — backend URL + /chatbot
- VITE_MAPBOX_TOKEN — Mapbox token used for map tiles
Run a test build and verify generated assets reference the expected endpoints.

Update backend configuration

Steps:

Open your backend App Service resource and navigate to Settings → Configuration.
Set FRONTEND_URL and DJANGO_CORS_ALLOWED_ORIGINS to the deployed frontend URL so the backend accepts requests from the static site origin.

GitHub Actions secrets (required)

Full instructions: configure required secrets in the repository before enabling CI/CD. Go to Settings → Secrets and variables → Actions and add each secret value. Do not commit secrets to source control. For deploys that use the Azure CLI or Azure/login action, you can provide either individual values (AZURE_SUBSCRIPTION_ID, AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET) or a single AZURE_CREDENTIALS JSON used by azure/login (format shown below).

After adding secrets, validate by pushing to your deployment branch and checking the Actions run logs. If a workflow fails due to missing or invalid secrets, the logs will indicate which step failed.

Required secrets (examples)

FRONTEND_VITE_API_BASE_URL — frontend build: API base URL used at build time
FRONTEND_VITE_CHATBOT_API_BASE_URL — frontend build: chatbot API URL
VITE_MAPBOX_TOKEN — Mapbox token for map tiles
AZURE_STATIC_WEB_APPS_API_TOKEN — optional token for Static Web Apps deploy
AZURE_WEBAPP_PUBLISH_PROFILE — App Service publish profile XML (paste contents)
AZURE_SUBSCRIPTION_ID, AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET — service principal credentials (or provide AZURE_CREDENTIALS JSON below)

Using AZURE_CREDENTIALS (recommended for CI)

Create a single JSON with the required fields and store it as a GitHub secret named AZURE_CREDENTIALS:

{"clientId":"","clientSecret":"","subscriptionId":"","tenantId":""}

Sample workflow snippets

Static Web Apps action (frontend):

uses: Azure/static-web-apps-deploy@v1
with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'

App Service deploy (backend) via publish profile:

uses: azure/webapps-deploy@v2
with:
  publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
  package: '.'

Azure App Registration (client id / tenant id)

To create a service principal and obtain IDs for automated deployment:

Azure Portal → Azure Active Directory → App registrations → New registration
- Name: e.g., vsr-backend-deployer
- Account type: Single-tenant (typical)
After creation: copy Application (client) ID → AZURE_CLIENT_ID and Directory (tenant) ID → AZURE_TENANT_ID.
Create a client secret: Certificates & secrets → New client secret and save the value → AZURE_CLIENT_SECRET.
Grant role to the service principal: Subscriptions → select subscription → Access control (IAM) → Add role assignment → assign Contributor (or narrower) to the registered app.
Optional: create an AZURE_CREDENTIALS JSON and store it in GitHub secrets for azure/login.

To obtain the App Service publish profile: App Service → Overview → Get publish profile and paste the XML into the GitHub secret AZURE_WEBAPP_PUBLISH_PROFILE.

Best practices & operational recommendations

Operational recommendations — full guidance:

Secrets management: store production secrets in Azure Key Vault and reference them from App Service (use managed identities) rather than embedding secrets in the repository or environment files.
Backups: enable automatic backups for Azure Database for PostgreSQL and periodically perform restore drills to validate backups.
Monitoring: enable Application Insights and configure alerts for failed requests, high CPU, memory pressure, and error rates; configure log retention and access controls.
HTTPS & domains: enforce HTTPS, configure custom domains, and use managed TLS certificates where possible.
Deployment strategy: use deployment slots for zero-downtime releases; consider blue/green or canary deployments for safe rollouts.
Secrets rotation: rotate client secrets and remove unused service principals regularly; record rotation policies in runbooks.
Onboarding: document required GitHub Actions secrets and their use cases for new team members; maintain a secure checklist for provisioning new environments.

Verification checklist

App Service health endpoint responds and returns 200.
Django migrations completed and database tables present.
Static assets served and frontend can call backend endpoints.
GitHub Actions workflows run successfully on push and on PRs.

Legal and GDPR Statement

1. GDPR (UK) Compliance Statement — Data Protection and Privacy Notice

This platform is committed to complying with the UK General Data Protection Regulation (UK GDPR).

Scope of Data Processing

The platform is designed for public and analytical use and:

Does not collect, store, or process personal data from general users of the platform.
Does not require user registration or authentication for public access.
Does not use tracking technologies that identify individual users.

Administrator Accounts

The platform maintains a limited number of administrator ("admin") accounts for operational and maintenance purposes. These accounts may involve the processing of basic personal data, including:

Name
Institutional email address
Role or organisational affiliation

This admin data is strictly limited to authorised administrators only, used solely for system administration, maintenance, and security purposes, and is not shared with third parties unless required by law or institutional policy.

Lawful Basis for Processing (Admins Only)

Processing of admin personal data is carried out on the lawful basis of legitimate interests and for the performance of tasks carried out in the public interest or in the exercise of official authority, where applicable. Retention and access controls are implemented in accordance with institutional policies.

Contact

For queries regarding this statement or data protection practices, contact:

Dr. Yun Fu — yun.fu@ucl.ac.uk
Paola Yela — paola.yela@ifrc.org

2. Source Code License and Usage Restrictions — Proprietary License Notice

This software and its associated source code (the "Software") are proprietary and confidential.

Permitted Use

Access to and use of the Software is strictly limited to:

Designated UCL examiners
Approved project partners
Authorised administrators responsible for system management

Use is permitted solely for:

Academic evaluation
Research collaboration
Internal project review
System administration and maintenance (for authorised administrators only)

Restrictions

The following actions are strictly prohibited without prior written consent from the project owner:

Copying, reproducing, or redistributing the Software
Modifying, adapting, or creating derivative works
Reverse engineering, decompiling, or disassembling any part of the Software
Publishing, sublicensing, or making the Software publicly available
Using the Software for commercial purposes

Development Blog and Monthly Videos

We maintained a single project blog for development updates.

Virtual Situation Room Blogspot

Monthly Videos

Month	Video Link	Coverage Summary
December	December Update Video	Scoping, requirements, and building the data ingestion agent.
January	January Update Video	Developing the data ingestion pipeline, agent orchestration, and iterating the frontend.
February	February Update Video	Pipeline consolidation, data sources addition, extra agentic features, and Azure setup.
March	March Update Video	Recap of the development progress of the VSR, extra features, deployment, and recent changes.

Bibliography

References (IEEE)

[1] International Federation of Red Cross and Red Crescent Societies, "IFRC GO." [Online]. Available: https://go.ifrc.org/. [Accessed: Mar. Mar. 26, 2026].
[2] United Nations Office for the Coordination of Humanitarian Affairs, "Humanitarian Action." [Online]. Available: https://humanitarianaction.info/. [Accessed: Mar. Mar. 26, 2026].
[3] IFRC Virtual Situation Room, "Situation Room Prototype." [Online]. Available: https://situation-room.ai/mmr. [Accessed: Mar. Mar. 26, 2026].
[4] IFRC GO, "Learnings from an LLM-powered Virtual Situation Room dashboard," Medium, 2024. [Online]. Available: https://ifrcgoproject.medium.com/learnings-from-an-llm-powered-virtual-situation-room-dashboard-9b2ed3f7342a. [Accessed: Mar. Mar. 26, 2026].
[5] P. Lewis et al., "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks," in Advances in Neural Information Processing Systems, vol. 33, 2020. [Online]. Available: https://arxiv.org/abs/2005.11401. [Accessed: Mar. Mar. 26, 2026].
[6] National Institute of Standards and Technology, "Artificial Intelligence Risk Management Framework (AI RMF 1.0)," NIST AI 100-1, Jan. 2023. [Online]. Available: https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.100-1.pdf. [Accessed: Mar. Mar. 26, 2026].