setup.html

---
layout: default
title: Setup & prerequisites
description: Everything you need to run the data-mesh reference — hardware, OS tuning, tooling, bootstrap, and verification.
permalink: /setup/
---

<section class="hero hero--compact">
    <div class="container">
        <span class="hero__eyebrow">Setup &amp; prerequisites</span>
        <h1>Running the reference, start to finish.</h1>
        <p class="hero__lead">
            From a bare Fedora workstation to a fully running data mesh —
            kernel tuning, tooling, and a single bootstrap command that
            brings up the entire stack: Istio, Kafka, Postgres,
            OpenMetadata, observability, and every domain service.
        </p>
    </div>
</section>

<!-- ───────── Hardware & OS ───────── -->

<section class="section">
    <div class="container" style="max-width: 42rem;">
        <h2 class="section-heading">Verified configuration</h2>

        <table>
            <thead>
                <tr>
                    <th>Requirement</th>
                    <th>Minimum</th>
                    <th>Notes</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>OS</td>
                    <td>Fedora 44, Docker Engine (docker-ce, daemon running, user in docker group)</td>
                    <td>minikube node runs containerd with runc</td>
                </tr>
                <tr>
                    <td>RAM</td>
                    <td>64 GB total</td>
                    <td>24 GB allocated to minikube profile; rest is host headroom</td>
                </tr>
                <tr>
                    <td>Disk</td>
                    <td>1 TB</td>
                    <td>About 100 GB free under the Docker data root (<code>/var/lib/docker</code>)</td>
                </tr>
                <tr>
                    <td>CPU</td>
                    <td>16 vCPU recommended</td>
                    <td>Not strictly required but the stack is heavy</td>
                </tr>
            </tbody>
        </table>
    </div>
</section>

<!-- ───────── Kernel & container tuning ───────── -->

<section class="section-tight">
    <div class="container" style="max-width: 42rem;">
        <h2 class="section-heading">Kernel tuning</h2>

        <h3>inotify limits</h3>
        <p>
            The capstone runs many controllers; Fedora's default 128
            instances is not enough.
        </p>
<pre><code>sudo sh -c 'printf "fs.inotify.max_user_instances = 512\nfs.inotify.max_user_watches = 524288\n" \
    &gt; /etc/sysctl.d/99-kubernetes.conf'
sudo sysctl -p /etc/sysctl.d/99-kubernetes.conf</code></pre>
    </div>
</section>

<!-- ───────── Container engine ───────── -->

<section class="section">
    <div class="container" style="max-width: 42rem;">
        <h2 class="section-heading">Container engine</h2>
        <p>
            The capstone runs on Docker Engine: native docker-ce on Linux,
            with the daemon running and your user in the
            <code>docker</code> group. Install it from
            <a href="https://docs.docker.com/engine/install/" rel="noopener">docs.docker.com/engine/install</a>,
            then enable it and point the CLI at it:
        </p>
<pre><code>sudo systemctl enable --now docker      # or: sudo systemctl start docker
sudo usermod -aG docker "$USER"         # log out and back in afterwards
docker context use default
docker info</code></pre>
        <p>
            Membership in the <code>docker</code> group is root-equivalent on the host.
        </p>

        <h3>VM-based engines</h3>
        <p>
            The capstone scripts are supported on Fedora and RHEL hosts (bare metal
            or VM). A VM-based engine such as Docker Desktop can provide the engine instead. It
            is an option, not a requirement. Its VM must be sized to at least 28 GB of memory;
            set <code>MINIKUBE_CPUS</code> and <code>MINIKUBE_MEMORY</code> to
            fit it, as described below.
        </p>

        <h3>Upgrading from an earlier (rootless podman) capstone profile</h3> <!-- forbidden-ok -->
        <p> <!-- forbidden-ok -->
            An earlier release created the profile with rootless podman. Delete that profile first, <!-- forbidden-ok -->
            then clear the setting, then run setup: <!-- forbidden-ok -->
        </p>
<pre><code>MINIKUBE_ROOTLESS=true minikube delete -p capstone <!-- forbidden-ok -->
minikube config unset rootless <!-- forbidden-ok -->
./scripts/setup-capstone-profile.sh</code></pre>

        <h3>Fitting minikube to the engine</h3>
        <p>
            The profile defaults to 16 CPUs, 24 GB of memory, and an 80 GB
            disk. Override them before creating the profile:
        </p>
<pre><code>export MINIKUBE_CPUS=16
export MINIKUBE_MEMORY=24g
export MINIKUBE_DISK=80g</code></pre>
        <p>
            The docker driver on Linux ignores the disk size; data lives under
            the engine's data root (<code>docker info</code> shows it), where
            about 100 GB free is recommended.
        </p>
    </div>
</section>

<!-- ───────── Required tooling ───────── -->

