Skip to main content
Version: Next 🚧


This guide helps you deploy and use Epinio, with the default options. It's a good configuration for evaluation, or testing, using an existing Kubernetes cluster. For advanced Epinio deployment scenarios look at the installation documentation.


Check your Kubernetes environment meets the Epinio requirements. You'll need both a default StorageClass and a default IngressClass. If you don't yet have a suitable Kubernetes cluster, you can follow the RKE2 Installation section to get started.

Deploy Epinio

Run the kubectl get nodes -o wide command to get the INTERNAL-IP value of the first Kubernetes node in your cluser. You'll use this value along with a wildcard DNS service domain (for eg. as the helm global.domain value for installing Epinio.


If you use a local Kubernetes cluster, the value should be no matter the output from the kubectl get nodes command above.

Install cert-manager

helm repo add jetstack
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager \
--namespace cert-manager --create-namespace \
--set installCRDs=true

Install Epinio

Then install Epinio by using helm as shown below. Replace the <INTERNAL-IP> placeholder with the correct IP address:

helm repo add epinio
helm repo update
helm upgrade --install epinio epinio/epinio \
--namespace epinio --create-namespace \
--set global.domain=<INTERNAL-IP>

You can then point your browser, or Epinio, CLI at the https://epinio.<INTERNAL-IP> url.

Download the Epinio CLI binary

Install the latest Epinio CLI with brew:

brew install epinio

Or, download the desired version from the Assets section of

Deploy an application with Epinio


The first task after an Epinio installation is to login with the epinio binary:

epinio login -u admin ''

# Trust the certificate by pressing 'y' and 'enter'

You may encounter an x509 error due to mismatched certificates after a restart. You can resolve it by reloading certificates. Us the command epinio settings update-ca. It will not be necessary to log in again.

To confirm that you're logged check the Epinio settings:

epinio settings show

Push an application

Sample applications

If you want to try a working application use the one inside the sample-app directory.

You can copy it to your system with the following commands:

git clone
cd epinio/assets/

Push an application

There are two ways to push an application:

  1. You can provide an Application Manifest which has the needed configuration for the applications.
epinio push manifest.yaml
  1. You can give the configuration as parameters, in which case --name is required. As the default route is used the name must be unique across all namespaces.
epinio push --name sample --path sample-app

The --path parameter is optional. If not specified the current working directory is used. Always check that the chosen directory has a supported application.

You can read about the applications supported in Epinio supported applications.

There is also information about the more advanced git model.


For details of the epinio push process, read the detailed push docs.

Check your application is working

When pushing the application, a unique URL is printed on the console. You use this to access your application. You can get this URL again by running:

epinio app show sample

Navigate to the "Routes" section.

Go ahead and open the application URL in your browser!

List all commands

To see a list of deployed applications, use the command:

epinio apps list

Delete an application

To delete the application named "sample" run the following command:

epinio delete sample

Create a separate namespace

To keep your applications separated, you can use namespaces. Create a new namespace with this command:

epinio namespace create newspace

To start deploying application to this new namespace you have to target it:

epinio target newspace

Until you target another namespace, epinio push deploys to newspace.