Deploying a Preact App with K3s Locally: A Beginner's Guide

Welcome to this comprehensive guide on deploying a Preact app using K3s locally! If you're new to web development, containers, or Kubernetes, don't worry—we'll start from the very basics and build up step by step. By the end, you'll have a fully functional Preact application running in a local Kubernetes cluster. This hands-on tutorial assumes no prior knowledge, so we'll explain every concept along the way.

What You'll Learn

• The basics of Preact (a lightweight React alternative)
• Introduction to containers and Docker
• Kubernetes fundamentals and why K3s is great for local development
• How to containerize and deploy an app locally

Prerequisites

Before we start, you'll need:

• A computer with Linux, macOS, or Windows (with WSL2 for Windows users)
• Basic command-line knowledge (we'll guide you through it)
• About 10-15 minutes of your time

No coding experience required!

What is Preact?

Preact is a fast, lightweight JavaScript library for building user interfaces. It's like React but smaller and more efficient. Think of it as a toolkit to create interactive web apps with components, state, and events.

Here's a simple ASCII representation of a Preact component:

+-------------------+
|   Preact App      |
+-------------------+
|                   |
|  <App />          |
|    ├── <Header /> |
|    └── <Content />|
|                   |
+-------------------+

Why Preact?

• Small size: Only ~3KB gzipped (vs. React's ~40KB)
• Fast: Better performance for simple apps
• Compatible: Works with most React code and tools

What is K3s?

K3s is a lightweight version of Kubernetes, the most popular container orchestration platform. Kubernetes manages containers (like tiny virtual machines for your app) at scale.

Key Concepts

• Container: A package with your app's code, dependencies, and runtime (like a portable box)
• Pod: The smallest unit in Kubernetes; usually one container
• Service: Exposes your app to the network
• Deployment: Manages how many copies of your app run

Visualizing Kubernetes components:

[Deployment]
     |
     v
  [Pod]  <-- Contains -->
+------------+
| Container  |
| (Your App) |
+------------+
     ^
     |
 [Service] <-- Exposes to network -->

K3s is perfect for local development because it's easy to install and uses fewer resources than full Kubernetes.

Step 1: Setting Up Your Environment

Install Node.js and npm

Preact apps need Node.js. Download from nodejs.org and install it.

Verify with:

node --version
npm --version

Install Docker

Docker creates containers. Download from docker.com and install.

Verify:

docker --version

Step 2: Create a Preact App

Initialize the Project

Create a new directory and set up Preact:

mkdir preact-k3s-app
cd preact-k3s-app
npm create preact@latest . -- --yes

This creates a basic Preact app with:

• src/: Your code
• package.json: Project config
• Build scripts

Your project structure will look like this:

preact-k3s-app/
├── src/
│   ├── index.js
│   └── style.css
├── package.json
└── README.md

Add Some Content

Edit src/index.js to add a simple component:

import { render } from 'preact';
import './style.css';

function App() {
  return (
    <div>
      <h1>Hello from Preact on K3s!</h1>
      <p>This app is running in a containerized Kubernetes cluster.</p>
    </div>
  );
}

render(<App />, document.getElementById('app'));

Build the App

npm run build

This creates a dist/ folder with production-ready files.

After building, your structure becomes:

preact-k3s-app/
├── src/
│   ├── index.js
│   └── style.css
├── dist/
│   ├── index.html
│   ├── bundle.js
│   └── style.css
├── package.json
├── README.md
└── Dockerfile (you'll add this next)

Step 3: Containerize with Docker

What is Containerization?

Containerization packages your app with everything it needs to run, ensuring it works the same everywhere.

Think of a container as a shipping box:

+-----------------------------+
|        Container            |
+-----------------------------+
|                             |
|  [Your App Code]            |
|  [Dependencies]             |
|  [Runtime (nginx)]          |
|                             |
+-----------------------------+
    |
    v
Docker Engine (runs anywhere)

Create a Dockerfile

In your project root, create Dockerfile:

# Use a lightweight web server
FROM nginx:alpine

# Copy built files to nginx
COPY dist/ /usr/share/nginx/html/

# Expose port 80
EXPOSE 80

# Start nginx
CMD ["nginx", "-g", "daemon off;"]

This uses nginx (a web server) to serve your Preact app.

Build the Docker Image

docker build -t preact-app:latest .

Test Locally

Run the container:

docker run -p 8080:80 preact-app:latest

Visit http://localhost:8080 in your browser. You should see your app!

Stop with Ctrl+C.

Step 4: Install K3s

What is K3s Installation?

K3s installs a full Kubernetes cluster with one command.

Install K3s

curl -sfL https://get.k3s.io | sh -

This downloads and runs K3s as a service.

Verify Installation

Check if it's running:

kubectl get nodes

You should see one node named after your machine.

kubectl is the Kubernetes command-line tool (installed with K3s).

Step 5: Deploy to K3s

Create Kubernetes Manifests

Kubernetes uses YAML files to define deployments.

Create deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: preact-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: preact-app
  template:
    metadata:
      labels:
        app: preact-app
    spec:
      containers:
      - name: preact-app
        image: preact-app:latest
        ports:
        - containerPort: 80

---
apiVersion: v1
kind: Service
metadata:
  name: preact-app-service
spec:
  selector:
    app: preact-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: LoadBalancer

This creates:

• A deployment with 1 replica of your container
• A service to expose it

Load the Image into K3s

Since we're local, load the Docker image:

docker save preact-app:latest | sudo k3s ctr images import -

Deploy

kubectl apply -f deployment.yaml

Check status:

kubectl get pods
kubectl get services

Access Your App

For local LoadBalancer, use port forwarding:

kubectl port-forward service/preact-app-service 8080:80

Visit http://localhost:8080. Your Preact app is now running on Kubernetes!

Here's the overall architecture:

[Your Machine]
     |
     v
  [K3s Cluster]
     |
     +-------------------+
     |   Deployment      |
     |   (Manages Pods)  |
     +-------------------+
             |
             v
     +-------------------+
     |       Pod         |
     +-------------------+
             |
             v
     +-------------------+
     |   Container       |
     | (Preact App +    |
     |     nginx)       |
     +-------------------+
             ^
             |
     +-------------------+
     |     Service       |
     | (LoadBalancer)    |
     +-------------------+
             ^
             |
     [Port Forwarding]
             ^
             |
     [Browser: localhost:8080]

Troubleshooting

• Pod not starting? Check logs: sudo kubectl logs <pod-name>
• Image not found? Ensure you loaded it correctly.
• Port issues? Make sure 8080 is free.

Conclusion

Congratulations! You've deployed a Preact app with K3s locally. You learned:

• Building web apps with Preact
• Containerizing with Docker
• Kubernetes basics with K3s
• Local deployment workflow

Next steps: Try scaling replicas, adding a database, or deploying to the cloud. Happy coding!

I'm actually looking for a new job. I've been a contractor for quite some time. Expertise in Rust | Python | JS |TS |Node | Go and many more. Based in London. Happy to be in the office 5 days a week if needed.

LinkedIn