Common Setup Steps#

This page contains setup steps shared by both the Getting Started with Turing Pi and Getting Started without Turing Pi tutorials. You do not need to read this page on its own — it is included automatically in the tutorial you are following.

Prerequisites#

Software (on your workstation)#

  • Linux workstation (or WSL2 on Windows)

  • podman 4.3 or later (rootless container runtime)

  • VS Code with the Dev Containers extension

  • git

Note

Set the VS Code setting dev.containers.dockerPath to podman before proceeding.

Fork and clone the repository#

  1. Fork the repository on GitHub: visit gilesknap/tpi-k3s-ansible and click Fork.

  2. Clone your fork:

git clone https://github.com/<your-username>/tpi-k3s-ansible.git
cd tpi-k3s-ansible

Note

You need your own fork because ArgoCD tracks your repository for GitOps. Changes you push to your fork are automatically deployed to your cluster.

The repo contains SealedSecret files encrypted for the original cluster — these won’t work on yours and can be safely ignored until you create your own during Set Up DNS, TLS & Cloudflare Tunnel setup.

Generate an SSH keypair#

Create a dedicated keypair for Ansible to use when connecting to all nodes:

# Run this on your HOST machine (outside the devcontainer)
ssh-keygen -t rsa -b 4096 -C "ansible master key" -f $HOME/.ssh/ansible_rsa

Use a strong passphrase. Then copy the public key into the repo:

cp $HOME/.ssh/ansible_rsa.pub pub_keys/ansible_rsa.pub

Open the devcontainer#

Open the repository in VS Code:

code .

When prompted, select “Reopen in Container” (or use Ctrl+Shift+P → Dev Containers: Reopen in Container).

The devcontainer provides Ansible (and its Python dependencies) out of the box. Cluster tools (kubectl, helm, kubeseal) are installed later by the tools role when you run the playbook. No additional installation is needed on your workstation.

Configure the cluster#

Edit group_vars/all.yml — the primary Ansible configuration:

# Change these to match your environment
control_plane: node01              # Which node is the K3s control plane
cluster_domain: example.com        # Your domain name
domain_email: you@example.com      # For Let's Encrypt certificates
repo_remote: https://github.com/<your-username>/tpi-k3s-ansible.git
repo_branch: main                  # Git branch for ArgoCD to track

Then edit kubernetes-services/values.yaml — the ArgoCD runtime configuration:

repo_branch: main                  # Must match the value in all.yml

# OAuth2 authentication gateway — leave false for initial setup.
# Enable after completing the OAuth guide (docs/how-to/oauth-setup).
enable_oauth2_proxy: false

# OAuth2 email allowlist — GitHub-linked emails allowed to access
# protected services. Remove the defaults and add your own:
oauth2_emails:
  - you@example.com

# NFS configuration (optional — only needed for LLM features)
rkllama:
  nfs:
    server: 192.168.1.3            # Your NFS server IP
    path: /path/to/rkllm/models    # NFS export path for rkllm models
llamacpp:
  nfs:
    server: 192.168.1.3
    path: /path/to/gguf/models
  model:
    file: "your-model.gguf"

Tip

If you do not have an NFS server or do not plan to use the LLM features (rkllama, llamacpp), you can leave the NFS settings as-is. The services will deploy but remain idle until configured.

Note

enable_oauth2_proxy controls whether cluster services require GitHub login. Leave it false until you have completed the Set Up OAuth Authentication guide — otherwise services like Grafana and Longhorn will return errors because the OAuth proxy is not yet deployed.

Verify the cluster#

After the playbook completes:

kubectl get nodes

Expected output shows all nodes in Ready state:

NAME     STATUS   ROLES                       AGE   VERSION
node01   Ready    control-plane,etcd,master   5m    v1.31.x+k3s1
node02   Ready    <none>                      4m    v1.31.x+k3s1
node03   Ready    <none>                      4m    v1.31.x+k3s1
node04   Ready    <none>                      4m    v1.31.x+k3s1

Check ArgoCD applications:

kubectl get applications -n argo-cd

All applications should eventually reach Synced and Healthy status.

Next Steps#