Skip to main content
Version: 1.9.0


This guide will help you deploy and use Epinio with default options suitable for evaluation or testing purposes on an existing Kubernetes cluster. For advanced Epinio deployment scenarios look into Installation Section.


Make sure your Kubernetes environment fulfills the Epinio Requirements. A default StorageClass as well as a default IngressClass are required. If you do not have a suitable Kubernetes cluster yet, you can follow the RKE2 Installation section.

Deploy Epinio

Run the kubectl get nodes -o wide command to get the INTERNAL-IP value of the first Kubernetes node. Later you will use this value along with a wildcard DNS service domain (for eg. as helm global.domain value for installing Epinio.


If you use Local Kubernetes Cluster, the value should be regardless of the output from the command above. Please refer to your Local Kubernetes Cluster documentation for the IP address details of the Ingress endpoint.

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 Epinio can be deployed 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 and/or epinio CLI to 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 and architecture from the Assets section of

Deploy an application with Epinio


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

epinio login -u admin ''

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

If you encounter an x509 error due to mismatched certificates after a restart, you can resolve it by reloading the certificates with epinio settings update-ca without having to log in again.

You can confirm that you're logged in by checking the Epinio settings:

epinio settings show

Push an application

Sample applications

If you just want an application that works 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 app

There are two ways to push an application:

  1. You can provide an Application Manifest which contains the required configuration for the applications.
epinio push manifest.yaml
  1. You can provide the configuration as parameters in which case the parameter --name is mandatory. Because of the default route the name has to be unique across all namespaces.
epinio push --name sample --path sample-app

Note that the --path parameter is optional. If not specified the current working directory will be used. Always ensure that the chosen directory contains a supported application.

If you want to know what applications are supported in Epinio, please read the notes about supported applications.

We also provide information about the more advanced git model.

Note: If you want to know the details of the epinio push process, please read the detailed push docs

Check that your application is working

After the application has been pushed, a unique URL is printed which you can use to access your application. If you don't have this URL available anymore you can find it again by running:

epinio app show sample

("Routes" is the part your are looking for)

Go ahead and open the application route in your browser!

List all commands

To see all the applications you have deployed use the following command:

epinio apps list

Delete an application

To delete the application you just deployed run the following command:

epinio delete sample

Create a separate namespace

If you want to keep your various application separated, you can use the concept of 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

After this and until you target another namespace, whenever you run epinio push you will be deploying to this new namespace.