nomad Documentation

1. Project Overview & Quickstart (hashicorp/nomad) Copy Chapter

Nomad [](LICENSE) [](https://discuss.hashicorp.com/c/nomad)

Nomad is a simple and flexible workload orchestrator to deploy and manage containers (docker, podman), non-containerized applications (executable, Java), and virtual machines (qemu) across on-prem and clouds at scale.

Nomad is supported on Linux, Windows, and macOS. A commercial version of Nomad, Nomad Enterprise, is also available.

• Documentation - concepts, user guides, reference
• CLI docs
• API docs
• Nomad plugins docs
• Tutorials
• Forum: Discuss

Nomad provides several key features:

• Deploy Containers and Legacy Applications: Nomad’s flexibility as an orchestrator enables an organization to run containers, legacy, and batch applications together on the same infrastructure. Nomad brings core orchestration benefits to legacy applications without needing to containerize via pluggable task drivers.

• Simple & Reliable: Nomad runs as a single binary and is entirely self contained - combining resource management and scheduling into a single system. Nomad does not require any external services for storage or coordination. Nomad automatically handles application, node, and driver failures. Nomad is distributed and resilient, using leader election and state replication to provide high availability in the event of failures.

• Device Plugins & GPU Support: Nomad offers built-in support for GPU workloads such as machine learning (ML) and artificial intelligence (AI). Nomad uses device plugins to automatically detect and utilize resources from hardware devices such as GPU, FPGAs, and TPUs.

• Federation for Multi-Region, Multi-Cloud: Nomad was designed to support infrastructure at a global scale. Nomad supports federation out-of-the-box and can deploy applications across multiple regions and clouds.

• Proven Scalability: Nomad is optimistically concurrent, which increases throughput and reduces latency for workloads. Nomad has been proven to scale to clusters of 10K+ nodes in real-world production environments.

• HashiCorp Ecosystem: Nomad integrates seamlessly with Terraform, Consul, Vault for provisioning, service discovery, and secrets management.

Quick Start Copy Chapter

Testing

Refer to the Getting Started tutorials for instructions on setting up a local Nomad cluster for non-production use.

Optionally, find Terraform manifests for bringing up a development Nomad cluster on a public cloud in the terraform directory.

Production

Refer to Production reference architecture for recommended practices and a reference architecture for production deployments.

Documentation

Nomad product documentation is stored in the web-unified-docs repo.

Roadmap

A timeline of major features expected for the next release or two can be found in the Public Roadmap.

This roadmap is a best guess at any given point, and both release dates and projects in each release are subject to change. Do not take any of these items as commitments, especially ones later than one major release away.

Contributing

See the contributing directory for more developer documentation.

2. Official Technical Reference & Guides (hashicorp/web-unified-docs) Copy Chapter

Web Unified Docs

[!IMPORTANT]
This README is for developers working on the documentation website. If you
want to contribute docs content, refer to the Contribute to HashiCorp
documentation guide.

The project in this repository, hashicorp/web-unified-docs, aims to implement DEVDOT-023: Unified Product Documentation Repository. The RFC for this project was intentionally light on implementation details, in order to foster consensus on the broad direction.

• PR previews: Show broken links in comments for awareness (informational only, don't block PRs)
• Production monitoring: Weekly scans create GitHub issues and send critical alerts to Datadog when users are affected

The weekly broken-link-check-full workflow generates comprehensive broken link reports with prioritization guidance. When contributors create PRs that modify content, the link checker shows any broken links in PR comments with actionable guidance without blocking development.

Quick tips for contributors:

• Fix internal HashiCorp links (high priority)
• Check external docs/API links (medium priority)
• Consider removing unreliable external links (low priority)

For detailed information about the monitoring system, see Broken Link
Monitoring Documentation. The EDU-053: Unified Education Style Guide
for this project was intentionally light on implementation details, in order
to foster consensus on the broad direction.

The existing API (content.hashicorp.com) has endpoints that serve documentation content. You can find the source code in hashicorp/mktg-content-workflows.

The goal of the unified docs API is to host all of HashiCorp's product documentation. The unified docs API will eventually replace the existing content API.

Local development Copy Chapter

Requirements Copy Section

• Docker and Docker Compose (for managing containers)

Quick start Copy Section

To get a migration preview running, run make from the root of this repo. The make command starts the unified-docs Docker profile that spins up a local instance of unified-devdot-api and dev-portal.

Once this command completes, you can access the following endpoints:

• http://localhost:3000 - An instance of the dev-portal container configured to pull from the experimental docs API (this repo). This image depends on the unified docs API (unified-devdot-api).

• http://localhost:8080 - An instance of the unified docs API container (this repo - unified-devdot-api) that serves content from the content directory. On startup, this container processes the content and assets in /content into public/assets and public/content. In addition, the container also generates app/api/docsPaths.json and app/api/versionMetadata.json from the contents within /content.

  Use the following example to test this endpoint: http://localhost:8080/api/content/terraform-plugin-framework/doc/latest/plugin/framework

[!NOTE]
The unified docs API container takes time to process the content and assets. You must wait for both the unified-devdot-api and dev-portal containers to complete before you can successfully test content in the dev-portal preview environment (localhost:3000). Visit http://localhost:8080/api/all-docs-paths to verify the unified-devdot-api container is complete.

To spin this down gracefully, run make clean in a separate terminal.

If you wish to remove the local Docker images as well, run make clean CLEAN_OPTION=full.

More commands Copy Section

The makefile serves as a convenience tool start the local preview. If you need more granular control, the package.json file contains a full list of available commands.

To use these, you will need to intentionally run npm install and npm run prebuild before anything else.

Use npm run coverage to run coverage tests.

Preview environments for unified-docs and dev-portal Copy Section

Unified docs API serves as one of the content APIs for dev-portal (frontend application for DevDot). As a result, when implementing new features, you may need to modify both the backend (this repo) and the frontend (dev-portal).

If you are working on a ticket that requires changes to both the unified docs API and dev-portal, please set custom environment variables for your branch in Vercel to simplify testing instructions.

For example, in Vercel, for your dev-portal branch, you can set the following environment variables:

Vercel will use these values to create deploy previews.

API development Copy Section

Reach out to team #team-web-presence if you need to do local API development

Background Copy Chapter

Project Rationale Copy Section

• Storing documentation in one branch of one repo dramatically simplifies the workflow for contributing documentation.
• Publishing changes to multiple versions can be done in a single PR, as opposed to multiple PRs which is required by the current setup.
• Finding and making the same change across multiple versions is as simple as doing a find-and-replace since all the versioned docs are on the filesystem at the same time.
• Adding a new product is as easy as making a new folder, as opposed to the current process which requires code-changes on the API side and the installation of a GitHub App to monitor for events.
• Sourcing from one branch in one repo eliminates the situation where a missed GitHub event can result in out-of-date documentation. If something goes wrong in the publishing process, simply run it again instead of relying on incoming commit/release events from the GitHub API.
• Since we can make edits to all docs for all products and versions from a single PR, making platform-level changes is dramatically simplified (such as updating to MDX v2, or rewriting URLs).
• Adding new features like content conformance (basically linting for docs) can be done for the entire codebase at once.
• Removes the ability for docs to break the release workflow in product repos.
• Enables us to support fully versioned deployment previews, whereas current previews are limited to the branch being modified.

[Architectural Decision Records](https://github.com/hashicorp/web-unified-docs/tree/main/docs/decisions) Copy Section

Update product repo documentation Copy Chapter

This script helps with product documentation migration to the web-unified-docs repository. When migrating documentation:

1. The web-unified-docs repository becomes the source of truth
2. Original documentation may remain temporarily as a fallback
3. Users should be directed to make future changes in web-unified-docs only

This script automatically adds a prominent notice to all MDX files in the original location, informing contributors where to make future changes.

./scripts/update-mdx-files.sh ~/Desktop/hashicorp/terraform-plugin-framework/website/docs

Example output:

Progress:

Files processed: 135
Files updated: 135
Files with no frontmatter: 0
Files with errors: 0

Completed! All MDX files have been processed.

Run broken link checker locally Copy Chapter

The repository uses a focused broken link monitoring system:

• PR previews: Show broken links in comments for awareness (informational only, don't block PRs)
• Production monitoring: Weekly scans create GitHub issues and Datadog alerts for user-facing problems

The weekly broken-link-check-full workflow generates comprehensive broken link reports. When contributors create PRs that modify content, the link checker shows any broken links in PR comments without blocking development.

For detailed information about the monitoring system, see Broken Link Monitoring Documentation.

UDR Migration Link Check Copy Section

For teams migrating products to UDR (Unified Docs Renderer), use the dedicated migration workflow:

1. Go to Actions → UDR Product Link Check
2. Click "Run workflow" and select your product
3. Review migration-specific broken link analysis in the generated GitHub issue

This workflow provides targeted link checking with migration-focused reporting and prioritization.

Local Testing Copy Section

You can also run the broken link checker locally. The following commands launch a lychee Docker container to check the content directories you specify.

Run the broken link checker on all content.

npm run broken-link

Check a specific directory within content.

npm run broken-link terraform-plugin-framework

Check multiple directories.

npm run broken-link terraform-plugin-framework-log terraform-plugin-mux

Architecture Copy Chapter

The following diagram illustrates the relationships between the unified docs API (this repo), dev-portal, and the existing content API:

graph LR
    subgraph "Content sources (non-migrated)"
        BDY[boundary]
        CSL[consul]
        HCP[hcp-docs]
        NMD[nomad]
        PKR[packer]
        SNT[sentinel]
        TF[terraform]
        TFC[terraform-cdk]
        TFA[terraform-docs-agents]
        TFD[terraform-docs-common]
        VGT[vagrant]
        VLT[vault]
        WPT[waypoint]

        CURALL["/content or /website"]
        BDY & CSL & HCP & NMD & PKR & SNT & TF & TFC & TFA & TFD & VGT & VLT & WPT --> CURALL
    end

    subgraph "Migrated content repo"
        TPF[terraform-plugin-framework]
        TPL[terraform-plugin-log]
        TPM[terraform-plugin-mux]
        TPS[terraform-plugin-sdk]
        TPT[terraform-plugin-testing]
        TFE[terraform-enterprise]

        MIGALL["/content"]
        TPF & TPL & TPM & TPS & TPT & TFE --> MIGALL
    end

    subgraph "APIs"
        CP[Content APIcontent.hashicorp.com]
        UDR[Unified Docs Repositoryweb-unified-docs]
    end

    subgraph "Frontend"
        DP[Dev Portaldev-portal]
    end

    %% BDY & CSL & HCP & NMD & PKR & PTF & SNT & TF & TFC & TFA & TFD & VGT & VLT & WPT --> CP
    %% TPF & TPL & TPM & TPS & TPT --> UDR

    CURALL -->|Current content flow| CP
    MIGALL -->|Migrated content| UDR

    CP -->|Serves most content| DP
    UDR -->|Serves unified/content content| DP

    class TPF,TPL,TPM,TPS,TPT,BDY,CSL,HCP,NMD,PKR,PTF,SNT,TF,TFC,TFA,TFD,VGT,VLT,WPT productRepo

The diagram shows:

• The content API — the existing system that sources product documentation content from product repositories
• The unified docs API — the new system that sources product documentation from this repo's /content directory. The migrated repos will use a directory approach to versioning (rather than the historic branch and tag strategy)
• The Dev Portal — the frontend that serves the main DevDot interface. Dev Portal sources its content from both the existing content API and unified docs API.