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.