> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Base Kit

> The single-environment homelab blueprint — local or cloud, any node count

The **Base Kit** is designed for **single-environment deployments** — all services share one deployment target.

It can run on a single server or span multiple nodes in the same environment (local or cloud). This is the simplest architecture pattern, optimized for reliability and straightforward operations.

<Note>
  The Base Kit follows an IaC-first approach using packaged OpenTofu plus a selected PaaS adapter. Coolify is the default beta path, and Komodo is the supported beta alternative.
</Note>

## Overview

```mermaid theme={null}
graph TB
    subgraph Env["Single Environment (local or cloud)"]
        subgraph Core["Core Services"]
            Traefik["Traefik v3<br/>Reverse Proxy"]
        end
        
        subgraph Platform["PaaS Platform"]
            Coolify["Coolify<br/>App Platform"]
        end
        
        subgraph Monitoring["Observability"]
            UptimeKuma["Uptime Kuma<br/>Status Monitoring"]
            Dozzle["Dozzle<br/>Log Viewer"]
        end
        
        subgraph Identity["Identity"]
            TinyAuth["TinyAuth"]
            PocketID["PocketID"]
        end
    end
    
    Internet["Internet"] --> Traefik
    Traefik --> Platform
    Traefik --> Monitoring
    Traefik --> Identity
    
    style Env fill:#1e293b,stroke:#38bdf8,color:#f8fafc
    style Core fill:#1e293b,stroke:#fbbf24,color:#f8fafc
    style Platform fill:#1e293b,stroke:#4ade80,color:#f8fafc
    style Monitoring fill:#1e293b,stroke:#a78bfa,color:#f8fafc
    style Identity fill:#1e293b,stroke:#ec4899,color:#f8fafc
```

## Common starting profiles

Base Kit no longer relies on the old monolithic `variant` selector. Start from the baseline and use context, mode, and add-ons to shape the deployment.

<Tabs>
  <Tab title="Baseline">
    The standard single-environment path.

    | Surface                  | Description                                |
    | ------------------------ | ------------------------------------------ |
    | **Traefik v3**           | Reverse proxy with auto-SSL                |
    | **Coolify**              | App platform (PaaS) - beta default         |
    | **Komodo**               | Beta-supported alternative PaaS            |
    | **Uptime Kuma / Beszel** | Lightweight uptime or node-health UX       |
    | **Dozzle**               | Real-time Docker log viewer                |
    | **monitoring-agent**     | OTLP collector baseline enabled by default |

    ```yaml stack-spec.yaml theme={null}
    stackkit: base-kit
    ```
  </Tab>

  <Tab title="With monitoring-core">
    Add centralized fan-in and longer retention when the deployment needs it.

    | Surface              | Description                                            |
    | -------------------- | ------------------------------------------------------ |
    | **monitoring-agent** | Default node-level OTLP collector                      |
    | **monitoring-core**  | Optional OTLP gateway and retention tier               |
    | **VictoriaMetrics**  | Optional durable metrics backend                       |
    | **Grafana**          | Optional dashboards when enabled with the backend tier |

    ```yaml stack-spec.yaml theme={null}
    stackkit: base-kit

    addons:
      - monitoring-core
    ```
  </Tab>

  <Tab title="Low-resource intent">
    Lightweight operator intent for constrained hardware.

    | Surface                          | Description                                |
    | -------------------------------- | ------------------------------------------ |
    | **mode: pi**                     | Forces the lightweight experience          |
    | **monitoring-agent**             | Keeps the collector baseline               |
    | **No retention tier by default** | Avoids heavier fan-in and storage services |

    ```yaml stack-spec.yaml theme={null}
    stackkit: base-kit
    mode: pi
    ```
  </Tab>
</Tabs>

## Included services

<Note>
  The app platform is **context-resolved**. The public BaseKit beta defaults to **Coolify** and supports **Komodo** as the beta alternative. Dokploy remains draft/non-beta and is not part of the canonical beta E2E matrix.
</Note>

