141 lines
5.8 KiB
Markdown
141 lines
5.8 KiB
Markdown
# Provisioning Platform Documentation
|
||
|
||
Complete documentation for the Provisioning Platform infrastructure automation system built with Nushell,
|
||
Nickel, and Rust.
|
||
|
||
## 📖 Browse Documentation
|
||
|
||
All documentation is **directly readable** as markdown files in Git/GitHub—mdBook is optional.
|
||
|
||
- **[Table of Contents](src/SUMMARY.md)** – Complete documentation index (188+ pages)
|
||
- **[Browse src/ directory](src/)** – All markdown files organized by topic
|
||
|
||
---
|
||
|
||
## 🚀 Quick Navigation
|
||
|
||
### For Users & Operators
|
||
|
||
- **[Getting Started](src/getting-started/)** – Installation, setup, and first deployment
|
||
- **[Operations Guide](src/operations/)** – Deployment, monitoring, orchestrator management
|
||
- **[Troubleshooting](src/troubleshooting/troubleshooting-guide.md)** – Common issues and solutions
|
||
- **[Security](src/security/)** – Authentication, encryption, secrets management
|
||
|
||
### For Developers & Architects
|
||
|
||
- **[Architecture Overview](src/architecture/)** – System design and integration patterns
|
||
- **[Infrastructure Guide](src/infrastructure/)** – CLI, configuration system, workspaces
|
||
- **[Development Guide](src/development/)** – Extensions, providers, taskservs, build system
|
||
- **[API Reference](src/api-reference/)** – REST API, WebSocket, SDKs, integration examples
|
||
|
||
### For Advanced Users
|
||
|
||
- **[Deployment Guides](src/guides/)** – Multi-provider setup, customization, infrastructure examples
|
||
- **[Integration Guides](src/integration/)** – Gitea, OCI, service mesh, secrets integration
|
||
- **[Testing](src/testing/)** – Test environment setup and validation
|
||
|
||
---
|
||
|
||
## 📚 Documentation Structure
|
||
|
||
```bash
|
||
provisioning/docs/
|
||
├── README.md # This file – navigation hub
|
||
├── book.toml # mdBook configuration
|
||
├── src/ # Source markdown files (version-controlled)
|
||
│ ├── SUMMARY.md # Complete table of contents
|
||
│ ├── getting-started/ # Installation and setup
|
||
│ ├── architecture/ # System design and ADRs
|
||
│ ├── infrastructure/ # CLI, configuration, workspaces
|
||
│ ├── operations/ # Deployment, orchestrator, monitoring
|
||
│ ├── development/ # Extensions, providers, build system
|
||
│ ├── api-reference/ # APIs and SDKs
|
||
│ ├── security/ # Authentication, secrets, encryption
|
||
│ ├── integration/ # Third-party integrations
|
||
│ ├── guides/ # How-to guides and examples
|
||
│ ├── troubleshooting/ # Common issues
|
||
│ └── ... # 12 other sections
|
||
├── book/ # Generated HTML output (Git-ignored)
|
||
└── examples/ # Example workspace configurations
|
||
```
|
||
|
||
### Why `src/` subdirectory
|
||
|
||
This is the **standard mdBook convention**:
|
||
- **Source (`src/`)**: Version-controlled markdown files, directly readable
|
||
- **Output (`book/`)**: Generated HTML/CSS/JS, Git-ignored (regenerated on build)
|
||
|
||
This separation allows the same source files to generate multiple output formats (HTML, PDF, EPUB) without
|
||
cluttering the version-controlled repository.
|
||
|
||
---
|
||
|
||
## 🔨 Building HTML with mdBook
|
||
|
||
If you prefer a formatted HTML website with search, themes, and copy buttons, build with mdBook:
|
||
|
||
### Prerequisites
|
||
|
||
```bash
|
||
bash
|
||
cargo install mdbook
|
||
```
|
||
|
||
### Build & Serve
|
||
|
||
```bash
|
||
bash
|
||
# Navigate to docs directory
|
||
cd provisioning/docs
|
||
|
||
# Build HTML to book/ directory
|
||
mdbook build
|
||
|
||
# Serve locally at http://localhost:3000 (with live reload)
|
||
mdbook serve
|
||
```
|
||
|
||
### Output
|
||
|
||
Generated HTML is available in `provisioning/docs/book/` after building.
|
||
|
||
**Note**: mdBook is entirely optional. The markdown files in `src/` work perfectly fine in any Git
|
||
viewer or text editor.
|
||
|
||
---
|
||
|
||
## 📖 Reading Markdown Directly
|
||
|
||
All documentation is standard GitHub Flavored Markdown. You can:
|
||
|
||
- **GitHub/GitLab**: Click `provisioning/docs/src/` and browse directly
|
||
- **Local Git**: Clone the repo and open any `.md` file in your editor
|
||
- **Text Search**: Use `grep` or your editor's search to find topics across all markdown files
|
||
- **mdBook (optional)**: Build HTML for formatted reading with search and theming
|
||
|
||
---
|
||
|
||
## 🔗 Key Reference Pages
|
||
|
||
| Document | Purpose |
|
||
| ------------------------------------------------------------------------------ | --------------------------------- |
|
||
| [System Overview](src/architecture/system-overview.md) | High-level architecture |
|
||
| [Installation Guide](src/getting-started/installation-guide.md) | Step-by-step setup |
|
||
| [CLI Reference](src/infrastructure/cli-reference.md) | Command reference |
|
||
| [Configuration System](src/infrastructure/configuration-system.md) | Config management |
|
||
| [Security System](src/security/security-system.md) | Authentication & encryption |
|
||
| [Orchestrator](src/operations/orchestrator.md) | Service orchestration |
|
||
| [Workspace Guide](src/infrastructure/workspaces/workspace-guide.md) | Infrastructure workspaces |
|
||
| [ADRs](src/architecture/adr/) | Architecture Decision Records |
|
||
|
||
---
|
||
|
||
## ❓ Questions
|
||
|
||
- **Getting started** → Start with [Installation Guide](src/getting-started/installation-guide.md)
|
||
- **Having issues** → Check [Troubleshooting](src/troubleshooting/troubleshooting-guide.md)
|
||
- **Looking for API docs** → See [API Reference](src/api-reference/)
|
||
- **Want architecture details** → Read [Architecture Overview](src/architecture/architecture-overview.md)
|
||
|
||
For complete navigation, see [Table of Contents](src/SUMMARY.md).
|