Getting Started

This guide walks you through installing Skipper on a fresh Linux server and deploying your first application. By the end, you will have a running Kubernetes cluster with automatic SSL and a web console.

Prerequisites

• A Linux server with root SSH access (Ubuntu 22.04, 24.04, or Debian 11, 12)
• Minimum 2 vCPU, 4GB RAM, and 40GB disk (4 vCPU / 8GB recommended)
• Ports 80, 443, and 6443 open
• An SSH key on your local machine

Any Linux VPS will work

Any cloud provider or hosting company that gives you a Linux VM with a public IP and root SSH access will work. A VPS with 4 vCPU, 8GB RAM, and 80GB disk is recommended for running multiple services with databases.

Step 1: Install the CLI

Quick install (Linux/macOS):

curl -sL https://getkipper.com/install | sh

Windows:

Download kip-windows-amd64.exe from the latest release, rename to kip.exe, and add the directory to your PATH.

Windows and kip install

All kip commands work natively on Windows. The one exception is kip install, which uses SSH to connect to a Linux server. For this command, use WSL or Git Bash.

Or build from source:

git clone https://git.labb.tools/labb-consulting/oss/skipper
cd skipper/kip && go build -o kip .
sudo mv kip /usr/local/bin/

Verify it works:

kip --version

Step 2: Install the cluster

Point Skipper at your server's IP address. It will SSH in, run preflight checks, and install everything automatically.

kip install --host 203.0.113.10 --ssh-key ~/.ssh/id_ed25519 --admin-email admin@example.com

You will see output like this:

  Connecting to 203.0.113.10...
  ✔  Connected

  Running preflight checks...
  ✔  OS: ubuntu 24.04
  ✔  RAM: 3820MB available
  ✔  Disk: 35370MB available
  ✔  Ports: 80, 443, 6443 open

  Registering subdomain...
  ✔  Subdomain assigned: 203-0-113-10.kipper.run

  Installing cluster...
  ...  Installing k3s
  ✔  Installing k3s
  ...  Installing Traefik ingress
  ✔  Installing Traefik ingress
  ...  Configuring cert-manager
  ✔  Configuring cert-manager
  ...  Setting up storage
  ✔  Setting up storage
  ...  Configuring identity provider
  ✔  Configuring identity provider
  ...  Deploying console
  ✔  Deploying console

  Cluster ready.
  Console:    https://console-203-0-113-10.kipper.run
  Kubeconfig: /Users/you/.kip/clusters/203-0-113-10.kipper.run.yaml
  Admin:      admin@203-0-113-10.kipper.run
  Password:   02026a371f24a488a86e654cada6e1c6

  Save these credentials now. They will not be shown again.
  If lost, run: kip auth reset-password

Step 3: Verify the cluster

kip status

  Cluster: 203-0-113-10.kipper.run
  Host:    203.0.113.10
  Config:  /Users/you/.kip/clusters/203-0-113-10.kipper.run.yaml

  Nodes:
    ✔  ubuntu-4gb-nbg1-4    master   Ready    v1.34.5+k3s1

  Components:
    ✔  k3s              1 node(s)
    ✔  Traefik          1/1 replicas available
    ✔  cert-manager     1/1 replicas available
    ✔  Longhorn         1/1 replicas available
    ✔  Dex              1/1 replicas available
    ✔  Console API      1/1 replicas available
    ✔  Console          1/1 replicas available

Step 4: Deploy your first app

kip app deploy --name hello --image nginx:latest --port 80

  Deploying hello...
  ✔  Deployment created
  ✔  Service created
  ✔  Ingress created
  ✔  Live at https://hello-203-0-113-10.kipper.run

Open the URL in your browser. You should see the nginx welcome page, served over HTTPS with a valid Let's Encrypt certificate.

Step 5: Manage your app

# List all deployed apps
kip app list

# Stream logs
kip app logs hello

# Set environment variables
kip app env set hello LOG_LEVEL=debug

# Set a secret (prompts for hidden input)
kip app secret set hello DATABASE_URL

# Update the image
kip app update hello --image nginx:1.27

# Restart the app
kip app restart hello

# Delete the app
kip app delete hello

Step 6: Add a database

kip service add postgres --name mydb

  Creating postgres service "mydb"...
  ✔  StatefulSet created
  ✔  Persistent storage provisioned
  ✔  Credentials generated

  Connection details:
    Host:     mydb.default.svc.cluster.local
    Port:     5432
    Username: skipper
    Password: a1b2c3d4e5f6...
    Database: app

  To bind to an app:
    kip service bind mydb <app>

Bind the database to your app so it receives connection details as environment variables:

kip service bind mydb hello

Step 7: Open the console

Visit the console URL from the install output (e.g. https://console-203-0-113-10.kipper.run) and sign in with your admin credentials. The dashboard shows cluster health, nodes, deployed apps, and services.

Step 8: Upgrade Skipper

When a new version of the Skipper console is available, upgrade with:

kip upgrade

This pulls the latest console images and restarts the system components. Your apps and services are not affected.

What's next?

• Deploy a real application from a container image
• Add a database or cache with persistent storage
• Manage projects to organize your apps
• Configure secrets for database URLs and API keys
• Share access with your team so developers can deploy and debug
• Set up a custom domain instead of using kipper.run