<section class="section">
    <div class="container" style="max-width: 42rem;">
        <h2 class="section-heading">Required tooling</h2>

        <ul>
            <li><strong>docker</strong> and <strong>docker compose</strong> (compose is not used by the minikube path; listed as a standard host tool)</li>
            <li><strong>minikube</strong> &gt;= 1.39.0 &mdash; the profile pins Kubernetes v1.36.5</li>
            <li><strong>kubectl</strong> 1.36.x</li>
            <li><strong>helm</strong></li>
            <li>
                <strong>istioctl</strong> 1.31.1 &mdash; with the full Istio
                distribution (not just the binary;
                <code>setup-kiali.sh</code> applies
                <code>samples/addons/kiali.yaml</code> from it)
            </li>
        </ul>
        <p>
            Optional, for the Red Hat (OpenShift Local) appendix only:
            <strong>crc</strong>, <strong>podman</strong>, and <strong>podman compose</strong>. <!-- forbidden-ok -->
        </p>

        <h3>Installing the Istio distribution</h3>
<pre><code>curl -fsSL https://github.com/istio/istio/releases/download/1.31.1/istio-1.31.1-linux-amd64.tar.gz \
    | tar xz -C ~/.local/share
ln -sfn ~/.local/share/istio-1.31.1 ~/.local/share/istio-current
cp ~/.local/share/istio-current/bin/istioctl ~/.local/bin/</code></pre>
    </div>
</section>

<!-- ───────── Bootstrap ───────── -->

<section class="section-tight">
    <div class="container" style="max-width: 42rem;">
        <h2 class="section-heading">Bootstrap</h2>

        <h3>Bring the whole system up</h3>
<pre><code>cd examples/lgtm-datamesh
./scripts/bootstrap-capstone.sh</code></pre>
        <p>
            Images are built with Docker Engine and loaded into the node with
            <code>minikube image load</code>; there is no registry. Bootstrap runs 10 tiers: minikube profile, Istio,
            CloudNativePG operator, Postgres cluster, Kafka (Strimzi),
            KEDA + HTTP add-on, OpenMetadata + observability, all services +
            scalers + seed data, Kiali, and catalog ingestion + lineage.
        </p>

        <h3>Restore baseline after running demos</h3>
<pre><code>./scripts/restore-baseline.sh</code></pre>
        <p>
            The demo scripts clean up their own releases on success. After
            running several, shared services may be missing.
            <code>restore-baseline.sh</code> puts the workloads back in
            their bootstrap state.
        </p>
    </div>
</section>

<!-- ───────── Verifying the stack ───────── -->

<section class="section">
    <div class="container" style="max-width: 42rem;">
        <h2 class="section-heading">Verifying the stack</h2>

        <h3>Cluster status</h3>
<pre><code>./scripts/cluster-status.sh</code></pre>

        <h3>Quick verification demos</h3>
        <ol>
            <li>
                <code>./demos/demo-order.sh</code> &mdash; creates an order
                via REST, confirms it in Postgres
            </li>
            <li>
                <code>./demos/demo-service.sh inventory</code> &mdash;
                builds, deploys, and health-checks a service
            </li>
            <li>
                <code>./demos/demo-observability.sh</code> &mdash; verifies
                Prometheus is scraping and Grafana is provisioned
            </li>
        </ol>
    </div>
</section>

<!-- ───────── Observability URLs ───────── -->

<section class="section-tight">
    <div class="container" style="max-width: 42rem;">
        <h2 class="section-heading">Accessing the tools</h2>
        <p>
            The tools run inside the cluster and are exposed as NodePort
            services published on <code>127.0.0.1</code> when the
            <code>capstone</code> minikube profile is created. Nothing runs in
            the background and nothing needs starting per demo. Ports are
            fixed at creation; an older profile without them is refused by
            <code>setup-capstone-profile.sh</code> and recreated with
            <code>./scripts/setup-capstone-profile.sh --replace</code>.
            <code>--replace</code> deletes and recreates the cluster, so run
            <code>./scripts/bootstrap-capstone.sh</code> again afterwards.
            Run the workshop in isolation: shut down CRC, other minikube
            profiles, and other workloads first so the host ports are free.
            To see which endpoints are published and reachable:
        </p>
        <pre><code>./scripts/show-endpoints.sh</code></pre>
        <p>
            (Prometheus uses host port 9091 because Fedora ships Cockpit on 9090.)
        </p>

        <table>
            <thead>
                <tr>
                    <th>Tool</th>
                    <th>Local URL</th>
                </tr>
            </thead>
            <tbody>
                <tr><td>Grafana</td><td><code>http://127.0.0.1:3000</code></td></tr>
                <tr><td>Prometheus</td><td><code>http://127.0.0.1:9091</code></td></tr>
                <tr><td>Kiali</td><td><code>http://127.0.0.1:20001/kiali</code></td></tr>
                <tr><td>Tempo (via Grafana)</td><td>&mdash; (Grafana &rarr; Explore &rarr; Tempo datasource)</td></tr>
                <tr><td>OpenMetadata</td><td><code>http://127.0.0.1:8585</code></td></tr>
                <tr><td>Apicurio</td><td><code>http://127.0.0.1:8084</code></td></tr>
                <tr><td>Kafka UI</td><td><code>http://127.0.0.1:8089</code></td></tr>
            </tbody>
        </table>

        <p>
            Grafana default credentials are <code>admin</code> / the value
            from
            <code>kubectl get secret grafana -n capstone -o jsonpath='{.data.admin-password}' | base64 -d</code>.
        </p>
    </div>
</section>