Install Your First Cluster with k3s

Prerequisites

You need a Linux machine — this can be a local VM, a cloud VPS (DigitalOcean, Hetzner, AWS EC2, etc.), or bare-metal hardware.

You also need curl and root access. Before starting, make sure you're logged in as root or switch to root:

sudo su

Install k3s

SSH into your machine and run the official install script. This installs the k3s server, kubectl, and starts the cluster in under a minute.

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

That's it. k3s is now running as a systemd service. You can check the service status with:

systemctl status k3s

Verify the Cluster

k3s ships with its own kubectl. Confirm the node is ready and system pods are running:

k3s kubectl get nodes

You should see your node with status Ready. Then check that all system pods are running:

k3s kubectl get pods -A

All pods in the kube-system namespace should be Running or Completed within a minute or two.

Configure kubeconfig

k3s writes its kubeconfig to /etc/rancher/k3s/k3s.yaml. Copy it to your local machine so CodePier and kubectl can use it.

On the server — make the config readable

cat /etc/rancher/k3s/k3s.yaml

On your local machine — save the config

Copy the output from above and save it to a file on your local machine. Replace 127.0.0.1 with your server's IP address or hostname:

# Save the kubeconfig (paste the contents from the server)
mkdir -p ~/.kube
nano ~/.kube/k3s.yaml

# Replace the server address — change 127.0.0.1 to your server's IP
# Before: server: https://127.0.0.1:6443
# After:  server: https://YOUR_SERVER_IP:6443

# Set the KUBECONFIG environment variable
export KUBECONFIG=~/.kube/k3s.yaml

# Verify connectivity from your local machine
kubectl get nodes

Connect to CodePier

Open the CodePier desktop app and add your new cluster:

1. Go to Clusters in the sidebar
2. Click Add Cluster
3. Select your kubeconfig file (~/.kube/k3s.yaml)
4. CodePier will detect the cluster and show it as connected

Deploy Your First App

Now that your cluster is connected, let's deploy a simple Node.js app. We'll use our node-getting-started sample repo to walk through the full flow.

Create a project

1. Open the CodePier app and click New Project
2. Enter a Project Name — for this guide, use hello-world
3. Choose a Namespace — this defaults to your project name. Keep it as hello-world

Add your resources

Inside your project, you'll create three resources — a Deployment, a Service, and an Ingress. For each one:

1. Click Add Resource
2. Pick the resource type (Deployment, Service, or Ingress)
3. CodePier opens the manifest editor with a starter template — edit it to match your app

Here's what the manifests should look like for the sample app:

Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-world
  namespace: hello-world
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello-world
  template:
    metadata:
      labels:
        app: hello-world
    spec:
      containers:
        - name: hello-world
          image: ghcr.io/codepier/node-getting-started:latest
          ports:
            - containerPort: 3000

Service

apiVersion: v1
kind: Service
metadata:
  name: hello-world
  namespace: hello-world
spec:
  selector:
    app: hello-world
  ports:
    - port: 3000
      targetPort: 3000

Ingress

k3s ships with Traefik as its default ingress controller. Use a .local hostname so the app is immediately reachable from any device on your network — CodePier publishes it via mDNS / Bonjour, no /etc/hosts editing required. (On Linux, install avahi-utils first.)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello-world
  namespace: hello-world
spec:
  rules:
    - host: hello-world.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: hello-world
                port:
                  number: 3000

Ship it

Once your manifests are ready, click Apply in the editor to deploy each resource to your cluster. CodePier shows a diff of what's changing so you can review before applying.

When all three resources are applied, open https://hello-world.local in your browser — you should see "Hello World!".

Start Developing

Your app is live in the cluster. Now clone the sample repo and hot-swap the running container with your local code.

git clone https://github.com/codepier/node-getting-started.git
cd node-getting-started

The repo includes a codepier.yaml that configures the dev environment:

deployment: hello-world
namespaces: [hello-world]

image: node:24-slim

workdir: /opt/hello-world

sync:
  - ".:/opt/hello-world"

ignore:
  - "node_modules"
  - ".git"

cache:
  - npm:~/.npm

Start the hot-swap:

codepier up

CodePier replaces the running container with a node:24-slim dev container, syncs your local files in real-time, and caches your npm packages between sessions. It drops you into an SSH session inside the pod. From there, install dependencies and start the dev server:

npm install
npm run dev

Any changes you make locally are reflected instantly in the cluster — and the Ingress keeps serving traffic at https://hello-world.local. Try editing index.js and watch it reload.

When you're done, exit the SSH session and CodePier automatically restores the original deployment.

Next Steps