tf_provider/docs/20_discovery/documentation_build_and_deploy.md

Documentation Build and Deployment Process

Overview

This document describes the process of building and deploying the Terraform Provider documentation for the Nubes Registry. The system uses mkdocs with the material theme for static site generation and S3 for storage. The Registry Server serves these files directly from the S3 bucket.

Architecture

1. Source: Documentation source files are in docs/ and configuration in mkdocs.yml.
2. Build: The static HTML site is built using mkdocs.
   • Note: Since mkdocs is not installed securely in the shell environment, we use the Docker image squidfunk/mkdocs-material.
3. Storage: The built site is uploaded to an S3 bucket named terraform-registry.
4. Serving: The Registry Server (registry-server-build/) reads files from docs/{namespace}/{name}/{version}/ keys in the bucket and serves them via HTTP.

Requirements

• Docker (for building the docs safely)
• mc (S3 client) configured with an alias (e.g., nubes_s3) pointing to the production S3 endpoint.
• Access keys for the S3 bucket.

Step-by-Step Process

1. Build the Documentation

Run the build using Docker to generate the site/ directory:

docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build

This mounts the current directory to /docs in the container and runs mkdocs build. The output is placed in the local site/ directory.

2. Deployment Script (scripts/publish-docs.sh)

We use a helper script to normalize the upload process. The script has been updated to point to the correct bucket path.

Usage:

./scripts/publish-docs.sh <site-dir> <registry-host> <namespace> <name> <version>

Parameters:

• site-dir: Path to the built site (usually site).
• registry-host: The host alias or endpoint (e.g., s3.msk-1.ngcloud.ru or internal logic, but effectively acts as part of the path structure in some versions, currently simplified to upload to docs/...).
• namespace: Provider namespace (e.g., nubes).
• name: Provider name (e.g., nubes).
• version: Semver version (e.g., 1.0.0).

3. Manual Deployment Command

If running manually without the script, use mc to mirror the site/ folder to the target S3 path:

# Example for version 1.0.0
mc cp --recursive site/ nubes_s3/terraform-registry/docs/nubes/nubes/1.0.0/

Troubleshooting

• Missing Dependencies: If mkdocs is not found, always prefer the Docker command above.
• Path Errors: Ensure the S3 path matches docs/<namespace>/<name>/<version>/. The registry server expects this exact structure to map URL paths to S3 keys.
• Bucket Access: Verify mc ls nubes_s3/terraform-registry works before attempting upload.

Recent Changes (Jan 2026)

• Fixed scripts/publish-docs.sh to target the terraform-registry bucket instead of terraform-providers.
• Standardized the S3 path structure to remove REGISTRY_HOST from the directory tree, aligning with registry-server-build/docs.go logic.