Getting Started with Balloon Popper Game¶

Learning Objectives¶

By the end of this chapter, you will:

Install all required tools and dependencies
Clone and configure the project repository
Set up a Python virtual environment with necessary packages
Understand the project structure
Configure DNS settings for streamlined development (optional)

Prerequisites¶

Before beginning this tutorial, ensure you have the following tools installed and properly configured:

Tool	Purpose	Minimum Version	Remarks
GitHub Account	Repository access	N/A
Docker Desktop	Container runtime	Latest
kubectl	Kubernetes CLI	Latest	`$PROJECT_HOME/setup.sh` will download latest matching the cluster version
rpk	Kafka CLI	Latest	`$PROJECT_HOME/setup.sh` will download latest matching the cluster Kafka version
k3d	Lightweight Kubernetes	>= 5.0.0
Python	Programming language	>= 3.12
psql	PostgreSQL CLI Client	>= 17.4	PostgreSQL client to work with Risingwave using SQL
uv	Python package manager	Latest
Task	Task runner	Latest
LocalStack	AWS emulator	>= 3.0.0
Dnsmasq	DNS management	Latest (Optional)

Prerequisites Check

Make sure all required tools are properly installed and available in your system PATH before proceeding. This will prevent issues later in the setup process.

Setting Up the Project¶

Step 1: Clone the Repository¶

git clone https://github.com/kameshsampath/balloon-popper-demo
cd balloon-popper-demo

Step 2: Configure Environment Variables¶

Set up essential environment variables for the project:

export PROJECT_HOME="$PWD"
export KUBECONFIG="$PWD/.kube/config"
export K3D_CLUSTER_NAME=balloon-popper-demo
export K3S_VERSION=v1.32.1-k3s1
export FEATURES_DIR="$PWD/k8s"

Environment Management

Consider using direnv to automatically set environment variables when entering the project directory. This simplifies your workflow and ensures consistent configuration.

Step 3: Set Up Python Environment¶

Create and activate a Python virtual environment:

# Pin Python version
uv python pin 3.12

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # On Unix/Linux/macOS
# OR
.venv\Scripts\activate     # On Windows

# Install dependencies
uv sync

Note

The virtual environment isolates your project dependencies from system-wide Python packages, preventing conflicts and ensuring reproducibility.

Step 4: DNS Configuration¶

For seamless access to services within your local Kubernetes cluster.

On macOS with Homebrew:

# Configure Dnsmasq to resolve .localstack domains to localhost
echo "address=/.localstack/127.0.0.1" >> $(brew --prefix)/etc/dnsmasq.conf

# Configure macOS to use Dnsmasq for .localstack domains
sudo mkdir -p /etc/resolver
cat <<EOF | sudo tee /etc/resolver/localstack
nameserver 127.0.0.1
EOF

Info

After configuring Dnsmasq, you may need to restart the service and flush your DNS cache for changes to take effect.

(OR)

Edit /etc/hosts and add the following entry

127.0.0.1 *.localstack

Project Structure Overview¶

The repository is organized into several key directories:

bin/: Contains setup and cleanup scripts
config/: Kubernetes cluster configuration
k8s/: Kubernetes manifests for all components
features/: Core infrastructure components (Kafka, LocalStack, etc.)
generator/: Event generator deployment
polaris/: Apache Polaris configuration
notebooks/: Jupyter notebooks for analysis
packages/: Python packages for the application components
common/: Shared utilities
dashboard/: Streamlit dashboard
generator/: Event generation logic
polaris-forge-setup/: Ansible playbooks for infrastructure setup
scripts/: Generated SQL scripts (will be created in later steps)
work/: Working directory for credentials and temporary files

Generated Files

Several configuration files containing sensitive information are not included in the repository and will be generated during the setup process:

k8s/features/postgresql.yaml
k8s/features/risingwave.yaml
k8s/polaris/persistence.xml
k8s/polaris/.bootstrap-credentials
k8s/polaris/.polaris.env
RSA key pairs
SQL scripts

Next Steps¶

Now that you have set up the project environment, you're ready to create your local Kubernetes cluster and deploy the necessary components. In the next chapter, we'll set up the local cloud infrastructure using K3d and deploy essential services like Kafka, LocalStack, and Apache Polaris.

Checkpoint

Before proceeding to the next chapter, ensure that:

All required tools are installed
The repository is cloned and environment variables are set
The Python virtual environment is activated
You understand the basic project structure