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.
SOCIAL SHARE CARD GENERATOR