Troubleshoot Documentation

This repository contains the documentation site for Troubleshoot, a kubectl plugin providing diagnostic tools for Kubernetes applications.

About Troubleshoot

Troubleshoot is a CLI tool that provides pre-installation cluster conformance testing and validation (preflight checks) and post-installation troubleshooting and diagnostics (support bundles).

Preflight Checks

Preflight checks are an easy-to-run set of conformance tests that can be written to verify that specific requirements in a cluster are met.

To run a sample preflight check from a sample application, install the preflight kubectl plugin and run:

kubectl preflight https://preflight.replicated.com

Support Bundle

A support bundle is an archive that's created in-cluster, by collecting logs, cluster information and executing various commands. After creating a support bundle, the cluster operator will normally deliver it to the application vendor for analysis and remote debugging.

To collect a sample support bundle, install the troubleshoot kubectl plugin and run:

kubectl support-bundle https://support-bundle.replicated.com

Documentation Development

Prerequisites

• Node.js 18.x or higher
• NPM (comes with Node.js)

Quick Start

# Install dependencies
make install

# Start development server
make start

# The site will be available at http://localhost:3001

Available Commands

make install               # Install dependencies
make start                 # Start development server
make build                 # Build for production
make serve                 # Serve built site locally
make test                  # Run all tests
make clean                 # Clear cache
make help                  # Show available commands

Deployment

The site is automatically deployed to Netlify when changes are pushed to the main branch.

• Build Command: make build
• Publish Directory: build
• Node Version: 18

The deployment configuration is in netlify.toml and includes:

• URL redirects for legacy paths
• Caching headers for static assets
• Security headers
• SPA fallback routing

Site Structure

This is a Docusaurus site with the following structure:

├── docs/                   # Documentation content
│   ├── preflight/          # Preflight checks
│   ├── support-bundle/     # Support bundle
│   ├── collect/            # Collectors
│   ├── analyze/            # Analyzers
│   ├── redact/             # Redactors
│   └── host-collect-analyze/  # Host utilities
├── src/                    # React components and pages
│   ├── components/         # Reusable components
│   ├── css/               # Custom styling
│   └── pages/             # Custom pages
├── static/                # Static assets
├── tests/                 # Test scripts
└── .github/workflows/     # GitHub Actions

Key Features

• Custom Landing Page: Matches the original troubleshoot.sh design
• Responsive Design: Mobile-friendly with proper breakpoints
• Enhanced Code Blocks: Syntax highlighting with copy buttons
• Search Integration: Algolia DocSearch with automated indexing
• SEO Optimized: Proper meta tags and social cards
• Performance: Optimized builds with caching

Search Setup

The site uses Algolia DocSearch for search functionality. The search is configured to:

• Index automatically: GitHub Actions workflow runs hourly to keep search updated
• Use environment variables: ALGOLIA_APP_ID and ALGOLIA_API_KEY for credentials
• Support contextual search: Results are filtered by section and page context

Environment Variables

For local development with search:

export ALGOLIA_APP_ID="your_app_id"
export ALGOLIA_API_KEY="your_api_key"

For production deployment:

• Netlify: Set in Site settings > Environment variables
• GitHub Actions: Set in Repository secrets

Testing

Run all tests with:

./tests/run-all-tests.sh

Individual tests:

./tests/build-test.sh      # Validates build process and output
./tests/test-search.sh     # Validates search configuration

Troubleshoot Documentation for LLMs

Troubleshoot supports the llms.txt convention for making documentation available to LLMs.

• llms.txt: This file contains Markdown versions of key docs pages.
• llms-full.txt: This file contains the contents of the docs/ directory in the troubleshoot.sh repository.

How LLM Files Are Generated

The static/js/generate-llms.js script generates LLM files:

• static/llms.txt: Curated list of key documentation pages
• static/llms-full.txt: Complete archive of all documentation

This script runs automatically with the prebuild npm hook before every production build. The prebuild hook is defined in package.json. To ensure the prebuild npm hook runs, the Netlify build command must be npm run build (not docusaurus build).

Generated files are excluded from version control (listed in .gitignore) because they are created fresh on every build.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run make test to ensure everything works
5. Submit a pull request

Support

For issues with the documentation site, please file an issue in the Troubleshoot repository.