Skip to main content
This guide walks you through cloning the repository and running a local preview environment. The preview includes a local instance of the unified docs API and the dev-portal frontend.

​
Prerequisites

You need the following tools installed before you begin:
  • Docker and Docker Compose — required to run the containers
  • Node.js v22 or higher and npm — required for running tests and scripts outside of Docker

​
Start the local preview

1

Clone the repository

Clone only the main branch to save time and disk space:
git clone --single-branch [email protected]:hashicorp/web-unified-docs.git
Then navigate into the cloned directory:
cd web-unified-docs
2

Start the containers

Run make from the root of the repository:
make
This starts the unified-docs Docker Compose profile, which spins up two containers:
ContainerPortDescription
unified-docs-api8080The unified docs API. Processes content from the /content directory on startup.
dev-portal3000The dev-portal frontend, configured to pull from the local unified docs API.
The unified-docs-api container takes time to process all content and assets on first start. Do not navigate to localhost:3000 until both containers have finished starting up.
3

Verify the API is ready

To confirm the unified-docs-api container has finished processing, visit:
http://localhost:8080/api/all-docs-paths
When this endpoint returns a JSON response, the API is ready. You can also test a specific content path:
http://localhost:8080/api/content/terraform-plugin-framework/doc/latest/plugin/framework
4

Open the dev-portal preview

Once both containers are running, open the local dev-portal:
http://localhost:3000
This is a full instance of the dev-portal frontend connected to your local unified docs API. Any content changes you make to the /content directory will be reflected here after the API reprocesses.

​
What each endpoint provides

localhost:3000

The dev-portal frontend. Use this to preview how your content changes appear to users on developer.hashicorp.com.

localhost:8080

The unified docs API. Serves raw content, navigation data, version metadata, and assets from the /content directory.

​
Run tests

To run the test suite with coverage reporting, first install dependencies and run the prebuild step outside of Docker: 
npm install
npm run prebuild
Then run coverage tests: 
npm run coverage

​
Stop the environment

To stop the containers gracefully, run the following in a separate terminal: 
make clean
To also remove the local Docker images (forces a full rebuild next time): 
make clean CLEAN_OPTION=full
If you cannot see local changes in the preview, you may be using a cached Docker image. Run make clean CLEAN_OPTION=full followed by make to force a full rebuild.

​
Troubleshooting

If you are running Docker and cannot see local changes or preview specific doc versions, you may have a stale or cached Docker image. Run:
make clean CLEAN_OPTION=full
make
This removes the local images and rebuilds from scratch.
The dev-portal container depends on unified-docs-api completing its health check before starting. If the dev-portal started before the API finished processing, wait for the API container to pass its health check and then reload localhost:3000.

Build docs developers (and LLMs) love

Get started for freeTalk to us