+
+---
+
+## What is Armada?
+
+Kubernetes was built for services. Armada was built for batch.
+
+When your job volume exceeds what a single cluster can handle, you need a control plane that sits above your fleet — routing jobs intelligently, fairly, and at scale. Armada is that layer.
+
+**Armada solves the problems Kubernetes wasn't designed to handle:**
+
+- **No job queue** — Kubernetes has no concept of ordering. Jobs compete for resources with no fairness guarantees. Armada adds a proper queue with priority, fair-share, and rate limiting.
+- **No multi-cluster coordination** — Each Kubernetes cluster is an island. Armada routes jobs across as many clusters as you need from a single API.
+- **Fine grained gang-scheduling** — Distributed jobs that need all workers to start together (MPI, PyTorch, Spark) are either fully scheduled or held in queue. Armada's implementation is battle-tested at scale with deep fairness and preemption integration.
+- **No fairness across teams** — One team can starve everyone else. Armada enforces fair-share scheduling so heavy users don't permanently dominate shared infrastructure.
+
+Armada is used in production at [G-Research](https://www.gresearch.co.uk/) since 2020, processing **millions of batch jobs per day** across tens of thousands of nodes.
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| 🌐 **Multi-cluster scheduling** | One API across unlimited Kubernetes clusters |
+| ⚖️ **Fair-share queuing** | Dominant resource fairness across teams and queues |
+| 🔗 **Gang scheduling** | Atomic startup for distributed workloads |
+| ⚡ **Preemption** | Urgent jobs bump lower-priority work automatically |
+| 📊 **Prometheus metrics** | Full observability into queue health and cluster utilisation |
+| 🔭 **Lookout UI** | Web interface for monitoring jobs, queues, and clusters |
+| 🔒 **Enterprise-ready** | Secure, highly available, OIDC authentication support |
+
+---
+
+## Getting started
+
+The fastest way to get Armada running locally is with the [Armada Operator](https://github.com/armadaproject/armada-operator):
+
+```bash
+git clone https://github.com/armadaproject/armada-operator.git
+cd armada-operator
+make kind-all
+```
+
+→ **[Full quickstart guide](https://armadaproject.io/quickstart)** — get up and running in an instant!
+
+
+
+### armadactl
+
+`armadactl` is installed automatically when you run `make kind-all`. To install it standalone or on a machine without the full Armada setup:
+
+```bash
+# download via script
+scripts/get-armadactl.sh
+
+# or grab the binary from the release page
+https://github.com/armadaproject/armada/releases/latest
+```
+
+---
+
+## Local development
+
+Armada runs locally via [Goreman](https://github.com/mattn/goreman) — dependencies (Redis, Postgres, Pulsar) run in containers, Armada components run as host processes built from source. Iteration is fast and debuggers attach directly.
+
+```bash
+mage kind # one-time: create local Kubernetes cluster
+export KUBECONFIG=.kube/external/config
+
+mage dev:up # default — no auth
+mage dev:up auth # with OIDC via Keycloak
+mage dev:up fake-executor # no Kubernetes cluster needed
+mage dev:down # stop dependency containers
+```
+
+→ **[Full local development guide](https://armadaproject.io/docs/developer-guide)** — profiles, procfiles, service ports, authentication, and debugging.
+
+---
+
+## Use cases
+
+Armada is used wherever batch jobs are too large, too many, or too complex for a single Kubernetes cluster:
+
+- **Quantitative finance & HPC** — millions of short-lived simulations per day with fair-share across research teams
+- **ML and AI training** — distributed GPU training with gang scheduling across clusters
+- **Platform engineering** — multi-tenant batch infrastructure with a single API surface
+- **SLURM migration** — familiar scheduling semantics (queues, priorities, preemption) on Kubernetes-native infrastructure
+- **CI/CD at scale** — priority control so critical merges always run first
+
+---
+
+## In production
+
+Armada has been running in production at [G-Research](https://www.gresearch.co.uk/) since 2020.
+
+**Running Armada in production?** Open a PR to add yourself to [ADOPTERS.md](./ADOPTERS.md) 🙌
+
+---
+
+## Community
+
+Everyone is welcome — come and say hi! 👋
+
+- 💬 **Slack** — [#armada on CNCF Slack](https://cloud-native.slack.com/archives/C03T9CBCEMC) — fastest way to get help and talk to maintainers
+- 💡 **GitHub Discussions** — [longer-form questions and ideas](https://github.com/armadaproject/armada/discussions)
+- 🐛 **GitHub Issues** — [bug reports and feature requests](https://github.com/armadaproject/armada/issues)
+- 📅 **Community meetings** — bi-weekly, open to all. Join [#armada on Slack](https://cloud-native.slack.com/archives/C03T9CBCEMC) for the invite link
+- ⭐ **Star the repo** — helps more people find Armada
+
+---
+
+## Contributing
+
+We'd love your contributions — code, docs, bug reports, or ideas. All are welcome.
+
+- Read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines
+- Check [good first issues](https://github.com/armadaproject/armada/labels/good%20first%20issue) for a starting point
+- All commits require a [DCO sign-off](https://developercertificate.org/): `git commit -s`
+- Please review [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing
+
+---
+
+## Documentation
+
+| Resource | Link |
+|---|---|
+| Website & overview | [armadaproject.io](https://armadaproject.io) |
+| Quickstart | [armadaproject.io/quickstart](https://armadaproject.io/quickstart) |
+| Architecture | [armadaproject.io/docs/architecture](https://armadaproject.io/docs/architecture) |
+| API reference | [armadaproject.io/docs/api](https://armadaproject.io/docs/api) |
+| Developer guide | [armadaproject.io/docs/developer-guide](https://armadaproject.io/docs/developer-guide) |
+| Release notes | [github.com/armadaproject/armada/releases](https://github.com/armadaproject/armada/releases) |
+
+---
+
+## Talks and videos
+
+- [Armada — high-throughput batch scheduling](https://www.youtube.com/watch?v=FT8pXYciD9A)
+- [Building Armada — Running Batch Jobs at Massive Scale on Kubernetes](https://www.youtube.com/watch?v=B3WPxw3OUl4)
+
+---
+
+
+
+
+
diff --git a/website/.remarkignore b/website/.remarkignore
index 0c28ce9e136..4ff1e0346fa 100644
--- a/website/.remarkignore
+++ b/website/.remarkignore
@@ -9,3 +9,6 @@ tmp.*
# Auto-generated files
python-airflow-operator.md
python-armada-client.md
+
+# Archived files
+_archive/
\ No newline at end of file
diff --git a/website/.remarkrc-md.mjs b/website/.remarkrc-md.mjs
index 8fbff6e5d46..bff8dd9cd82 100644
--- a/website/.remarkrc-md.mjs
+++ b/website/.remarkrc-md.mjs
@@ -2,7 +2,19 @@ const remarkConfig = {
plugins: [
'remark-preset-lint-consistent',
'remark-frontmatter',
- 'remark-validate-links',
+ [
+ 'remark-validate-links',
+ {
+ // Internal links use absolute Next.js routes (e.g. /docs/clients),
+ // not file paths. remark-validate-links resolves paths from the git
+ // root and has no extension resolution, so it can't check these.
+ // Skip route-shaped links; relative links and heading anchors are
+ // still validated.
+ // TODO: add a post-build link check against the static export to
+ // properly validate routes (see check-links.sh).
+ skipPathPatterns: [/\/[^/.]+\/?(#[^/]*)?$/],
+ },
+ ],
[
'remark-lint-no-dead-urls',
{
diff --git a/website/.remarkrc-mdx.mjs b/website/.remarkrc-mdx.mjs
index 2c1b6bf8679..345d1d07634 100644
--- a/website/.remarkrc-mdx.mjs
+++ b/website/.remarkrc-mdx.mjs
@@ -2,7 +2,19 @@ const remarkConfig = {
plugins: [
'remark-mdx',
'remark-mdx-frontmatter',
- 'remark-validate-links',
+ [
+ 'remark-validate-links',
+ {
+ // Internal links use absolute Next.js routes (e.g. /docs/clients),
+ // not file paths. remark-validate-links resolves paths from the git
+ // root and has no extension resolution, so it can't check these.
+ // Skip route-shaped links; relative links and heading anchors are
+ // still validated.
+ // TODO: add a post-build link check against the static export to
+ // properly validate routes (see check-links.sh).
+ skipPathPatterns: [/\/[^/.]+\/?(#[^/]*)?$/],
+ },
+ ],
[
'remark-lint-no-dead-urls',
{
diff --git a/website/README.md b/website/README.md
index b1a39c6743b..b118b144958 100644
--- a/website/README.md
+++ b/website/README.md
@@ -1,42 +1,118 @@
-# Armada - documentation website
+# Armada Website Readme
-This is a [Next.js](https://nextjs.org) project, based on the [Fumadocs](https://fumadocs.dev) framework, bootstrapped
-using:
-
-- [`npx create-next-app@latest`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
-- [`yarn create fumadocs-app`](https://github.com/fuma-nama/fumadocs).
+The Armada documentation site is built with [Next.js](https://nextjs.org) and [Fumadocs](https://fumadocs.dev). All content is written in MDX, Markdown that can include React components.
## Requirements
-- Node.js >= 20.x
-- Yarn ~1.22.22
+Before you start, make sure you have the following installed:
+
+- **Node.js** >= 20.x — [Download](https://nodejs.org)
+- **Yarn** ~1.22.22 — install with `npm install -g yarn` if you don't have it
+
+## Getting started
-## Installation
+All commands should be run from inside the `website/` folder. If you are at the root of the `armada` repository, navigate there first:
-```shell
+```bash
+cd website
+```
+
+### Install dependencies
+
+```bash
yarn install
```
-## Local Development
+### Start the local dev server
```bash
yarn dev
```
-Open http://localhost:3000 on your browser to see the result.
+Open [http://localhost:3000](http://localhost:3000) in your browser. The page will hot-reload as you edit files — you do not need to restart the server after making changes to content or components.
-## Build and Preview
+### GitHub Pages base path
-To build the project for production and preview it, run:
+The live site is deployed to GitHub Pages under a base path. If your changes involve links, images, or assets and you want to make sure they resolve correctly in that environment, copy `.env.example` to `.env.local` and set the base path before running the preview:
```bash
-yarn build
-# then
-yarn preview
+cp .env.example .env.local
+```
+
+Then open `.env.local` and follow the instructions inside. You do not need this for most content changes: only if you are working on routing, assets, or the Next.js config itself.
+
+## How the site works
+
+Every page on the site is an `.mdx` file under `content/`. MDX is Markdown that can also use React components. You write normal Markdown and drop in components (cards, callouts, custom JSX) where you need them.
+
+### Content structure
+
+content/
+├── index.mdx # Homepage / landing page
+├── getting-started.mdx # Quickstart guide
+├── meta.json # Root nav configuration
+├── docs/ # All documentation pages
+│ ├── meta.json
+│ ├── core-concepts.mdx
+│ ├── developer-guide.mdx
+│ └── ...
+└── contribute/ # Contributing section
+├── meta.json
+└── ...
+
+### How the left sidebar nav works
+
+The left sidebar is driven entirely by `meta.json` files — Fumadocs reads them at build time and constructs the page tree from them.
+
+**Root nav — `content/meta.json`**
+
+**Section nav — `content/docs/meta.json`**
+
+A `meta.json` inside a folder controls that section's title, page order, and which pages appear.
+
+**To add a page to the nav:**
+
+1. Create the `.mdx` file in the right folder
+2. Add the filename (without `.mdx`) to the relevant `meta.json` pages array
+
+**To remove a page from the nav:**
+Remove it from `meta.json`.
+
+**To reorder pages:**
+Change the order in the `meta.json` pages array. Top to bottom = top to bottom in the sidebar.
+
+**Important:** A folder with no `meta.json` is completely invisible to the nav. The pages exist and are routable URLs but won't appear in the sidebar. If a page you created isn't showing up, check whether its folder has a `meta.json` and whether that file is listed in it.
+
+### Right TOC
+
+Generated automatically from `##` and `###` Markdown headings only. JSX elements and styled `
`/`` tags do not appear in the TOC regardless of how they look visually.
+
+### The homepage
+
+The homepage is `content/index.mdx` — a content page like any other, served by the `[[...slug]]` catch-all route. The `_(home)` route group in `src/app/` handles the root `/` path and renders `index.mdx` directly.
+
+### The `not-prose` rule
+
+Fumadocs applies typography styles to all MDX content by default. Any custom JSX layout block — a hero section, a card grid, a CTA — needs the `not-prose` class on its outermost element, otherwise Fumadocs' prose styles will override your custom styles:
+
+```mdx
+
+ {/* your custom layout here */}
+
```
-The preview server will start on http://localhost:3000 by default. It also supports base path configuration to mimic
-the GitHub Pages environment. Check the `.env.example` file to see how to set it up.
+### Markdown links inside JSX
+
+Markdown link syntax (`[text](url)`) does not render inside JSX elements. Use anchor tags instead:
+
+```mdx
+{/* This won't work inside a JSX div */}
+[CNCF](https://cncf.io)
+
+{/* Use this instead */}
+
+CNCF
+```
## Format, Lint Content, Lint Code and Spell Check
diff --git a/website/content/architecture.mdx b/website/_archive/architecture.mdx
similarity index 100%
rename from website/content/architecture.mdx
rename to website/_archive/architecture.mdx
diff --git a/website/content/armada-api.mdx b/website/_archive/armada-api.mdx
similarity index 100%
rename from website/content/armada-api.mdx
rename to website/_archive/armada-api.mdx
diff --git a/website/content/armada_airflow_operator.mdx b/website/_archive/armada_airflow_operator.mdx
similarity index 100%
rename from website/content/armada_airflow_operator.mdx
rename to website/_archive/armada_airflow_operator.mdx
diff --git a/website/content/armada_client_package.mdx b/website/_archive/armada_client_package.mdx
similarity index 100%
rename from website/content/armada_client_package.mdx
rename to website/_archive/armada_client_package.mdx
diff --git a/website/content/armada_demo.mdx b/website/_archive/armada_demo.mdx
similarity index 100%
rename from website/content/armada_demo.mdx
rename to website/_archive/armada_demo.mdx
diff --git a/website/content/armada_helm_charts.mdx b/website/_archive/armada_helm_charts.mdx
similarity index 100%
rename from website/content/armada_helm_charts.mdx
rename to website/_archive/armada_helm_charts.mdx
diff --git a/website/content/client_libraries.mdx b/website/_archive/client_libraries.mdx
similarity index 100%
rename from website/content/client_libraries.mdx
rename to website/_archive/client_libraries.mdx
diff --git a/website/content/community.mdx b/website/_archive/community.mdx
similarity index 100%
rename from website/content/community.mdx
rename to website/_archive/community.mdx
diff --git a/website/content/creating_and_submitting_jobs.mdx b/website/_archive/creating_and_submitting_jobs.mdx
similarity index 100%
rename from website/content/creating_and_submitting_jobs.mdx
rename to website/_archive/creating_and_submitting_jobs.mdx
diff --git a/website/content/design/architecture.mdx b/website/_archive/design/architecture.mdx
similarity index 100%
rename from website/content/design/architecture.mdx
rename to website/_archive/design/architecture.mdx
diff --git a/website/content/design/database_interfaces.mdx b/website/_archive/design/database_interfaces.mdx
similarity index 100%
rename from website/content/design/database_interfaces.mdx
rename to website/_archive/design/database_interfaces.mdx
diff --git a/website/content/design/index.mdx b/website/_archive/design/index.mdx
similarity index 100%
rename from website/content/design/index.mdx
rename to website/_archive/design/index.mdx
diff --git a/website/content/design/jobservice/job-service.mdx b/website/_archive/design/jobservice/job-service.mdx
similarity index 100%
rename from website/content/design/jobservice/job-service.mdx
rename to website/_archive/design/jobservice/job-service.mdx
diff --git a/website/content/design/priority.mdx b/website/_archive/design/priority.mdx
similarity index 100%
rename from website/content/design/priority.mdx
rename to website/_archive/design/priority.mdx
diff --git a/website/content/design/relationships_diagram.mdx b/website/_archive/design/relationships_diagram.mdx
similarity index 100%
rename from website/content/design/relationships_diagram.mdx
rename to website/_archive/design/relationships_diagram.mdx
diff --git a/website/content/design/scheduler.mdx b/website/_archive/design/scheduler.mdx
similarity index 100%
rename from website/content/design/scheduler.mdx
rename to website/_archive/design/scheduler.mdx
diff --git a/website/content/developer/api.mdx b/website/_archive/developer/api.mdx
similarity index 100%
rename from website/content/developer/api.mdx
rename to website/_archive/developer/api.mdx
diff --git a/website/content/developer/aws-ec2.mdx b/website/_archive/developer/aws-ec2.mdx
similarity index 100%
rename from website/content/developer/aws-ec2.mdx
rename to website/_archive/developer/aws-ec2.mdx
diff --git a/website/content/developer/manual-localdev.mdx b/website/_archive/developer/manual-localdev.mdx
similarity index 100%
rename from website/content/developer/manual-localdev.mdx
rename to website/_archive/developer/manual-localdev.mdx
diff --git a/website/content/developer/oidc.mdx b/website/_archive/developer/oidc.mdx
similarity index 100%
rename from website/content/developer/oidc.mdx
rename to website/_archive/developer/oidc.mdx
diff --git a/website/content/developer/pprof.mdx b/website/_archive/developer/pprof.mdx
similarity index 100%
rename from website/content/developer/pprof.mdx
rename to website/_archive/developer/pprof.mdx
diff --git a/website/content/developer/ubuntu-setup.mdx b/website/_archive/developer/ubuntu-setup.mdx
similarity index 100%
rename from website/content/developer/ubuntu-setup.mdx
rename to website/_archive/developer/ubuntu-setup.mdx
diff --git a/website/content/developer/ui.mdx b/website/_archive/developer/ui.mdx
similarity index 100%
rename from website/content/developer/ui.mdx
rename to website/_archive/developer/ui.mdx
diff --git a/website/content/developer/usage_metrics.mdx b/website/_archive/developer/usage_metrics.mdx
similarity index 100%
rename from website/content/developer/usage_metrics.mdx
rename to website/_archive/developer/usage_metrics.mdx
diff --git a/website/content/developer/website.mdx b/website/_archive/developer/website.mdx
similarity index 100%
rename from website/content/developer/website.mdx
rename to website/_archive/developer/website.mdx
diff --git a/website/content/developer_guide.mdx b/website/_archive/developer_guide.mdx
similarity index 100%
rename from website/content/developer_guide.mdx
rename to website/_archive/developer_guide.mdx
diff --git a/website/content/development_guide.mdx b/website/_archive/development_guide.mdx
similarity index 100%
rename from website/content/development_guide.mdx
rename to website/_archive/development_guide.mdx
diff --git a/website/content/floating_resources.mdx b/website/_archive/floating_resources.mdx
similarity index 100%
rename from website/content/floating_resources.mdx
rename to website/_archive/floating_resources.mdx
diff --git a/website/content/kubernetes_native_auth.mdx b/website/_archive/kubernetes_native_auth.mdx
similarity index 100%
rename from website/content/kubernetes_native_auth.mdx
rename to website/_archive/kubernetes_native_auth.mdx
diff --git a/website/content/maintaining_consistency_across_views.mdx b/website/_archive/maintaining_consistency_across_views.mdx
similarity index 100%
rename from website/content/maintaining_consistency_across_views.mdx
rename to website/_archive/maintaining_consistency_across_views.mdx
diff --git a/website/content/operator-guide.mdx b/website/_archive/operator-guide.mdx
similarity index 97%
rename from website/content/operator-guide.mdx
rename to website/_archive/operator-guide.mdx
index ff005317886..4e4a6495a71 100644
--- a/website/content/operator-guide.mdx
+++ b/website/_archive/operator-guide.mdx
@@ -26,7 +26,7 @@ Armada consists of several components that work together:
- **Lookout**: Provides job monitoring and web UI
- **Supporting services**: Pulsar (message broker), PostgreSQL, and Redis
-For a detailed explanation of how these components interact, see the [Architecture documentation](./understanding-armada/architecture.mdx).
+For a detailed explanation of how these components interact, see the [Architecture documentation](docs/architecture.mdx).
## Local Installation
@@ -449,11 +449,11 @@ If you encounter issues not covered here:
- **GitHub Issues**: Report bugs and request features at [github.com/armadaproject/armada/issues](https://github.com/armadaproject/armada/issues)
- **Community Slack**: Join discussions on [CNCF Slack](https://cloud-native.slack.com/?redir=%2Farchives%2FC03T9CBCEMC)
-- **Documentation**: Check the [Architecture documentation](./understanding-armada/architecture.mdx) for system design details
+- **Documentation**: Check the [Architecture documentation](docs/architecture.mdx) for system design details
## Additional Resources
-- [Architecture Overview](./understanding-armada/architecture.mdx) - Understand how Armada components work
+- [Architecture Overview](docs/architecture.mdx) - Understand how Armada components work
- [User Guide](./user-guide) - Learn how to submit and manage jobs
- [Armada Operator](https://github.com/armadaproject/armada-operator) - Kubernetes-native deployment option
- [Helm Charts Documentation](https://github.com/armadaproject/armada/tree/master/deployment) - Detailed Helm configuration reference
diff --git a/website/content/priority_algorithm.mdx b/website/_archive/priority_algorithm.mdx
similarity index 100%
rename from website/content/priority_algorithm.mdx
rename to website/_archive/priority_algorithm.mdx
diff --git a/website/content/production-install.mdx b/website/_archive/production-install.mdx
similarity index 100%
rename from website/content/production-install.mdx
rename to website/_archive/production-install.mdx
diff --git a/website/content/quickstart.mdx b/website/_archive/quickstart.mdx
similarity index 100%
rename from website/content/quickstart.mdx
rename to website/_archive/quickstart.mdx
diff --git a/website/content/scheduling_and_preempting_jobs.mdx b/website/_archive/scheduling_and_preempting_jobs.mdx
similarity index 100%
rename from website/content/scheduling_and_preempting_jobs.mdx
rename to website/_archive/scheduling_and_preempting_jobs.mdx
diff --git a/website/content/system_overview.mdx b/website/_archive/system_overview.mdx
similarity index 100%
rename from website/content/system_overview.mdx
rename to website/_archive/system_overview.mdx
diff --git a/website/content/understanding-armada/index.mdx b/website/_archive/understanding-armada/index.mdx
similarity index 85%
rename from website/content/understanding-armada/index.mdx
rename to website/_archive/understanding-armada/index.mdx
index fcba84fced1..d953d6c3c68 100644
--- a/website/content/understanding-armada/index.mdx
+++ b/website/_archive/understanding-armada/index.mdx
@@ -10,7 +10,7 @@ This section provides a comprehensive overview of how Armada works, from its cor
Learn about Armada's system architecture, including its components, event-sourcing design, and how jobs flow through the system from submission to completion.
-[Learn more about Architecture →](./architecture.mdx)
+[Learn more about Architecture →](../docs/architecture.mdx)
## Core Concepts
@@ -18,4 +18,4 @@ Learn about Armada's system architecture, including its components, event-sourci
Explore fundamental concepts like jobs, queues, job sets, priorities, and fair-use scheduling algorithms that make Armada a powerful batch scheduler.
-[Learn more about Core Concepts →](./core-concepts.mdx)
+[Learn more about Core Concepts →](../docs/core-concepts.mdx)
diff --git a/website/_archive/understanding-armada/meta.json b/website/_archive/understanding-armada/meta.json
new file mode 100644
index 00000000000..efbe7311acc
--- /dev/null
+++ b/website/_archive/understanding-armada/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Understanding Armada",
+ "pages": ["index", "architecture", "core-concepts"]
+}
diff --git a/website/content/user-guide/index.mdx b/website/_archive/user-guide/index.mdx
similarity index 100%
rename from website/content/user-guide/index.mdx
rename to website/_archive/user-guide/index.mdx
diff --git a/website/content/user-guide/meta.json b/website/_archive/user-guide/meta.json
similarity index 100%
rename from website/content/user-guide/meta.json
rename to website/_archive/user-guide/meta.json
diff --git a/website/content/contribute/community.mdx b/website/content/contribute/community.mdx
new file mode 100644
index 00000000000..0e26e051686
--- /dev/null
+++ b/website/content/contribute/community.mdx
@@ -0,0 +1,41 @@
+---
+title: 'Community & Adopters'
+description: 'Get help, connect with the community, and see who is using Armada.'
+---
+
+## Connect with us
+
+We'd love to hear from you! Whether you need help, want to contribute, or just want to say hello, there are several ways to connect with our community.
+
+### Slack
+
+Real-time interactions between Armada developers and users occurs primarily in [CNCF Slack](https://cloud-native.slack.com/archives/C03T9CBCEMC). This is where we gather to ask questions, share ideas, and connect with other users and maintainers.
+
+- If you already have an account on CNCF Slack, join #armada on [https://cloud-native.slack.com](https://cloud-native.slack.com)
+- If you need an invitation to CNCF Slack, you can get one at [https://slack.cncf.io](https://slack.cncf.io)
+
+Don't hesitate to reach out if you need help getting started or have questions about using Armada in your environment. If you're wondering whether Armada is right for your use case, we'd love to hear about your requirements and help you evaluate. Jump into Slack and let's talk!
+
+### GitHub Discussions
+
+Armada uses GitHub Discussions for long-form communication and design discussions. To join the conversation there, go to: [https://github.com/armadaproject/armada/discussions](https://github.com/armadaproject/armada/discussions)
+
+This is the best place for brainstorming potential new features, sharing ideas, and having detailed technical discussions.
+
+### GitHub Issues & Pull Requests
+
+Found a bug or have a feature request? Open an issue on our [GitHub repository](https://github.com/armadaproject/armada/issues) and tell us about it. We're always looking for ways to improve.
+
+Have a fix or enhancement ready? We'd love to see your contribution! Submit a pull request on our [GitHub repository](https://github.com/armadaproject/armada/pulls). Whether it's code, documentation, or improvements, every contribution helps make Armada better for everyone.
+
+Interested in contributing but not sure where to start? Check out our [Contributor Guide](/contribute/contributor-guide) and browse open issues on GitHub. There's always something you can help with!
+
+## Community Meetings
+
+We host bi-weekly Armada Outreach meetings where we discuss project updates, gather feedback, and plan future developments. Join us to stay in the loop and share your thoughts! To receive an invitation link, reach out through our Slack channel.
+
+## Adopters
+
+Organizations around the world run Armada in production. See who's using Armada and how they're using it in our **[adopters list on GitHub](https://github.com/armadaproject/armada/blob/master/ADOPTERS.md)**.
+
+Using Armada at your organization? We'd love to hear your story—[add your organization](https://github.com/armadaproject/armada/blob/master/ADOPTERS.md) with a pull request.
diff --git a/website/content/contribute/contributor-guide.mdx b/website/content/contribute/contributor-guide.mdx
index 8b05fe4dec3..c1942b8206f 100644
--- a/website/content/contribute/contributor-guide.mdx
+++ b/website/content/contribute/contributor-guide.mdx
@@ -7,7 +7,7 @@ description: 'Guidelines and tips for contributing to the Armada project.'
To setup your development environment, follow the instructions based on the area you want to contribute to:
-- **For Armada core development**: See the [Developer Guide](../developer-guide.mdx) for local setup, code structure, and development workflows
+- **For Armada core development**: See the [Developer Guide](/docs/developer-guide) for local setup, code structure, and development workflows
- **For Armada Operator development**: See the [Armada Operator repository](https://github.com/armadaproject/armada-operator) for setup instructions and development guidelines
## Reporting Issues
@@ -64,7 +64,7 @@ For more details, see [DCO](https://github.com/apps/dco).
## Communication
-For real-time discussions, Slack channels, GitHub Discussions, and community meetings, see our [Community page](../community.mdx).
+For real-time discussions, Slack channels, GitHub Discussions, and community meetings, see our [Community page](/contribute/community).
## Security
diff --git a/website/content/contribute/index.mdx b/website/content/contribute/index.mdx
index f5de302d0db..3eb7d2974dd 100644
--- a/website/content/contribute/index.mdx
+++ b/website/content/contribute/index.mdx
@@ -20,7 +20,7 @@ import { Cards, Card } from 'fumadocs-ui/components/card';
description='Our community standards and guidelines for participation'
/>
diff --git a/website/content/developer-guide.mdx b/website/content/developer-guide.mdx
deleted file mode 100644
index 98f6a8d0235..00000000000
--- a/website/content/developer-guide.mdx
+++ /dev/null
@@ -1,358 +0,0 @@
----
-title: 'Developer Guide'
-description: 'Set up your development environment and start contributing to Armada'
----
-
-This guide helps you set up a development environment for contributing to Armada or customizing it with new features. For contribution guidelines, see the [Contributor Guide](./contribute/contributor-guide.mdx).
-
-## Prerequisites
-
-Install the following tools before you begin. These are verified requirements from the Armada source code:
-
-- **[Go](https://go.dev/doc/install)** (version 1.26 or later) - Required for building Armada
-- **gcc** (for Windows, see [tdm-gcc](https://jmeubank.github.io/tdm-gcc/)) - Required for CGO compilation
-- **[mage](https://magefile.org/)** - Build tool used throughout the Armada project (similar to Make, written in Go)
-- **[Docker](https://docs.docker.com/get-docker/)** - Container runtime for running dependencies
-- **[kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)** - Kubernetes command-line tool
-- **[protobuf](https://github.com/protocolbuffers/protobuf/releases)** (version 3.17.3 or later) - Protocol buffer compiler (required if you modify `.proto` files)
-- **[kind](https://kind.sigs.k8s.io/)** - Kubernetes in Docker (bootstrapped via `mage BootstrapTools`)
-
-**Note:** Additional tools are automatically installed via `mage BootstrapTools` from [`tools.yaml`](https://github.com/armadaproject/armada/blob/master/tools.yaml), including golangci-lint, sqlc, go-swagger, and others.
-
-## Development Environment Setup
-
-Armada provides two main ways to run components locally for development. Choose the method that best fits your workflow.
-
-### Using `mage dev` (Recommended)
-
-The `mage dev` targets automate the setup process and are the recommended way to get started:
-
-- Bootstraps required tools from [`tools.yaml`](https://github.com/armadaproject/armada/blob/master/tools.yaml)
-- Starts dependencies (Pulsar, Redis, PostgreSQL) in containers
-- Builds and starts Armada components (`mage dev:up` runs them via goreman; `mage dev:full` runs them in containers against a [kind](https://kind.sigs.k8s.io/) cluster)
-
-**Note:** If you edit a proto file, run `mage proto` to regenerate the Go code.
-
-The `mage dev` targets:
-
-```bash
-# Run dependencies in containers and Armada components via goreman (fast iteration)
-mage dev:up
-
-# Run the entire stack in containers against a Kind cluster (what CI uses)
-mage dev:full
-```
-
-We use `mage dev:full` to test the CI pipeline. Use it to test changes to core components.
-
-To stop the local development environment:
-
-```bash
-mage dev:down # stop the dependency containers (after `mage dev:up`)
-mage dev:fullDown # stop the containerized stack and tear down Kind (after `mage dev:full`)
-```
-
-### Using Goreman
-
-[Goreman](https://github.com/mattn/goreman) is a Go-based clone of [Foreman](https://github.com/ddollar/foreman) that manages Procfile-based applications, allowing you to run multiple processes with a single command. Goreman will build the components from source and run them locally, making it easy to test changes quickly.
-
-1. Install `goreman`:
-
- ```bash
- go install github.com/mattn/goreman@latest
- ```
-
-2. Start dependencies:
-
- ```bash
- docker compose -f _local/compose/stack.yaml up -d
- ```
-
- **Note:** Images can be overridden using environment variables: `REDIS_IMAGE`, `POSTGRES_IMAGE`, `PULSAR_IMAGE`, `KEYCLOAK_IMAGE`, `OTEL_IMAGE`, `JAEGER_IMAGE`, `GRAFANA_IMAGE`
-
-3. Initialize databases and Kubernetes resources:
-
- ```bash
- _local/scripts/init.sh
- ```
-
-4. Start Armada components:
- ```bash
- goreman -f _local/procfiles/no-auth.Procfile start
- ```
-
-#### Local Development with Authentication
-
-To run Armada with OIDC authentication enabled using Keycloak:
-
-1. Start dependencies with the auth profile:
-
- ```bash
- docker compose -f _local/compose/stack.yaml --profile auth up -d
- ```
-
- This starts Redis, PostgreSQL, Pulsar, and Keycloak with a pre-configured realm.
-
-2. Initialize databases and Kubernetes resources:
-
- ```bash
- _local/scripts/init.sh
- ```
-
-3. Start Armada components with auth configuration:
-
- ```bash
- goreman -f _local/procfiles/auth.Procfile start
- ```
-
-4. Use armadactl with OIDC authentication:
- ```bash
- armadactl --config _local/.armadactl.yaml --context auth-oidc get queues
- ```
-
-#### Local Development with Fake Executor
-
-For testing Armada without a real Kubernetes cluster, you can use the fake executor that simulates a Kubernetes environment:
-
-```bash
-goreman -f _local/procfiles/fake-executor.Procfile start
-```
-
-The fake executor simulates:
-
-- 2 virtual nodes with 8 CPUs and 32Gi memory each
-- Pod lifecycle management without actual container execution
-- Resource allocation and job state transitions
-
-This is useful for:
-
-- Testing Armada's scheduling logic
-- Development when Kubernetes is not available
-- Integration testing of job flows
-
-### Configuration Options
-
-You can set the `ARMADA_COMPONENTS` environment variable to choose which components to run:
-
-```bash
-export ARMADA_COMPONENTS="server,executor"
-```
-
-### Testing Your Setup
-
-Verify that your development environment is working:
-
-```bash
-# Run the test suite
-mage testsuite
-```
-
-Or manually:
-
-```bash
-go run cmd/armadactl/main.go create queue e2e-test-queue
-export ARMADA_EXECUTOR_INGRESS_URL="http://localhost"
-export ARMADA_EXECUTOR_INGRESS_PORT=5001
-go run cmd/testsuite/main.go test --tests "testsuite/testcases/basic/*" --junit junit.xml
-```
-
-## Code Structure
-
-Understanding Armada's codebase structure will help you navigate and contribute effectively.
-
-### Directory Layout
-
-```
-armada/
-├── cmd/ # Main entry points for all components
-│ ├── server/ # Armada server (API server)
-│ ├── executor/ # Executor (runs in each K8s cluster)
-│ ├── scheduler/ # Scheduler (job scheduling logic)
-│ ├── lookout/ # Lookout (job monitoring/UI backend)
-│ └── armadactl/ # Command-line interface
-├── internal/ # Internal packages (not for external use)
-│ ├── server/ # Server implementation
-│ ├── executor/ # Executor implementation
-│ ├── scheduler/ # Scheduler implementation
-│ ├── lookout/ # Lookout implementation
-│ └── common/ # Shared utilities
-├── pkg/ # Public packages (for external use)
-│ ├── api/ # gRPC API definitions
-│ └── client/ # Client libraries
-├── config/ # Configuration files for components
-├── deployment/ # Helm charts and deployment configs
-├── magefiles/ # Build automation (mage targets)
-└── testsuite/ # Integration test cases
-```
-
-### Key Components
-
-- **Server** (`cmd/server/`, `internal/server/`): The main API server that accepts job submissions and manages queues
-- **Executor** (`cmd/executor/`, `internal/executor/`): Runs in each Kubernetes cluster and executes jobs
-- **Scheduler** (`cmd/scheduler/`, `internal/scheduler/`): Determines when and where jobs should run
-- **Lookout** (`cmd/lookout/`, `internal/lookout/`): Provides job monitoring and UI backend
-- **armadactl** (`cmd/armadactl/`): Command-line interface for interacting with Armada
-
-### Using `mage`
-
-`mage` is the build tool used throughout the Armada project. To see all available commands:
-
-```bash
-mage -l
-```
-
-Common mage targets:
-
-- `mage dev:up` - Run dependencies in containers and Armada components via goreman
-- `mage dev:full` - Run the entire stack in containers against a Kind cluster (what CI uses)
-- `mage buildDockers` - Build Docker images
-- `mage proto` - Generate Go code from proto files
-- `mage testsuite` - Run the test suite
-- `mage ui` - Build and run the Lookout UI
-
-## Debugging and Profiling
-
-### Profiling with pprof
-
-Go provides a profiling tool called [pprof](https://pkg.go.dev/net/http/pprof). To use pprof with Armada, enable the profiling socket in your config.
-
-```yaml
-profiling:
- port: 6060
- hostnames:
- - 'armada-scheduler-profiling.armada.my-k8s-cluster.com'
- clusterIssuer: 'k8s-cluster-issuer'
- auth:
- anonymousAuth: true
- permissionGroupMapping:
- pprof: ['everyone']
-```
-
-### Debugging components
-
-`mage dev:up` builds each component with debug flags (`-gcflags="all=-N -l"`) and runs them as host
-processes, so you can attach a debugger (Delve, VS Code, or GoLand) to any running process directly.
-Each component reads `_local//config.yaml`.
-
-For VS Code, use the launch configurations in `.vscode/launch.json`. See the
-[VS Code Debugging Guide](https://code.visualstudio.com/docs/editor/debugging) for details.
-
-### Debug Port Mappings
-
-| Armada service | Debug host |
-| ----------------- | ---------------- |
-| `server` | `localhost:4000` |
-| `executor` | `localhost:4001` |
-| `binoculars` | `localhost:4002` |
-| `eventingester` | `localhost:4003` |
-| `lookoutui` | `localhost:4004` |
-| `lookout` | `localhost:4005` |
-| `lookoutingester` | `localhost:4007` |
-
-### GoLand Run Configurations
-
-Run configurations are available in the `.run` directory. When opening the project in GoLand, you can run Armada in both standard and debug mode.
-
-**Note:** The executor requires a Kubernetes config in `$PROJECT_DIR$/.kube/internal/config`.
-
-### Other Debugging Methods
-
-Run `mage dev:deps` to only spin up the dependencies (redis, postgres, pulsar), then run individual components yourself. Each component reads its config from `_local//config.yaml`.
-
-## Extending Armada
-
-Armada can be extended and customized in several ways:
-
-### Custom Schedulers
-
-The scheduler is designed to be extensible. You can implement custom scheduling algorithms by modifying the scheduler logic in `internal/scheduler/`. The scheduler handles:
-
-- Job queuing and prioritization
-- Resource allocation
-- Gang scheduling
-- Preemption logic
-
-The scheduler code is located in `internal/scheduler/` and can be customized to implement different scheduling strategies.
-
-### Custom Executors
-
-While the standard executor works with Kubernetes, you could create custom executors for other platforms. The executor interface is defined in `pkg/executorapi/` and communicates with the scheduler via gRPC.
-
-### Client Libraries
-
-Armada provides client libraries for multiple languages that you can extend or use as reference:
-
-- **Python**: [`client/python/`](https://github.com/armadaproject/armada/tree/master/client/python)
-- **Java**: [`client/java/`](https://github.com/armadaproject/armada/tree/master/client/java)
-- **Scala**: [`client/scala/`](https://github.com/armadaproject/armada/tree/master/client/scala)
-- **.NET**: [`client/DotNet/`](https://github.com/armadaproject/armada/tree/master/client/DotNet)
-
-These libraries provide programmatic access to Armada's APIs and can be used as reference for building custom clients.
-
-### Integration Examples
-
-Armada has been integrated with various systems. These can serve as examples for creating your own integrations:
-
-- **Airflow**: [`third_party/airflow/`](https://github.com/armadaproject/armada/tree/master/third_party/airflow) - Airflow operator for Armada
-- **Metaflow**: [armada-metaflow repository](https://github.com/armadaproject/armada-metaflow) - Metaflow decorator for Armada
-- **Jenkins**: [jenkins-plugin repository](https://github.com/armadaproject/jenkins-plugin) - Jenkins plugin for Armada
-- **Spark**: [armada-spark repository](https://github.com/armadaproject/armada-spark) - Spark cluster manager for Armada
-
-### UI Development
-
-To develop the Lookout UI locally, the UI code is located in `internal/lookoutui/`. The UI is built with React and TypeScript.
-
-When using Goreman, the UI runs automatically on http://localhost:3000 (frontend dev server).
-
-To run the UI separately for development:
-
-```bash
-cd internal/lookoutui
-yarn
-yarn openapi
-PROXY_TARGET=http://localhost:8089 yarn dev
-```
-
-This starts a development server on http://localhost:3000 that proxies API requests to the backend.
-
-Alternatively, build a production version with:
-
-```bash
-mage ui
-```
-
-This builds the UI and makes it available at http://localhost:8089.
-
-## Troubleshooting
-
-### Port 6443 Already in Use
-
-If port 6443 is already in use, modify `_local/kind/cluster.yaml` to use a different port:
-
-```yaml
-- containerPort: 6443
- hostPort: 6444 # Change to an available port
- protocol: TCP
-```
-
-### Arm/M1 Mac Issues
-
-On Arm/M1 Macs, you may need to set:
-
-```bash
-export PULSAR_IMAGE=richgross/pulsar:2.11.0
-```
-
-For more information on known issues:
-
-- [Arm issue](https://github.com/armadaproject/armada/issues/2493)
-- [Windows issue](https://github.com/armadaproject/armada/issues/2492)
-
-## Additional Resources
-
-### Website Resources
-
-- [API Reference](./user-guide/api.mdx) - API reference for REST and gRPC
-- [Contributor Guide](./contribute/contributor-guide.mdx) - Contribution guidelines and PR process
-- [Understanding Armada](./understanding-armada) - Core concepts and architecture
-- [Community](./community.mdx) - Get help, connect with the community, and find support resources
diff --git a/website/content/user-guide/api.mdx b/website/content/docs/api.mdx
similarity index 97%
rename from website/content/user-guide/api.mdx
rename to website/content/docs/api.mdx
index c84ffd98951..9ef67f71799 100644
--- a/website/content/user-guide/api.mdx
+++ b/website/content/docs/api.mdx
@@ -78,4 +78,4 @@ For most use cases, we recommend using:
- [OpenAPI Specification](https://github.com/armadaproject/armada/blob/master/pkg/api/api.swagger.json) - Full REST API documentation
- [gRPC API Definitions](https://github.com/armadaproject/armada/tree/master/pkg/api) - Protocol buffer definitions
-- [Client Libraries](./clients.mdx) - Pre-built libraries for popular languages
+- [Client Libraries](/docs/clients) - Pre-built libraries for popular languages
diff --git a/website/content/understanding-armada/architecture.mdx b/website/content/docs/architecture.mdx
similarity index 100%
rename from website/content/understanding-armada/architecture.mdx
rename to website/content/docs/architecture.mdx
diff --git a/website/content/user-guide/cli.mdx b/website/content/docs/cli.mdx
similarity index 100%
rename from website/content/user-guide/cli.mdx
rename to website/content/docs/cli.mdx
diff --git a/website/content/user-guide/clients.mdx b/website/content/docs/clients.mdx
similarity index 100%
rename from website/content/user-guide/clients.mdx
rename to website/content/docs/clients.mdx
diff --git a/website/content/understanding-armada/core-concepts.mdx b/website/content/docs/core-concepts.mdx
similarity index 100%
rename from website/content/understanding-armada/core-concepts.mdx
rename to website/content/docs/core-concepts.mdx
diff --git a/website/content/docs/developer-guide.mdx b/website/content/docs/developer-guide.mdx
new file mode 100644
index 00000000000..8cb2ce592b3
--- /dev/null
+++ b/website/content/docs/developer-guide.mdx
@@ -0,0 +1,343 @@
+---
+title: 'Local Development'
+description: 'Set up your development environment and start contributing to Armada'
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+This guide walks you through setting up a local Armada development environment using Goreman, our recommended approach for contributing to Armada.
+
+## Prerequisites
+
+Before you begin, make sure you have the following installed:
+
+- `Go` — [go.dev](https://go.dev/doc/install)
+- `gcc` — C compiler required by some Go packages
+- `mage` — [magefile.org](https://magefile.org/)
+- `Docker` — [docs.docker.com](https://docs.docker.com/get-docker/)
+- `kubectl` — [kubernetes.io](https://kubernetes.io/docs/tasks/tools/)
+- `protobuf` — Protocol buffer compiler
+- `kind` — [kind.sigs.k8s.io](https://kind.sigs.k8s.io/)
+- `yarn` — [yarnpkg.com](https://yarnpkg.com/getting-started/install) — required for Lookout UI development
+
+
+ Additional tools are automatically installed via `mage BootstrapTools` from
+ `tools.yaml`, including golangci-lint, sqlc, go-swagger, and others.
+
+
+{/* divider */}
+
+
+
+## Using Goreman
+
+[Goreman](https://github.com/mattn/goreman) is a Go-based clone of
+[Foreman](https://github.com/ddollar/foreman) that manages Procfile-based
+applications, allowing you to run multiple processes with a single command.
+Components are built from source and run on the host, so iteration is fast
+and debuggers attach directly.
+
+
+
+
+
+**Clone the repository**
+
+```bash
+git clone https://github.com/armadaproject/armada.git
+cd armada
+```
+
+
+
+
+
+**Create a local Kind cluster**
+
+```bash
+mage kind
+```
+
+This is a one-time setup step.
+
+
+
+
+
+**Start all Armada services**
+
+```bash
+mage dev:up
+```
+
+This starts Redis, PostgreSQL, and Pulsar in containers, then runs the Armada
+server, scheduler, executor, Lookout, and all ingesters as local processes via
+Goreman.
+
+
+
+
+
+**Verify everything is running**
+
+```bash
+goreman run status
+```
+
+Running processes are prefixed with `*`:
+*server
+*scheduler
+*scheduleringester
+*eventingester
+*executor
+*lookout
+*lookoutingester
+*binoculars
+\*lookoutui
+
+
+
+
+
+
+ Restart individual processes without stopping everything:
+
+```bash
+ goreman restart server
+```
+
+
+
+**Useful mage commands**
+
+```bash
+mage dev:up # start dependencies + Armada components via Goreman
+mage dev:full # run the entire stack in containers against Kind (what CI uses)
+mage dev:down # stop dependency containers (after mage dev:up)
+mage dev:fullDown # stop containerised stack and tear down Kind (after mage dev:full)
+mage -l # list all available mage commands
+```
+
+
+ Use `mage dev:full` to replicate what CI runs. Use `mage dev:up` for
+ day-to-day development. It's faster since components run as host
+ processes.
+
+
+{/* divider */}
+
+
+
+## Running with authentication
+
+
+
+
+
+**Start dependencies with the auth profile**
+
+```bash
+docker compose -f _local/compose/stack.yaml --profile auth up -d
+```
+
+This starts Redis, PostgreSQL, Pulsar, and Keycloak with a pre-configured realm.
+
+
+
+
+
+**Initialise databases and Kubernetes resources**
+
+```bash
+_local/scripts/init.sh
+```
+
+
+
+
+
+**Start Armada components with auth configuration**
+
+```bash
+goreman -f _local/procfiles/auth.Procfile start
+```
+
+
+ The first run compiles all Armada components from source which can take
+ several minutes. Subsequent runs are faster as Go caches build artifacts.
+
+
+
+
+
+
+**Use armadactl with OIDC authentication**
+
+```bash
+armadactl --config _local/.armadactl.yaml --context auth-oidc get queues
+```
+
+
+
+
+
+
+ Default Keycloak credentials — Admin: `admin` / `admin` · User: `user` /
+ `password`
+
+
+{/* divider */}
+
+
+
+## Running without a Kubernetes cluster
+
+For testing Armada without a real Kubernetes cluster, use the fake executor
+which simulates a Kubernetes environment:
+
+```bash
+goreman -f _local/procfiles/fake-executor.Procfile start
+```
+
+The fake executor simulates:
+
+- 2 virtual nodes with 8 CPUs and 32Gi memory each
+- Pod lifecycle management without actual container execution
+- Resource allocation and job state transitions
+
+Useful for testing scheduling logic, development when Kubernetes is unavailable,
+and integration testing of job flows.
+
+{/* divider */}
+
+
+
+## Testing your setup
+
+Run the full test suite:
+
+```bash
+mage testsuite
+```
+
+Or manually:
+
+```bash
+go run cmd/armadactl/main.go create queue e2e-test-queue
+export ARMADA_EXECUTOR_INGRESS_URL="http://localhost"
+export ARMADA_EXECUTOR_INGRESS_PORT=5001
+go run cmd/testsuite/main.go test --tests "testsuite/testcases/basic/*" --junit junit.xml
+```
+
+{/* divider */}
+
+
+
+## Profiling with pprof
+
+Enable profiling in your component config:
+
+```yaml
+profiling:
+ port: 6060
+```
+
+Then connect:
+
+```bash
+go tool pprof http://localhost:6060/debug/pprof/profile
+```
+
+{/* divider */}
+
+
+
+## Debug port mappings
+
+| Component | Debug host |
+| ----------------- | ---------------- |
+| `server` | `localhost:4000` |
+| `executor` | `localhost:4001` |
+| `binoculars` | `localhost:4002` |
+| `eventingester` | `localhost:4003` |
+| `lookoutui` | `localhost:4004` |
+| `lookout` | `localhost:4005` |
+| `lookoutingester` | `localhost:4007` |
+
+{/* divider */}
+
+
+
+## Troubleshooting
+
+**Port 6443 already in use**
+
+Modify `_local/kind/cluster.yaml` to use a different port:
+
+```yaml
+- containerPort: 6443
+ hostPort: 6444
+ protocol: TCP
+```
+
+**Arm/M1 Mac issues**
+
+```bash
+export PULSAR_IMAGE=richgross/pulsar:2.11.0
+```
+
+See [Arm issue #2493](https://github.com/armadaproject/armada/issues/2493) and
+[Windows issue #2492](https://github.com/armadaproject/armada/issues/2492) for
+more details.
+
+{/* divider */}
+
+
+
+{/* ── CTA ── */}
+
+
+
+
+
+
Need help?
+
+
+ Ask in the Armada Slack channel or find us on Github!
+
diff --git a/website/content/user-guide/integrations.mdx b/website/content/docs/integrations.mdx
similarity index 100%
rename from website/content/user-guide/integrations.mdx
rename to website/content/docs/integrations.mdx
diff --git a/website/content/docs/meta.json b/website/content/docs/meta.json
new file mode 100644
index 00000000000..1ee45d16627
--- /dev/null
+++ b/website/content/docs/meta.json
@@ -0,0 +1,14 @@
+{
+ "title": "Docs",
+ "pages": [
+ "core-concepts",
+ "developer-guide",
+ "architecture",
+ "cli",
+ "clients",
+ "integrations",
+ "user-guide",
+ "api",
+ "..."
+ ]
+}
diff --git a/website/content/docs/user-guide.mdx b/website/content/docs/user-guide.mdx
new file mode 100644
index 00000000000..40fcdd6fe30
--- /dev/null
+++ b/website/content/docs/user-guide.mdx
@@ -0,0 +1,52 @@
+---
+title: 'User Guide'
+---
+
+**Practical guidance for job submission and management.**
+
+Armada provides multiple ways to interact with the system, allowing you to choose the method that best fits your workflow. Whether you're submitting jobs interactively, integrating with existing pipelines, or building custom applications, Armada has the right interface for you.
+
+## Ways to Interact with Armada
+
+**Command-Line Interface (CLI) - Recommended for Most Users**
+
+`armadactl` is the official command-line tool and the **best way to interact with Armada** for most users. It provides a simple, intuitive interface for submitting jobs, managing queues, monitoring job status, and performing common operations. Built on the [Cobra](https://github.com/spf13/cobra) framework, `armadactl` offers a familiar command-line experience with comprehensive functionality.
+
+**Client Libraries - For Programmatic Access**
+
+For applications and scripts that need to programmatically interact with Armada, client libraries are available in multiple programming languages including Go, Java, Scala, Python, and .NET. These libraries wrap the Armada gRPC APIs and provide type-safe interfaces for job submission and management.
+
+**REST and gRPC APIs - For Custom Integrations**
+
+For custom integrations or when client libraries aren't available in your preferred language, Armada exposes REST and gRPC APIs. These APIs provide full access to all Armada functionality and are ideal for building custom tooling or integrating with existing systems.
+
+**Integrations - For Workflow Orchestration**
+
+Armada integrates seamlessly with popular workflow orchestration tools including Apache Airflow, Metaflow, Jenkins, and Apache Spark. These integrations allow you to leverage Armada's powerful scheduling capabilities within your existing workflows.
+
+## Getting Started
+
+import { Cards, Card } from 'fumadocs-ui/components/card';
+
+
+
+
+
+
+
diff --git a/website/content/getting-started.mdx b/website/content/getting-started.mdx
index 308458a5926..1accd6a9de4 100644
--- a/website/content/getting-started.mdx
+++ b/website/content/getting-started.mdx
@@ -156,7 +156,7 @@ import { Cards, Card } from 'fumadocs-ui/components/card';
diff --git a/website/content/index.mdx b/website/content/index.mdx
index 9fd552922cc..5eaa9f69370 100644
--- a/website/content/index.mdx
+++ b/website/content/index.mdx
@@ -1,198 +1,319 @@
---
-title: Overview
+title: Armada
---
+import Link from 'next/link';
+import {
+ Boxes,
+ Scale,
+ Zap,
+ MoveUpRight,
+ Activity,
+ LayoutGrid,
+} from 'lucide-react';
+import { Cards, Card } from 'fumadocs-ui/components/card';
import { ArmadaIcon, ArmadaText } from '@/components/logo';
-
+
+ ## Armada
+
+
+ {/* headline */}
+
+ One API.
+ Any number of clusters.
+ Millions of jobs.
+
+
+ {/* Armada description */}
+
+ Armada is the open-source batch job meta-scheduler that makes Kubernetes
+ handle massive-scale workloads, with fair queuing, gang scheduling, and multi-cluster
+ orchestration built in.
+
+
+ {/* buttons */}
+
-
-## What is Armada?
-
-Armada is a multi-Kubernetes cluster batch job meta-scheduler designed to handle massive-scale workloads. Built on top of Kubernetes, Armada enables organizations to distribute millions of batch jobs per day across tens of thousands of nodes spanning multiple clusters, making it an ideal solution for high-throughput computational workloads.
-
-Armada serves as middleware that transforms Kubernetes into a powerful batch processing platform while maintaining compatibility with service workloads. It addresses the fundamental limitations of running batch workloads at scale on Kubernetes by providing:
-
-- **Multi-cluster orchestration**: Schedule jobs across many Kubernetes clusters seamlessly
-- **High-throughput queueing**: Handle millions of queued jobs
-- **Advanced batch scheduling**: Fair queuing, gang scheduling, preemption, and resource limits
-- **Enterprise-grade reliability**: Secure, highly available components designed for production use
-
-As a [CNCF Sandbox project](https://www.cncf.io/), Armada is actively maintained and used in production environments, including at [G-Research](https://www.gresearch.com/) where it processes millions of jobs daily.
-
-## Why Use Armada?
-
-### Kubernetes Limitations for Batch Workloads
-
-Traditional Kubernetes faces several challenges when running batch workloads at scale:
-
-1. **Single Cluster Scaling Limits**: Scaling a single Kubernetes cluster beyond a certain size is [challenging](https://openai.com/blog/scaling-kubernetes-to-7500-nodes/), typically maxing out around 5,000-15,000 nodes depending on configuration.
-
-2. **Storage Backend Constraints**: Etcd, Kubernetes' in-cluster storage backend, has [performance limitations](https://etcd.io/docs/v3.5/op-guide/performance/) that make achieving very high throughput difficult and can become a bottleneck for job queuing.
-
-3. **Inadequate Batch Scheduling**: The default [kube-scheduler](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/) lacks essential batch scheduling features like fair queuing, gang scheduling, and intelligent preemption.
-
-### Armada's Solution
-
-Armada overcomes these limitations by:
-
-- **Distributing across multiple clusters**: Manage thousands of nodes across many Kubernetes clusters
-- **Partial Out-of-cluster scheduling**: Leverage external storage backends (e.g., PostgreSQL and Redis) for high-throughput batch job queueing and scheduling
-- **Purpose-built batch scheduler**: Include advanced scheduling features designed specifically for batch workloads
-
-## Key Features and Benefits
-
-### Core Scheduling Features
-
-**Fair-Use Scheduling**
+ rel='noreferrer'
+ className='rounded-lg border border-fd-border px-3.5 py-2 font-medium text-base no-underline transition-all hover:bg-fd-muted hover:shadow-lg hover:shadow-black/20 dark:hover:shadow-white/20'
+ >
+ View on GitHub
+
+
-- Maintains fair resource share over time across users and teams
-- Based on dominant resource fairness principles
-- Includes priority factors for different queues
-- Inspired by HTCondor priority systems
+ {/* divider */}
+
-**High Throughput Processing**
-
-- Handle millions of queued jobs simultaneously
-- Efficient job submission and status tracking
-
-**Gang Scheduling**
-
-- Atomically schedule sets of related jobs
-- Ensures all jobs in a group start together or not at all
-- Critical for distributed computing frameworks like MPI
-
-**Intelligent Preemption**
-
-- Run urgent jobs in a timely fashion
-- Balance resource allocation between users
-- Configurable preemption policies
-
-### Enterprise-Grade Operations
-
-**Massive Scale Support**
-
-- Utilize multiple Kubernetes clusters simultaneously
-- Scale beyond single cluster limitations
-- Add and remove clusters without service disruption
-
-**Advanced Resource Management**
-
-- Resource and job scheduling rate limits
-- Detailed resource allocation controls
-
-**Comprehensive Monitoring**
-
-- Detailed analytics via [Prometheus](https://prometheus.io/) integration
-- Resource allocation and system behavior insights
-- Automatic failure detection and node removal
-
-**Production-Ready Features**
-
-- Secure authentication and authorization
-- High availability architecture
-- Automatic node failure handling
-
-## Use Cases and Success Stories
-
-### High-Performance Computing (HPC)
-
-- **Machine Learning Training**: Distribute large-scale ML training jobs across multiple clusters
-- **Scientific Computing**: Run complex simulations and data analysis workloads
-- **Financial Modeling**: Execute risk calculations and quantitative analysis at scale
-
-### Data Processing Pipelines
-
-- **ETL Workloads**: Process large datasets with parallel batch jobs
-- **Data Analytics**: Run distributed analytics jobs across multiple clusters
-- **Backup and Archival**: Coordinate large-scale data movement operations
+
-### CI/CD and Development
+
-- **Build Systems**: Distribute compilation and testing jobs
-- **Integration Testing**: Run comprehensive test suites across multiple environments
-- **Deployment Automation**: Coordinate complex deployment workflows
+
+ As a [CNCF Sandbox project](https://www.cncf.io/), Armada is actively
+ maintained and used in production environments, including at
+ [G-Research](https://www.gresearch.com/) where it processes millions of jobs
+ daily.
+
-### Production Deployment at G-Research
+{/* divider */}
+
+
+
+{/* ## Why use Armada? */}
+
+
+
+ ## What is Armada?
+
+
+{/* heading */}
+
+
+ The batch scheduler Kubernetes was missing.
+
+
+{/* description */}
+
+
+ Armada sits above your Kubernetes clusters as a control plane. It does not
+ replace Kubernetes, but allows K8 to handle millions of jobs a day across tens
+ of thousands of nodes.
+
+
+{/* cards — left-accent, content stays left-aligned */}
+
+
+ } title='Multi-cluster native' className='border-0 border-l-2 border-fd-primary rounded-sm shadow-md shadow-black/20 dark:shadow-white/10 transition-colors hover:bg-fd-muted'>
+ Run jobs across many clusters through one API, and add or remove capacity without disrupting what's already running.
+
+ } title='Fair-share scheduling' className='border-0 border-l-2 border-fd-primary rounded-sm shadow-md shadow-black/20 dark:shadow-white/10 transition-colors hover:bg-fd-muted'>
+ Every team gets a fair share of resources over time, so heavy users can't crowd everyone else out.
+
+ } title='Gang scheduling' className='border-0 border-l-2 border-fd-primary rounded-sm shadow-md shadow-black/20 dark:shadow-white/10 transition-colors hover:bg-fd-muted'>
+ All the workers in a job start together or not at all, which is what frameworks like MPI, PyTorch, and Spark need.
+
+ } title='Intelligent preemption' className='border-0 border-l-2 border-fd-primary rounded-sm shadow-md shadow-black/20 dark:shadow-white/10 transition-colors hover:bg-fd-muted'>
+ Urgent work can preempt lower-priority jobs to run in time, and you decide how that works per queue.
+
+ } title='High throughput' className='border-0 border-l-2 border-fd-primary rounded-sm shadow-md shadow-black/20 dark:shadow-white/10 transition-colors hover:bg-fd-muted'>
+ Handle millions of queued jobs by moving queueing onto PostgreSQL and Redis instead of leaning on etcd.
+
+ } title='Built for production' className='border-0 border-l-2 border-fd-primary rounded-sm shadow-md shadow-black/20 dark:shadow-white/10 transition-colors hover:bg-fd-muted'>
+ Prometheus metrics, Lookout web UI, secure auth, and automatic handling of failed nodes, all come built in.
+
+
+
+{/* divider */}
+
+
+{/* ## Use cases */}
+
+
+
+ ## Use Cases
+
+
+{/* heading */}
+
+
+ Is Armada right for you?
+
+
+{/* description */}
+
+
+
+
+
+ {/* 01 */}
+
+ 01
+
+ Machine learning training at scale
+
+ Your workers need to start together or not at all. Armada's gang scheduling makes sure they do, across however many clusters have the GPU capacity you need.
+
+
+
+
+ {/* 02 */}
+
+ 02
+
+ Quantitative research and financial modelling
+
+ Millions of short-lived jobs, every day. Armada keeps them moving fairly and fast, with priority controls for the calculations that can't wait.
+
+
+
+
+ {/* 03 */}
+
+ 03
+
+ High-performance computing
+
+ MPI workloads in containers, scheduled across clusters, with hardware-aware placement. Cloud-native tooling without giving up the reproducibility HPC teams depend on.
+
+
+
+
+ {/* 04 */}
+
+ 04
+
+ Multi-tenant compute environments
+
+ Multiple teams, one infrastructure. Fair-share scheduling means no single team can quietly consume everything while others wait.
+
+
+
+
+ {/* 05 */}
+
+ 05
+
+ CI/CD build and test
+
+ Critical merges go first. Large test suites don't block urgent builds. Priority and fairness built in, no manual queue management.
+
+
+
+
+
+
+
+ Armada's niche is multi-cluster. If you're not there yet, another project may be a better fit.
+
+
+ See how Armada compares →
+
+
-G-Research, a leading quantitative research company, uses Armada in production to:
+
+
-- Process millions of jobs per day
-- Manage tens of thousands of nodes
-- Support diverse computational workloads
-- Maintain high availability and performance
+{/* divider */}
-## Comparison with Other Schedulers
+
-### vs. Native Kubernetes Scheduler
+{/* ── CTA ── */}
-- **Scale**: Armada spans multiple clusters vs. single cluster limitation
-- **Throughput**: Millions of jobs vs. thousands with native scheduler
-- **Batch Features**: Purpose-built for batch vs. service-oriented design
-- **Fair Scheduling**: Advanced fair-use policies vs. basic priority classes
+
+
+
+ ## Next Steps
+
-### vs. Traditional HPC Schedulers (SLURM, PBS)
+
-- **Container Native**: Built for containerized workloads vs. traditional HPC
-- **Kubernetes Integration**: Leverages Kubernetes ecosystem vs. isolated systems
-- **Cloud Ready**: Designed for cloud and hybrid environments
-- **Modern APIs**: REST/gRPC APIs vs. command-line interfaces
-- **Rich Client Support**: Client libraries available for multiple languages (Go, Java, Scala, Python and .NET)
+
+ Ready to run batch at scale?
+
-## Next Steps
+
+ Get Armada running locally in minutes. Join the community of organisations running batch workloads on Kubernetes.
+
-Ready to explore Armada? Here are your next steps:
+
+
+ Read the quickstart →
+
+
+ Join #armada on Slack
+
-import { Cards, Card } from 'fumadocs-ui/components/card';
+
+
+ 
+
+ 
-
-
- 
+ 
+ 
+ 
+ 
+