---
title: Installation
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

- For Installation from existing Kubernetes Cluster, please read the [advanced installation guide](./platform-engineers/advanced-install#install-kubevela-with-existing-kubernetes-cluster).
- For upgrading from existing KubeVela control plane, please read the [upgrade guide](./platform-engineers/advanced-install#upgrade).

## 1. Install VelaD

[VelaD](https://github.com/kubevela/velad) packages KubeVela with all dependencies that enables you to run KubeVela on any of docker compatible environments or linux system.

- VelaD provides Kubernetes by leveraging [K3s](https://rancher.com/docs/k3s/latest/en/quick-start/) on linux or [k3d](https://k3d.io/) on docker environment.
- KubeVela along with all related images, and `vela` command line are packaged together that enables air-gapped installation.
- **VelaD suits great for local development and quick demos, while we strongly recommend you to [install KubeVela with managed Kubernetes services](./platform-engineers/advanced-install#install-kubevela-with-existing-kubernetes-cluster) for production usage**.

### Prerequisites

- Docker v20.10.5+ (runc >= v1.0.0-rc93) **or** Linux system

### Download VelaD

It will download and place the binary in your system `PATH`,
so you may be required for root privilege during the installation process.
If you don't need the automation with root access, you can download from the [release page](https://github.com/kubevela/velad/releases) and uncompress manually.

- ** MacOS/Linux **

```shell
curl -fsSl https://static.kubevela.net/script/install-velad.sh | bash -s 1.4.2
```

- **Windows**

> Only the official release version is supported.

```shell
powershell -Command "iwr -useb https://static.kubevela.net/script/install-velad.ps1 | iex"
```

Check `velad` and `vela` command line tools are exist in `/usr/local/bin/` for MacOS/Linux or `C:\vela\` for Windows.

### Setup

```shell
velad install
```

expected output:

```
Preparing K3s images...
Successfully prepare k3s image:  /Users/sunjianbo/.vela/velad/k3s/k3s-airgap-images-amd64.tgz
Successfully prepare k3d images

...snip...

KubeVela control plane has been successfully set up on your cluster.
If you want to enable dashboard, please run "vela addon enable /Users/sunjianbo/.vela/addons/velaux"

Keep the token below if you want to restart the control plane
K1075e7f6c77555e6ebdaf4854e4a2f39ae4287cfad23f27cdac5b33608d44633fe::server:zSpzbdbGzVxOwfBvvjgT

🚀  Successfully install KubeVela control plane
🔭  See available commands with `vela help`
```

**Export the Kubernetes config **

```
export KUBECONFIG=$(velad kubeconfig --host)
vela comp
```

## 2. Install VelaUX

> This is optional if you don't use UI console of KubeVela.

VelaUX is a dashboard including UI console and API services.

```shell script
vela addon enable ~/.vela/addons/velaux
```

expected output:

```
Addon: velaux enabled Successfully.
```

By default, velaux didn't have any exposed port, you can view it by:

```
vela port-forward addon-velaux -n vela-system 8080:80
```

Choose `> Cluster: local | Namespace: vela-system | Component: velaux | Kind: Service` for visit.

If you have loadbalaner or ingress, please refer to [VelaUX addon docs](./reference/addons/velaux) for more advanced installation ways.

VelaUX need authentication. Default username is `admin` and the password is `VelaUX12345`.
It requires you to override with a new password for the first login, please make sure to remember the new password.

## 3. Cleanup

```
velad uninstall
```

This command will clean up KubeVela controllers along with the Kubernetes cluster, refer to [the advanced guide](./platform-engineers/advanced-install#uninstall) for more detailed steps.

## Next Step

- [Deploy your first application](./quick-start).