Getting Started

This guide takes you from a fresh Linux server to a running app with HTTPS and a web console. Run the commands on your own Linux, macOS or Windows computer. Kipper uses SSH to set up the server, then APIs to deploy and manage your workloads.

To join a cluster someone has already installed, follow Team Access.

Prerequisites

• A supported server: Ubuntu 22.04, 24.04, or 26.04; Debian 12 or 13; or Rocky Linux, AlmaLinux or CentOS Stream 9 or 10, with a public IP address and SSH access as root, or as a user with passwordless sudo. Kipper also accepts Ubuntu 20.04 and Debian 11, with a warning that standard support has ended.
• Capacity: the installer requires at least 4 GB RAM and enough disk space for Kipper's system volumes and images. Start with a 40 GB disk and allow additional capacity for your apps and databases. See sizing guidance.
• An SSH key: add the public key to the server's root account. You should be able to connect with ssh root@your-server. Cloud images that log you in as ubuntu or ec2-user work as well: pass that user with --ssh-user (see logging in as a user other than root). On Windows, kip can create the key and add its public key to the server.
• Provider firewall rules: allow SSH and ports 80 and 443. Allow port 6443 from the addresses that will use the Kubernetes API, including your own computer.

Kipper configures the server's firewall during installation: UFW on Ubuntu and Debian, firewalld on Rocky Linux, AlmaLinux and CentOS Stream. Kipper preserves active firewalls you manage unless you grant permission to take them over.

When installing over SSH from a terminal, kip install asks before taking over an eligible running UFW or firewalld and lists the proposed changes. With --via-server, including on Windows, the prompt appears on your computer before a new server job starts. Without a terminal, grant permission with --adopt-firewall. If you decline, Kipper preserves your firewall. For firewalld, it then checks required cluster access, and installation stops if required rules are missing or cannot be evaluated. See host security for details.

The free *.kipper.run address works with Kipper-managed DNS. To use your own domain at install time, configure its DNS records first.

Step 1: Install the CLI

Linux / macOS

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

Windows (PowerShell)

irm https://getkipper.com/install.ps1 | iex
kip --version

Both installers verify the download against the release's checksums. On Windows, the installer places kip in %LOCALAPPDATA%\Programs\kip and adds this folder to your user PATH. The default Windows installation requires no administrator rights. If kip is not found, open a new PowerShell window. See Installing from Windows for details.

To build the CLI from source, see Contributing.

Step 2: Install the cluster

Replace the example IP, key path, and email with your own:

Linux / macOS

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

Windows (PowerShell)

kip install --host 203.0.113.10 --admin-email admin@example.com

On Windows, unless you set --ssh-key or KIP_SSH_KEY, kip uses the default key at %USERPROFILE%\.ssh\id_ed25519 and offers to create it if it is missing. If the server rejects the key, kip offers to add its public key through a separate SSH login, which may prompt for the root password. The installation runs on the server and continues if your connection drops.

Kipper checks the server, installs the platform, and prints the console URL and admin sign-in details. The free cluster address is derived from the server's IP; in this example it is 203-0-113-10.kipper.run.

Save the printed admin password. Kipper stores its hash. If you lose the password, kip auth reset-password generates a replacement.

The final step opens a browser. Sign in with the admin address and password from the output so the installer can verify your Kubernetes access. If you skip sign-in, or install with --no-login, finish it later:

kip auth login
kip auth verify

Step 3: Verify the cluster

kip status

Check that the node and platform components are ready. Components may take a little longer to become ready after installation; wait a minute and check again if needed.

The output also includes a DNS resolver audit. For resolver warnings, see kip cluster dns repair.

Step 4: Deploy your first app

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

Open the HTTPS URL printed by the command. Once the deployment is ready, you should see the nginx welcome page.

Check the app and read its logs:

kip app list
kip app logs hello

Add -f to keep streaming new lines until you press Ctrl+C.

Visit the console URL printed during installation and sign in with the same account. The dashboard shows your cluster, apps, and services.

Step 5: Try configuration and secrets

Save an environment variable or a secret:

kip app env set hello LOG_LEVEL=debug
kip app secret set hello EXAMPLE_TOKEN

The secret command prompts for hidden input. These commands save values for the app; they take effect when its pods restart:

kip app restart hello

Nginx does not use these example variables. Your own app can read them through its normal environment-variable API. See Secrets & Environment Variables for templates, previews, and rollback.

Step 6: Add a database when your app needs one

kip service add postgres --name mydb
kip service info mydb

Bind the service to an app that uses PostgreSQL:

kip service bind mydb myapp

Replace myapp with that app's name. The binding supplies connection details as environment variables. See Stateful Services for supported services and binding names.

Keeping Kipper up to date

kip upgrade

The command updates Kipper and offers to reconcile system components. System upgrades can briefly disrupt workloads, so review the confirmation before proceeding. See upgrade options, including --skip-system for keeping component versions in place.

What's next?

• Deploy your application from an image or Git repository.
• Create projects and environments for test and production.
• Invite your team and assign project roles.
• Configure backups for recovery.
• Use your own domain.

To remove the example app:

kip app delete hello