<CardGroup cols={2}>
  <Card title="Traefik v3" icon="route">
    **Reverse Proxy & SSL**

    Automatic HTTPS certificates (Let's Encrypt), routing, and load balancing for all services.
  </Card>

  <Card title="Coolify" icon="cloud">
    **App platform (beta default)**

    Self-hosted PaaS like Vercel/Heroku. BaseKit bootstraps Coolify, enables its API, stores platform placement state, and deploys StackKit-owned apps through Coolify.
  </Card>

  <Card title="Komodo" icon="rocket">
    **Beta-supported alternative**

    Komodo is the supported beta alternative for kombify.me provider-lease evidence. Dokploy remains draft until promoted by its own release evidence.
  </Card>

  <Card title="Uptime Kuma" icon="heart-pulse">
    **Status Monitoring**

    Monitor your services with beautiful status pages and alerts.
  </Card>

  <Card title="Netdata" icon="gauge">
    **Server Metrics**

    Real-time per-node metrics (CPU, RAM, disk, network). Beszel or Glances on low-resource nodes.
  </Card>

  <Card title="Dozzle" icon="list">
    **Log Viewer**

    Real-time Docker container log viewer in your browser.
  </Card>
</CardGroup>

### Identity services

<CardGroup cols={2}>
  <Card title="TinyAuth" icon="key">
    **Lightweight auth proxy**

    Gateway auth boundary for protected routes.
  </Card>

  <Card title="PocketID" icon="id-card">
    **Passkey-first OIDC provider**

    Owner activation and passkey login for the BaseKit beta path.
  </Card>
</CardGroup>

## Requirements

| Resource          | Low                     | Standard           | High                                          |
| ----------------- | ----------------------- | ------------------ | --------------------------------------------- |
| **CPU**           | 2 cores                 | 4 cores            | 8 cores                                       |
| **RAM**           | 4 GB                    | 8 GB               | 16 GB                                         |
| **Storage**       | 20 GB SSD               | 50 GB SSD          | 100+ GB SSD                                   |
| **Observability** | Collector baseline only | Collector baseline | Collector baseline + optional monitoring-core |

### Supported operating systems

| OS     | Version       | Status        |
| ------ | ------------- | ------------- |
| Ubuntu | 24.04 LTS     | ✅ Recommended |
| Ubuntu | 22.04 LTS     | ✅ Supported   |
| Debian | 12 (Bookworm) | ✅ Supported   |

## Quick start

<Steps>
  <Step title="Create your spec file">
    ```yaml stack-spec.yaml theme={null}
    stackkit: base-kit

    # Node configuration
    nodes:
      - name: main-server
        type: local  # or vps, cloud
        connection:
          host: 192.168.1.100
          user: root
          ssh_key: ~/.ssh/id_ed25519

    # Domain (optional - enables auto-SSL)
    domain: homelab.example.com
    email: you@example.com

    # Service toggles
    services:
      coolify:
        enabled: true
      uptime_kuma:
        enabled: true
      dozzle:
        enabled: true
    ```
  </Step>

  <Step title="Validate configuration">
    ```bash theme={null}
    stackkit validate
    ```

    Output:

    ```text theme={null}
    ✓ StackKit: base-kit (v1.0.0)
    ✓ Monitoring: OTLP collector baseline
    ✓ OS: ubuntu-24
    ✓ Compute tier: standard
    ✓ All service dependencies satisfied
    ✓ No port conflicts detected

    Ready to deploy!
    ```
  </Step>

  <Step title="Generate infrastructure code">
    ```bash theme={null}
    stackkit generate
    ```

    Creates:

    * `deploy/` - generated OpenTofu input and output files
    * `.stackkit/platform.json` - selected PaaS placement and API context after apply
    * `.stackkit/state.yaml` - setup-run state and retry-safe setup action evidence
    * service output files with Base Hub, identity, monitoring, and application URLs
  </Step>

  <Step title="Preview and apply">
    ```bash theme={null}
    stackkit plan   # Preview changes
    stackkit apply  # Deploy
    ```
  </Step>
</Steps>

## Configuration reference

### Node settings

```yaml theme={null}
nodes:
  - name: main-server
    type: local              # local, vps, cloud
    os: ubuntu-24            # ubuntu-24, ubuntu-22, debian-12
    
    connection:
      host: 192.168.1.100
      port: 22
      user: root
      ssh_key: ~/.ssh/id_ed25519
      # OR password: ${SSH_PASSWORD}
    
    resources:               # Optional — auto-detected
      cpu: 4
      memory_gb: 8
      disk_gb: 50
```

### Domain and SSL

<Tabs>
  <Tab title="With domain">
    ```yaml theme={null}
    domain: homelab.example.com
    email: you@example.com

    ssl:
      provider: letsencrypt
      # Optional: wildcard for *.homelab.example.com
      wildcard: true
    ```
  </Tab>

  <Tab title="Local only">
    ```yaml theme={null}
    # No domain — access via IP:port
    # Coolify will be available at http://IP:8000

    ssl:
      provider: selfsigned
    ```
  </Tab>
</Tabs>

### Service configuration

```yaml theme={null}
services:
  traefik:
    enabled: true           # Always required
    dashboard: true         # Enable Traefik UI
    log_level: INFO
    
  coolify:
    enabled: true
    # Coolify runs on port 8000 by default
    
  uptime_kuma:
    enabled: true
    public_page: true       # Enable public status page
    
  dozzle:
    enabled: true
    remote_hosts: []        # Add remote Docker hosts
    
  # Identity is part of the beta baseline unless intentionally overridden
  tinyauth:
    enabled: true
    
  pocketid:
    enabled: true
```

## Deployment modes

The Base Kit supports these public install modes:

| Mode             | Engine                                                                   | When to use                               |
| ---------------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| **Bare**         | Packaged OpenTofu without Base Hub/setup automation                      | Manual or BYOS foundations                |
| **Bootstrapped** | Packaged OpenTofu plus Base Hub, identity, monitoring, and setup actions | Default public beta path                  |
| **Advanced**     | Bootstrapped plus advanced handoff/runtime metadata                      | TechStack/Komodo and guided handoff paths |

Terramate remains an explicit `terramate` / `advanced-terramate` opt-in until its stack templates have release-grade evidence.

```yaml theme={null}
# Default beta mode
mode: bootstrapped
```

## File structure

After `stackkit generate`:

```text theme={null}
.
├── stack-spec.yaml          # Your configuration
├── deploy/                  # Generated OpenTofu inputs and outputs
├── .stackkit/
│   ├── platform.json        # Selected PaaS context after apply
│   ├── state.yaml           # Setup-run state
│   └── security-baseline.json
└── artifacts/               # Optional local evidence and diagnostics
```

## Constraints

The Base Kit enforces these rules:

| Constraint       | Value                   | Reason                     |
| ---------------- | ----------------------- | -------------------------- |
| Environment      | Single (local or cloud) | Single-environment pattern |
| Traefik required | Yes                     | All services need routing  |
| Min RAM          | 4 GB                    | Services won't fit in less |

<Warning>
  The Base Kit serves a single-environment pattern. If you need:

  * **Hybrid local + cloud** — [Modern Homelab Kit](https://docs.kombify.io/stackkits/kits/modern-homelab)
  * **Automatic failover and redundancy** — [High Availability Kit](https://docs.kombify.io/stackkits/kits/ha-kit)
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Services not accessible">
    1. Check Traefik is running: `docker logs traefik`
    2. Verify DNS resolves to your server
    3. Check firewall allows ports 80/443
    4. For local: Use `http://IP:PORT` instead of domain
  </Accordion>

  <Accordion title="SSL certificate errors">
    * **Let's Encrypt**: Domain must be publicly accessible
    * **Self-signed**: Add browser exception or use `curl -k`
    * Check rate limits at [https://letsencrypt.org/docs/rate-limits/](https://letsencrypt.org/docs/rate-limits/)
  </Accordion>

  <Accordion title="Coolify not starting">
    1. Check port 8000 is not in use: `netstat -tlnp | grep 8000`
    2. Verify Docker socket permissions
    3. Check logs: `docker logs coolify`
  </Accordion>

  <Accordion title="Low disk space warnings">
    1. Prune unused images: `docker image prune -a`
    2. Check volume sizes: `docker system df`
    3. Consider adding external storage
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Node Hub" icon="grid-2" href="https://docs.kombify.io/guides/stackkits/node-hub">
    Open the standard `base.<domain>` dashboard and service guide matrix.
  </Card>

  <Card title="CUE basics" icon="code" href="https://docs.kombify.io/stackkits/explanations/cue-architecture">
    Learn how to customize StackKit schemas
  </Card>
</CardGroup>