Overview
Run Qovery on your local machine using Docker and k3s (lightweight Kubernetes). Perfect for development, testing, and learning without cloud costs or Docker Desktop requirements.
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 daemon running (Docker Desktop not required, especially on Linux)
- Git
- Common utilities:
jq, curl, sed, grep (usually pre-installed)
Linux Users: You only need Docker Engine running on your machine. Docker Desktop is not required.
Installation Steps
Install Qovery CLI
Linux
MacOS
Windows
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. The classic way to install binaries on Windows is to use Scoop.# Add Qovery bucket
scoop bucket add qovery https://github.com/Qovery/scoop-qovery-cli
# Install the CLI
scoop install qovery-cli
Install the Qovery CLI on Windows manually by downloading the latest release, and uncompress its content to C:\Windows. 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
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.
Set Context
Configure your CLI context:Select your organization when prompted. Deploy Local Cluster
Install a local k3s Kubernetes cluster with Qovery: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.
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 local 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 tutorials to deploy applications locally
The local cluster runs entirely on your machine, making it perfect for testing and development without cloud costs.
Limitations
Local Kubernetes is NOT for production:
- Single node (no high availability)
- Limited resources
- Loses data on restart
- Performance limitations
Cleanup
When you’re finished testing, remove the local cluster:
This command removes the local k3s cluster and all Qovery components from your machine.
Next Steps
