From 287dfc0b8b07f3e0b43cc99b2311d96387beaf53 Mon Sep 17 00:00:00 2001
From: Slawomir Koszewski <slawek@koszewscy.waw.pl>
Date: Mon, 20 Apr 2026 07:35:02 +0200
Subject: [PATCH] docs: add README.md with setup instructions and environment
 variables

---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..51bbd16
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# Azure Image Chooser
+
+Azure Image Chooser is a Node.js application that allows users to select Azure VM images from the Azure Marketplace.
+
+Azure Image Chooser has a TypeScript backend (Express) and a React frontend (Vite). At the time of writing this, Node.js 24 is used by the container image and is the recommended version for local runs.
+
+You can run it on your local machine or deploy to any platform that runs containers.
+
+## Environment variables
+
+Required for both local and container run:
+
+- `AZURE_SUBSCRIPTION_ID`: Azure subscription used for Marketplace queries.
+
+Authentication variables (only needed when identity is not provided by the environment):
+
+- `AZURE_TENANT_ID`: Microsoft Entra tenant ID for service principal auth.
+- `AZURE_CLIENT_ID`: Service principal (app registration) client ID.
+- `AZURE_CLIENT_SECRET`: Service principal client secret.
+
+Optional:
+
+- `PORT`: Backend listening port. Default is `3000`.
+
+Local run notes:
+
+- `AZURE_SUBSCRIPTION_ID` must be set.
+- Use either Azure CLI login (`az login`) or the service principal variables above.
+
+Container run notes:
+
+- `AZURE_SUBSCRIPTION_ID` must be passed to the container.
+- Pass `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET` unless your container runtime provides identity (for example Managed Identity / Workload Identity).
+
+## Running on a local machine
+
+Load environment variables from the repository environment file:
+
+```shell
+set -a; source azure.env; set +a
+```
+
+Execute the following commands to install dependencies, build, and run the app:
+
+```shell
+cd app/backend
+npm ci
+
+cd ../frontend
+npm ci
+
+cd backend
+npm run build
+
+cd ../frontend
+npm run build
+
+cd ../backend
+npm run start
+```
+
+The app will block the terminal and start a web server on port 3000. Open http://localhost:3000 in your browser.
+
+## Running with Docker
+
+Build and run the container:
+
+```shell
+docker build -t azure-image-chooser-node ./app
+docker run --rm -p 3000:3000 \
+  -e AZURE_SUBSCRIPTION_ID="subscription_id" \
+  -e AZURE_CLIENT_ID="client_id" \
+  -e AZURE_CLIENT_SECRET="client_secret" \
+  -e AZURE_TENANT_ID="tenant_id" \
+  azure-image-chooser-node
+```
+
+> NOTE: As with local runs, you can omit AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID when the runtime environment already provides Azure credentials.