Demo Environment Only: This local installation is designed for demonstration and testing purposes only. It is not intended for production use.
Prerequisites
Before starting, ensure you have:
System Requirements:
- Operating System: Linux, macOS, or Windows (WSL only)
- CPU & Memory: Minimum 4 CPU cores and 8GB RAM for Docker
- Software:
- Docker (must be running)
- Git
- Common utilities:
jq, curl, sed, grep (usually pre-installed)
Account:
- A Qovery account (free) - you’ll create one during setup
Installation Steps
Step 1: Install Qovery CLI
Linux
MacOS
Windows (WSL)
Docker
To download and install Qovery CLI on any Linux distribution:curl -s https://get.qovery.com | bash
Qovery is part of AUR packages, so you can install it with yay: Install the Qovery CLI on Linux manually by downloading the latest release, and uncompress its content to a folder into your shell PATH. The common solution to install a command line binary on the MacOS is to use Homebrew.# Add Qovery brew repository
brew tap Qovery/qovery-cli
# Install the CLI
brew install qovery-cli
To download and install Qovery CLI from the command line:curl -s https://get.qovery.com | bash
Install the Qovery CLI on Mac OS manually by downloading the latest release, and uncompress its content to a folder into your shell PATH. WSL Required: All Qovery commands must be run in a WSL (Windows Subsystem for Linux) terminal. If you haven’t installed WSL yet, follow Microsoft’s WSL installation guide. curl -s https://get.qovery.com | bash
Install Docker on your local machine and run the following command:# Pull and Run the latest Qovery CLI
docker run ghcr.io/qovery/qovery-cli:latest help
latest by the version you want to use. For example, to use the version 0.58.4, run:docker run ghcr.io/qovery/qovery-cli:0.58.4 help
Step 2: Authenticate
Sign in to your Qovery account (or create one if you haven’t already):This will open your browser to complete the authentication process.Running in a terminal without browser access? Use qovery auth --headless instead.
Step 3: Set Context
Configure your CLI context:Select your organization when prompted. Step 4: Deploy Demo Cluster
Install a local k3s Kubernetes cluster with Qovery on top:This command will:
- Install k3s (lightweight Kubernetes)
- Install Qovery agent and all required components
- Configure networking and ingress
- Take approximately 5-10 minutes to complete
macOS and Windows Users: You may be prompted for your admin password. This is necessary to properly route traffic from your host to your k3s applications.
Step 5: Access the Console
Once the installation is complete, navigate to console.qovery.comYou should see your demo cluster connected and ready to use. You can now start deploying applications! Using Your Local Cluster
Once your demo cluster is running, you can:
- Deploy applications via the Qovery Console
- Use kubectl to interact with your local k3s cluster directly
- Use k9s for a terminal-based Kubernetes dashboard
- Follow our tutorials to deploy your first application
The demo cluster runs entirely on your local machine, making it perfect for testing and development without cloud costs.
Cleanup
When you’re finished testing, remove the demo cluster:
This command removes the local k3s cluster and all Qovery components from your machine.
What’s Next?
