# Examples and Tutorials

This directory contains comprehensive examples and step-by-step tutorials for using Infrastructure Automation. Each example includes complete configurations, scripts, and explanations.

## Available Examples

### [Quick Start Examples](quick-start/)

Perfect for beginners getting familiar with the system:

- **Local Development Setup** - Simple local infrastructure for learning
- **Single Server Deployment** - Deploy a basic web server
- **Basic Task Service Installation** - Install Docker and simple services

### [Web Application Examples](web-application/)

Complete web application infrastructure patterns:

- **LAMP Stack** - Linux, Apache, MySQL, PHP application
- **MEAN Stack** - MongoDB, Express.js, Angular, Node.js
- **Three-Tier Application** - Load balancer, application servers, database
- **Static Website** - CDN-backed static site deployment

### [Microservices Examples](microservices/)

Modern microservices architecture patterns:

- **Kubernetes Microservices** - Container orchestration with Kubernetes
- **Service Mesh** - Istio/Linkerd service mesh deployment
- **API Gateway** - Centralized API management
- **Event-Driven Architecture** - Message queues and event streaming

### [Multi-Cloud Examples](multi-cloud/)

Multi-provider and hybrid cloud scenarios:

- **AWS + UpCloud Hybrid** - Hybrid cloud deployment
- **Multi-Region Setup** - Geographic distribution
- **Cloud Migration** - Migrating between providers
- **Disaster Recovery** - Cross-cloud backup and recovery

### [CI/CD Examples](ci-cd/)

Continuous integration and deployment patterns:

- **GitOps Workflow** - Git-based deployment pipeline
- **Blue-Green Deployment** - Zero-downtime deployments
- **Canary Releases** - Gradual feature rollouts
- **Infrastructure as Code Pipeline** - Automated infrastructure testing

### [Monitoring Examples](monitoring/)

Observability and monitoring setups:

- **Basic Monitoring** - Prometheus, Grafana, AlertManager
- **Log Aggregation** - ELK/EFK stack for log management
- **Distributed Tracing** - Jaeger/Zipkin for microservices
- **SRE Dashboard** - SRE-focused monitoring and alerting

## How to Use These Examples

### 1. Choose Your Example

Browse the directories and find an example that matches your use case. Each example includes:

- `README.md` - Overview and requirements
- `settings.ncl` - Infrastructure configuration
- `config.toml` - Environment configuration
- `deploy.sh` - Deployment script
- `cleanup.sh` - Cleanup script
- `verify.sh` - Verification script

### 2. Set Up Your Environment

```bash
# Navigate to example directory
cd docs/user/examples/web-application/lamp-stack

# Review the README
cat README.md

# Check requirements
./check-requirements.sh
```plaintext

### 3. Customize Configuration

```bash
# Copy and modify settings
cp settings.ncl my-settings.ncl
nano my-settings.ncl

# Update configuration for your environment
cp config.toml my-config.toml
nano my-config.toml
```plaintext

### 4. Deploy

```bash
# Validate configuration
provisioning validate config --settings my-settings.ncl

# Deploy with check mode first
./deploy.sh --check

# Deploy for real
./deploy.sh
```plaintext

### 5. Verify and Test

```bash
# Run verification tests
./verify.sh

# Manual testing
provisioning show servers --infra my-example
```plaintext

### 6. Clean Up

```bash
# When done, clean up resources
./cleanup.sh
```plaintext

## Example Categories

### Learning Path

**Beginner → Intermediate → Advanced**

1. **Start Here**: [Quick Start - Local Development](quick-start/local-development/)
2. **Basic Infrastructure**: [Web Application - LAMP Stack](web-application/lamp-stack/)
3. **Container Orchestration**: [Microservices - Kubernetes](microservices/kubernetes/)
4. **Production Ready**: [CI/CD - GitOps Workflow](ci-cd/gitops/)
5. **Multi-Cloud**: [Multi-Cloud - AWS + UpCloud](multi-cloud/aws-upcloud/)

### By Use Case

**Web Applications**

- Simple websites and blogs
- E-commerce platforms
- Content management systems
- API backends

**Microservices**

- Container-native applications
- Service-oriented architectures
- API-first applications
- Event-driven systems

**Data & Analytics**

- Data pipelines
- Analytics platforms
- Machine learning infrastructure
- Data warehouses

**DevOps & Platform**

- CI/CD pipelines
- Platform engineering
- Developer tooling
- Infrastructure automation

## Requirements

### System Requirements

Most examples require:

- Linux or macOS development environment
- At least 4 GB RAM available
- 10 GB free disk space
- Internet connectivity

### Software Prerequisites

- **Provisioning** installed and configured
- **Nushell 0.107.1+**
- **KCL 0.11.2+**
- **Git** for version control
- **Text editor** of your choice

### Cloud Provider Access

Examples may require:

- **AWS Account** with appropriate permissions
- **UpCloud Account** with API access
- **Local Development** environment (Docker, VMs)

### Verification

Before starting any example:

```bash
# Verify installation
provisioning --version

# Check environment
provisioning env

# Validate configuration
provisioning validate config

# Test provider connectivity
provisioning provider test local
```plaintext

## Contributing Examples

### Creating New Examples

Want to contribute an example? Follow this structure:

```plaintext
example-name/
├── README.md              # Overview and instructions
├── settings.ncl            # Infrastructure configuration
├── config.toml           # Environment settings
├── deploy.sh             # Deployment script
├── verify.sh             # Verification script
├── cleanup.sh            # Cleanup script
├── check-requirements.sh # Prerequisite checker
└── docs/                 # Additional documentation
    ├── architecture.md   # Architecture explanation
    └── troubleshooting.md # Common issues
```plaintext

### Example Template

Use this template for new examples:

**README.md**

```markdown
# Example Name

Brief description of what this example demonstrates.

## What You'll Learn
- Concept 1
- Concept 2
- Concept 3

## Prerequisites
- Requirement 1
- Requirement 2

## Architecture
[Architecture diagram or description]

## Deployment
[Step-by-step instructions]

## Verification
[How to test the deployment]

## Cleanup
[How to remove resources]

## Troubleshooting
[Common issues and solutions]
```plaintext

### Submission Process

1. Create your example following the template
2. Test thoroughly on clean environment
3. Document all prerequisites and steps
4. Submit pull request with clear description

## Support and Feedback

### Getting Help

If you encounter issues with any example:

1. **Check the troubleshooting section** in the example's README
2. **Verify prerequisites** are met
3. **Use debug mode** for detailed output:

   ```bash
   provisioning --debug <command>
   ```

1. **Consult the main troubleshooting guide**: [troubleshooting-guide.md](../troubleshooting-guide.md)

### Reporting Issues

When reporting issues with examples:

1. **Specify the example** name and version
2. **Include your environment** details:

   ```bash
   provisioning env > environment.txt
   ```

3. **Provide error messages** and logs
4. **Include steps to reproduce** the issue

### Suggesting Improvements

We welcome suggestions for:

- New example scenarios
- Improvements to existing examples
- Additional use cases to cover
- Documentation enhancements

## License and Usage

All examples are provided under the same license as the main project. Feel free to:

- Use examples as starting points for your projects
- Modify and adapt to your needs
- Share and distribute
- Contribute improvements back to the community

---

**Next Steps:**

- Browse the [Quick Start examples](quick-start/) to get familiar with the system
- Try the [Web Application examples](web-application/) for real-world scenarios
- Explore [Advanced examples](microservices/) when you're ready for production use

Happy provisioning. 🚀
