<p align="center">
    <img src="../resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
</p>

<p align="center">
    <img src="../resources/logo-text.svg" alt="Provisioning" width="500"/>
</p>

# User Guides

Step-by-step guides for common workflows, best practices, and advanced operational
scenarios using the Provisioning platform.

## Overview

This section provides practical guides for:

- **Getting started** - From-scratch deployment and initial setup
- **Organization** - Workspace management and multi-cloud strategies
- **Automation** - Advanced workflow orchestration and GitOps
- **Operations** - Disaster recovery, secrets rotation, cost governance
- **Integration** - Hybrid cloud setup, zero-trust networks, legacy migration
- **Scaling** - Multi-tenant environments, high availability, performance optimization

Each guide includes step-by-step instructions, configuration examples, troubleshooting, and best practices.

## Getting Started

### I'm completely new to Provisioning

Start with: **[From Scratch Guide](./from-scratch.md)** - Complete walkthrough from installation through first deployment with explanations and examples.

### I want to organize infrastructure

Read: **[Workspace Management](./workspace-management.md)** - Best practices for organizing workspaces, isolation, and multi-team setup.

## Core Workflow Guides

- **[From Scratch Guide](./from-scratch.md)** - Installation, workspace creation,
  first deployment step-by-step

- **[Workspace Management](./workspace-management.md)** - Organization best
  practices, multi-tenancy, collaboration, customization, schemas

- **[Multi-Cloud Deployment](./multi-cloud-deployment.md)** - Deploy across
  AWS, UpCloud, Hetzner with abstraction and failover

<p align="center">
    <img src="../resources/diagrams/examples/multi-cloud-deployment.svg"
         alt="Multi-Cloud Deployment AWS UpCloud Hetzner Provider Abstraction" width="800"/>
</p>

- **[Advanced Workflow Orchestration](./advanced-workflow-orchestration.md)** -
  DAG scheduling, parallel execution, logic, error handling, multi-environment

<p align="center">
    <img src="../resources/diagrams/workflows/deployment-pipeline.svg"
         alt="Deployment Pipeline Dev Staging Canary Production with Validation Gates" width="850"/>
</p>

## Advanced Operational Guides

- **[Hybrid Cloud Deployment](./hybrid-cloud-deployment.md)** - Hub-and-spoke
  architecture connecting on-premise and cloud infrastructure

- **[GitOps Infrastructure Deployment](./gitops-infrastructure-deployment.md)**
  - GitHub Actions, reconciliation, drift detection, audit trails

- **[Advanced Networking](./advanced-networking.md)** - Load balancing,
  service mesh, DNS, zero-trust architecture, network policies

- **[Secrets Rotation Strategy](./secrets-rotation-strategy.md)** - Password,
  API key, certificate, encryption key rotation with zero downtime

## Enterprise Features

- **[Custom Extensions](./custom-extensions.md)** - Custom providers, task
  services, detectors, Nushell plugins

- **[Disaster Recovery Guide](./disaster-recovery.md)** - DR planning, backup,
  failover procedures, testing, recovery time optimization

- **[Legacy System Migration](./legacy-system-migration.md)** - Zero-downtime
  migration with gradual traffic cutover and validation

## Quick Navigation

### I need to

**Deploy infrastructure quickly** → [From Scratch Guide](./from-scratch.md)

**Organize multiple workspaces** → [Workspace Management](./workspace-management.md)

**Deploy across clouds** → [Multi-Cloud Deployment](./multi-cloud-deployment.md)

**Build complex workflows** → [Advanced Workflow Orchestration](./advanced-workflow-orchestration.md)

**Set up GitOps** → [GitOps Infrastructure Deployment](./gitops-infrastructure-deployment.md)

**Handle disasters** → [Disaster Recovery Guide](./disaster-recovery.md)

**Rotate secrets safely** → [Secrets Rotation Strategy](./secrets-rotation-strategy.md)

**Connect on-premise to cloud** → [Hybrid Cloud Deployment](./hybrid-cloud-deployment.md)

**Design secure networks** → [Advanced Networking](./advanced-networking.md)

**Build custom extensions** → [Custom Extensions](./custom-extensions.md)

**Migrate legacy systems** → [Legacy System Migration](./legacy-system-migration.md)

## Guide Structure

Each guide follows this pattern:

1. **Overview** - What you'll accomplish
2. **Prerequisites** - What you need before starting
3. **Architecture** - Visual diagram of the solution
4. **Step-by-Step** - Detailed instructions with examples
5. **Configuration** - Full Nickel configuration examples
6. **Verification** - How to validate the deployment
7. **Troubleshooting** - Common issues and solutions
8. **Next Steps** - How to extend or customize
9. **Best Practices** - Lessons learned and recommendations

## Learning Paths

### Path 1: I'm new to Provisioning (Day 1)
1. [From Scratch Guide](./from-scratch.md) - Basic setup
2. [Workspace Management](./workspace-management.md) - Organization
3. [Multi-Cloud Deployment](./multi-cloud-deployment.md) - Multi-cloud

### Path 2: I need production-ready setup (Week 1)
1. [Workspace Management](./workspace-management.md) - Organization
2. [GitOps Infrastructure Deployment](./gitops-infrastructure-deployment.md) - Automation
3. [Disaster Recovery Guide](./disaster-recovery.md) - Resilience
4. [Secrets Rotation Strategy](./secrets-rotation-strategy.md) - Security
5. [Advanced Networking](./advanced-networking.md) - Enterprise networking

### Path 3: I'm migrating from legacy (Month-long project)
1. [Legacy System Migration](./legacy-system-migration.md) - Migration plan
2. [Advanced Workflow Orchestration](./advanced-workflow-orchestration.md) - Complex deployments
3. [Hybrid Cloud Deployment](./hybrid-cloud-deployment.md) - Coexistence
4. [GitOps Infrastructure Deployment](./gitops-infrastructure-deployment.md) - Continuous deployment
5. [Disaster Recovery Guide](./disaster-recovery.md) - Failover strategies

### Path 4: I'm building a platform (Team project)
1. [Custom Extensions](./custom-extensions.md) - Build extensions
2. [Workspace Management](./workspace-management.md) - Multi-tenant setup
3. [Advanced Workflow Orchestration](./advanced-workflow-orchestration.md) - Complex workflows
4. [GitOps Infrastructure Deployment](./gitops-infrastructure-deployment.md) - CD/GitOps
5. [Secrets Rotation Strategy](./secrets-rotation-strategy.md) - Security at scale

## Related Documentation

- **Getting Started** → See `provisioning/docs/src/getting-started/`
- **Examples** → See `provisioning/docs/src/examples/`
- **Features** → See `provisioning/docs/src/features/`
- **Operations** → See `provisioning/docs/src/operations/`
- **Development** → See `provisioning/docs/src/development/`
