Skip to content

QUICKSTART.md

Latest commit

 

History

History
225 lines (164 loc) · 6.06 KB

QUICKSTART.md

File metadata and controls

225 lines (164 loc) · 6.06 KB

Qubinode Navigator - Quick Start Guide

Get from zero to running infrastructure in 15-25 minutes

Prerequisites

  • OS: RHEL 9, CentOS Stream 9, Rocky Linux 9, or Fedora 39+
  • RAM: 8GB minimum (16GB+ recommended)
  • Disk: 50GB+ free space
  • CPU: Virtualization enabled (VT-x/AMD-V)
  • Software: Git, Podman (or Docker)
  • Network: Internet access for container images

Step 1: Clone the Repository (2 min)

# Install git if not present
sudo dnf install -y git

# Clone the repository
git clone https://github.com/Qubinode/qubinode_navigator.git
cd qubinode_navigator

Step 2: Run Pre-flight Checks (2 min)

This validates your system and auto-fixes common issues:

./scripts/preflight-check.sh --fix

What it checks:

  • CPU virtualization support
  • Container runtime (podman)
  • Network connectivity
  • Disk space and memory
  • Required external repositories

If all checks pass, you'll see:

Pre-flight checks passed!
You can proceed with deployment:
  ./deploy-qubinode-with-airflow.sh

Step 3: Deploy Everything (10-15 min)

./deploy-qubinode-with-airflow.sh

This script deploys:

  • Apache Airflow (workflow orchestration)
  • PostgreSQL (Airflow metadata database)
  • AI Assistant (optional)
  • Nginx reverse proxy
  • SSH configuration for container→host access

Step 4: Access the Services

After deployment completes, you'll see:

Service URL Credentials
Airflow UI http://YOUR_IP/ admin / admin
AI Assistant http://YOUR_IP/ai/ (no auth)
Health Check http://YOUR_IP/health (no auth)

Note: The full stack deployment includes Nginx reverse proxy, so services are accessed on port 80. For development deployments (scripts/development/deploy-qubinode.sh), use direct ports: Airflow at :8888, AI Assistant at :8080.

Step 5: Enable and Run DAGs

  1. Open Airflow UI in your browser
  2. You'll see several pre-built DAGs:
DAG Purpose
example_kcli_vm_provisioning Create/manage VMs with kcli
infrastructure_health_check Monitor infrastructure components
freeipa_deployment Deploy FreeIPA identity management
stepca_deployment Deploy Step-CA certificate authority
certificate_provisioning Request/renew TLS certificates
dns_management Manage DNS records in FreeIPA
  1. Enable a DAG: Click the toggle switch to enable it
  2. Run a DAG: Click the "play" button → "Trigger DAG"
  3. Monitor: Watch progress in Graph or Grid view

Recommended First DAGs

1. Test Infrastructure Health

DAG: infrastructure_health_check
Purpose: Verify all components are working
Action: Trigger manually

2. Create Your First VM

DAG: example_kcli_vm_provisioning
Purpose: Create a CentOS Stream 10 VM
Action: Trigger with default parameters

3. Deploy FreeIPA (Identity Management)

DAG: freeipa_deployment
Purpose: Deploy FreeIPA for DNS + identity
Action: Configure parameters, then trigger

Command Reference

# Check deployment status
./airflow/deploy-airflow.sh status

# View container logs
cd airflow && podman-compose logs -f

# Restart services
cd airflow && podman-compose restart

# Stop everything
cd airflow && podman-compose down

# Start everything
cd airflow && podman-compose up -d

Directory Structure

qubinode_navigator/
├── airflow/
│   ├── dags/                    # Workflow definitions (DAGs)
│   ├── plugins/qubinode/        # Custom operators for kcli, virsh
│   ├── docker-compose.yml       # Container configuration
│   └── deploy-airflow.sh        # Deployment script
├── scripts/
│   ├── preflight-check.sh       # Pre-deployment validation
│   ├── qubinode-cert            # Certificate management CLI
│   └── qubinode-dns             # DNS management CLI
├── ansible/
│   └── roles/                   # Ansible roles for deployments
└── docs/
    └── adrs/                    # Architecture Decision Records

Troubleshooting

Airflow UI not accessible

# Check if containers are running
cd airflow && podman-compose ps

# Check logs
podman-compose logs airflow-webserver

DAG not appearing

# Check scheduler logs
cd airflow && podman-compose logs airflow-scheduler

# Force DAG rescan
podman-compose restart airflow-scheduler

VM operations failing

# Verify kcli is working on the host
kcli list vm

# Check if libvirtd is running
systemctl status libvirtd

Pre-flight check failures

# Run with verbose output
./scripts/preflight-check.sh --fix 2>&1 | tee preflight.log

# Common fixes:
# - Enable virtualization in BIOS
# - Start libvirtd: systemctl start libvirtd
# - Install podman: dnf install -y podman podman-compose

Next Steps

  1. Deploy FreeIPA - Identity management with DNS
  2. Deploy Step-CA - Internal certificate authority
  3. Deploy VyOS - Network segmentation (requires console access)
  4. Create custom DAGs - Automate your infrastructure

Getting Help

Related Documentation

Estimated total time: 15-25 minutes from clone to running Airflow UI