Add quickstart sample(#183)

# Adding a AIO Quickstart Process to accelerate dev and experimental
projects

## Destination Repo Structure (explore-iot-operations)

The destination repo is an Azure-Samples collection with existing
content:

```
explore-iot-operations/
├── samples/                  # 14 existing code samples (auth servers, WASM, dashboards, etc.)
├── tutorials/                # Event-driven Dapr tutorial
├── tools/                    # Schema generation helper
├── docker/                   # WASM Rust build container
├── docs/                     # Repo organization docs
├── README.md                 # Root README (codespace-focused getting started)
├── CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE.md, SECURITY.md, CHANGELOG.md
└── index.html
```

## What Was Migrated

The quickstart content has already been placed under `quickstart/`:

```
quickstart/
├── readme.md                 # Main quickstart guide
├── README_ADVANCED.md        # Detailed technical reference
├── quick_vm_build.md         # VM build instructions
├── arc_build_linux/          # Edge installer scripts
├── arm_templates/            # ARM templates
├── config/                   # Config templates
├── external_configuration/   # Azure configuration scripts
└── modules/                  # Edge modules
    ├── demohistorian/
    └── edgemqttsim/
```

### Content NOT migrated (by design)

These directories from learn-iot are **not** in this repo (they either
don't exist yet, are out of scope, or are handled differently):

| Directory | Reason |
|-----------|--------|
| `Fabric_setup/` | Not yet migrated; referenced in README_ADVANCED.md |
| `operations/` | Dataflow YAML examples; not yet migrated |
| `docs/img/` | Process diagrams; image references will be removed for
now |
| `issues/` | Repo-specific issue tracking; not applicable here |
| `modules/sputnik/` | Not migrated |
| `modules/hello-flask/` | Not migrated |
| `bugfix.md` | Development notes; not applicable |

---

## Changes Required

### 1. `docs/ORGANIZATION.md` — Add quickstart to repo structure

The organization doc currently only describes `samples/` and
`tutorials/`. It needs a new **Quickstart** section to explain the
`quickstart/` directory, its purpose, and how it differs from samples
and tutorials.

**Changes:**
- Add `quickstart/` to the directory tree diagram
- Add a paragraph explaining the quickstart's purpose and scope
- Preserve all existing content about samples and tutorials

### 2. `README.md` (root) — Add quickstart entry point

The root README currently focuses on the GitHub Codespaces experience.
The quickstart is a complementary path for deploying on real hardware or
AKS Edge Essentials.

**Changes:**
- Add a "Quickstart: Deploy on Real Hardware" section after the existing
Getting Started
- Brief description with a link to `quickstart/readme.md`
- Mention that the quickstart is for production-oriented deployments vs.
the codespace path
- Keep all existing content intact (codespace badge, existing Getting
Started, Contributing, etc.)

### 3. `quickstart/readme.md` — Fix references for new repo context

All internal paths and clone URLs currently reference
`BillmanH/learn-iot`. These need to point to the correct locations
within this repo.

**Key changes:**
- **Clone URL**: `BillmanH/learn-iot` →
`Azure-Samples/explore-iot-operations`
- **ZIP download URL**: Updated similarly
- **Clone target directory**: `learn-iot` → `explore-iot-operations`
- **Working directory**: After clone, `cd` into `quickstart/`
- **Relative path references**: Paths like
`arc_build_linux/installer.sh` are correct (relative to `quickstart/`)
- **Image reference**: `![Process Overview](docs/img/process_1.png)` —
removed (image not migrated)
- **Image references**: `![resources pre iot](docs/img/...)` and
`![resources post iot](docs/img/...)` — removed
- **Fabric setup link**: Updated to note content is in the source repo
or removed
- **Issue tracker link**: Updated to this repo's issues
- **Context framing**: Add a note that this quickstart lives within the
larger explore-iot-operations repo

### 4. `quickstart/README_ADVANCED.md` — Fix internal references

**Key changes:**
- **Repository structure diagram**: `learn-iothub/` → updated to reflect
`quickstart/` layout
- **References to `iotopps/`**: The source repo used `iotopps/` for edge
apps; this repo uses `modules/`. Update all references.
- **Clone/download references**: Same URL updates as the main readme
- **Fabric setup link**:
`fabric_setup/fabric-realtime-intelligence-setup.md` → note not migrated
- **Diagnostic script paths**: Already correct (relative to
`arc_build_linux/`)

---

## What This Plan Does NOT Change

- **No file moves or renames** — all quickstart files stay under
`quickstart/`
- **No code changes** — scripts, templates, and application code are
untouched
- **No changes to existing samples/** — all 14 existing samples remain
as-is
- **No changes to tutorials/** — existing tutorial content is preserved
- **No changes to tools/, docker/, .devcontainer/** — infrastructure
files untouched
- **No changes to CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE.md,
SECURITY.md, CHANGELOG.md**

---------

Co-authored-by: william_harding <wharding@microsoft.com>

Author: BillmanH

.gitignore

@@ -422,3 +422,8 @@ target
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 install.sh
+
+
+
+*/config/aio_config.json
+docs/branding/*

README.md

@@ -1,21 +1,28 @@
 # Explore IoT Operations
 
-This repo is the source of tools, samples, tutorials, and other resources for customers of Azure IoT Operations.
+This repo is the source of tools, samples, quickstarts, tutorials, and other resources for customers of Azure IoT Operations.
 
 ## Features
 
 This project provides the following:
 
 * Pre-configured codespace with [K3s](https://k3s.io/) cluster via [K3d](https://k3d.io/)
+* [IoT Operations Quickstart](./quickstart/readme.md) — automated deployment on real edge hardware (Ubuntu/K3s) or a single Windows machine (AKS Edge Essentials)
 * MQTT Device Simulator
+* Edge modules: factory equipment simulator, MQTT historian
+* Samples for auth servers, WASM dataflow operators, custom RBAC, observability, and more
 
 > [!IMPORTANT]
-> Codespaces are easy to setup quickly and tear down later, but they're not suitable for performance evaluation or scale testing. For those scenarios, use a validated environment from the official documentation.
+> Codespaces are easy to setup quickly and tear down later, but they're not suitable for performance evaluation or scale testing. For those scenarios, use the [IoT Operations Quickstart](./quickstart/readme.md) or a validated environment from the official documentation.
 >
 
 
 ## Getting Started
 
+### Option A: GitHub Codespaces (browser-based, no local install)
+
+> **Note:** Codespaces are ephemeral — they are automatically stopped after a period of inactivity and deleted after a retention period. They are great for exploration and learning, but not suitable for persistent environments. For a lasting deployment, use [Option B](#option-b-iot-operations-quickstart-deploy-on-your-own-hardware-or-vm).
+
 1. Use this GitHub codespace to explore Azure IoT Operations in your browser without installing anything on your local machine.
 
    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/explore-iot-operations?quickstart=1)
@@ -36,6 +43,36 @@ This project provides the following:
 
 3. Explore!
 
+### Option B: IoT Operations Quickstart (deploy on your own hardware or VM)
+
+For persistent deployments on machines you control — Ubuntu devices, Windows PCs, or VMs — use the **[IoT Operations Quickstart](./quickstart/readme.md)**. It provides:
+
+- One-command edge setup on Ubuntu with K3s
+- Automated Azure configuration from a Windows management machine
+- Industrial IoT demo apps (factory simulator, MQTT historian)
+- Dataflow pipelines to Azure (ADX, Event Hubs, Fabric) using Managed Identity
+
+Two paths are supported:
+
+| Path | Target | Guide |
+|------|--------|-------|
+| **Ubuntu / K3s** | Ubuntu device, NUC, PC, or VM | [Quickstart README](./quickstart/readme.md) |
+| **AKS Edge Essentials** | Windows device, PC, or VM | [Quickstart README — Path B](./quickstart/readme.md#path-b-single-windows-machine-aks-ee) |
+
+See the [Advanced Guide](./quickstart/README_ADVANCED.md) for detailed technical reference, troubleshooting, and operations documentation.
+
+## Repository Structure
+
+```
+├── quickstart/         Automated IoT Operations deployment on edge hardware
+├── samples/            Code samples and tools
+├── tutorials/          Step-by-step walkthroughs
+├── tools/              Utility tools (schema generator, etc.)
+└── docker/             Container build assets
+```
+
+See [Organization docs](./docs/ORGANIZATION.md) for conventions and contribution guidelines.
+
 ## Contributing
 
 Please view the developer guides in the docs directory to get started with contributions. Get started with the [Organization docs](./docs/ORGANIZATION.md) and [Code of Conduct](CODE_OF_CONDUCT.md).

docs/ORGANIZATION.md

@@ -2,9 +2,17 @@
 
 ## Structure
 
-Explore IoT Operations is a collection of tools and samples for customers of Azure IoT Operations. To keep the project understandable and extensible to future additions, the following conventions should be followed for repository structure.
+Explore IoT Operations is a collection of tools, samples, and quickstart deployments for customers of Azure IoT Operations. To keep the project understandable and extensible to future additions, the following conventions should be followed for repository structure.
 
 ```
+├── quickstart/
+│   ├── arc_build_linux/
+│   ├── arm_templates/
+│   ├── config/
+│   ├── external_configuration/
+│   ├── modules/
+│   ├── readme.md
+│   └── README_ADVANCED.md
 ├── samples/
 │   ├── sample1/
 │   ├── ...
@@ -13,7 +21,10 @@ Explore IoT Operations is a collection of tools and samples for customers of Azu
 └── README.md
 ```
 
+**Quickstart** (`./quickstart`) is an automated, end-to-end deployment of Azure IoT Operations on real edge hardware (Ubuntu/K3s) or a single Windows machine (AKS Edge Essentials). It includes edge installer scripts, Azure configuration scripts, ARM templates, and deployable edge modules (factory simulator, MQTT historian). The quickstart is designed for users who want to stand up a production-oriented IoT Operations environment — as opposed to the GitHub Codespaces path — and validate their own dataflow pipelines and Fabric integration. See the [quickstart README](../quickstart/readme.md) for full instructions and the [advanced guide](../quickstart/README_ADVANCED.md) for detailed technical reference.
+
 **Samples** (`./samples`) are tools or code samples which can be written in any language. They should be given a descriptive name which adequately describes their purpose, and should include some level of documentation regarding their usage.
+
 **Tutorials** (`./tutorials`) are collections of code and documentation which are used together to provide a step-by-step walkthrough to demonstrate the capabilities of some feature of Azure IoT Operations. These typically serve a more narrow scope than that of a tool or code sample, designed to exercise specific facets of Azure IoT Operations.
 
 ## Linting, Formatting, and Testing Requirements