Varnish Orca
← Orca documentation

Installation

Learn how to install Varnish Orca on the supported platforms.

Docker

Step 1: Run the container

docker run -p 80:80 varnish/orca

Varnish should now be listening to port 80 with the default configuration.

Step 2: Customize configuration (Optional)

Create config.yaml and mount it into the container at /etc/varnish-supervisor/default.yaml:

docker run -p 80:80 -v $(pwd)/config.yaml:/etc/varnish-supervisor/default.yaml varnish/orca

When using multiple configuration files, it is better to mount a directory into the container like so:

docker run -p 80:80 -v $(pwd):/cfg varnish/orca --config /cfg/config1.yaml:/cfg/config2.yaml

Docker Compose

Step 1: Clone the Orca Git repository

git clone https://github.com/varnish/orca.git && cd orca

Step 2: Start the docker compose

docker compose up

This command uses the docker-compose.yaml file to orchestrate the Docker container. The container’s port 80 is forwarded to the host system’s port 80 by this configuration, and uses the standard Orca configuration.

Step 3: Optionally mount a custom Orca config file

If you want to customize the configuration of Varnish Orca, you can mount a config.yaml file into the container by using the following docker-compose.yaml setup:

services:
  orca:
    image: varnish/orca
    ports:
      - "80:80"
    volumes:
        - ./config.yaml:/app/config.yaml:ro
    command: --config /app/config.yaml

Don’t forget to run docker compose down to tear down the existing container setup before running docker compose up again.

We also have tutorials that teaches you how to enable TLS and register a custom Orca license using docker compose:

Kubernetes (using the Helm Chart)

If you want to deploy Varnish Orca to a Kubernetes cluster, you can use our official Helm Chart.

The Helm Chart for Orca has a whole range of configurable settings that are listed on the chart’s README.md file on GitHub.

You can simply run helm install varnish-orca oci://docker.io/varnish/orca-chart to deploy Varnish Orca to your Kubernetes cluster using Helm. However, it makes sense to configure your Kubernetes deployment by overriding some settings in values.yaml.

Step 1: Create a values.yaml file

Create a values.yaml file that contains the configuration settings you want to override. The orca section of the values.yaml file reflects the configuration specification of Orca.

The following code block illustrates how you can override values.yaml to configure the supported registries of your Varnish Orca deployment:

orca:
  virtual_registry:
    registries:
    - name: dockerhub
      default: true
      remotes:
      - url: https://docker.io
    - name: quay
      remotes:
      - url: https://quay.io
    - name: ghcr
      remotes:
      - url: https://ghcr.io
    - name: k8s
      remotes:
      - url: https://registry.k8s.io
    - name: npmjs
      remotes:
      - url: https://registry.npmjs.org
    - name: go
      remotes:
      - url: https://proxy.golang.org
    - name: github
      remotes:
      - url: https://github.com
    - name: gitlab
      remotes:
      - url: https://gitlab.com

We have tutorials that teaches you how to enable TLS and register a custom Orca license using the Helm Chart:

Step 2: Install the Helm Chart

Run the following command to install the Helm Chart and deploy Varnish Orca to your Kubernetes cluster:

helm install -f values.yaml varnish-orca oci://docker.io/varnish/orca-chart

This command uses the custom values.yaml file to override the standard configuration. The name of the Helm deployment in this case is varnish-orca.

You can run helm status varnish-orca to check the status of the Helm deployment, and you can run kubectl get all -A -l "app.kubernetes.io/name=orca-chart,app.kubernetes.io/instance=varnish-orca" to check the status of the deployment in Kubernetes.

Install on Debian/Ubuntu

To install Varnish Orca on a Debian-based system, you can install the varnish-supervisor DEB package. This package is in fact installed in the varnish/orca Docker image, and the only difference is that varnish/orca comes with additional default configuration.

Step 1: Configure the repository

curl -s https://packagecloud.io/install/repositories/varnishplus/60-enterprise/script.deb.sh | sudo bash

Step 2: Install the package

sudo apt -y install varnish-supervisor

Verify successful installation:

varnish-supervisor --version

The varnish-supervisor service should start automatically:

systemctl status varnish-supervisor

Step 3: Customize configuration (Optional)

The package installs a default configuration file in /etc/varnish-supervisor/default.yaml. You can either edit this file directly (it won’t be replaced when upgrading the package), or change the ``–config` argument to a different path:

sudo systemctl edit --full varnish-supervisor

To have the changes take effect, restart the service:

sudo systemctl restart varnish-supervisor

Install on RHEL/CentOS

To install Varnish Orca on a RHEL-based system, you can install the varnish-supervisor RPM package.

Step 1: Configure the repository

curl -s https://packagecloud.io/install/repositories/varnishplus/60-enterprise/script.rpm.sh | sudo bash

Step 2: Install the package

sudo yum -y install varnish-supervisor

To verify successful installation, run:

varnish-supervisor --version

Step 3: Start the service

On RHEL-based systems, services should not be started automatically during installation, so you have to enable it explicitly:

sudo systemctl enable varnish-supervisor && sudo systemctl enable varnish-supervisor

Check that systemd service started successfully:

systemctl status varnish-supervisor

Step 4: Customize configuration (Optional)

The package installs a default configuration file in /etc/varnish-supervisor/default.yaml. You can either edit this file directly (it won’t be replaced when upgrading the package), or change the ``–config` argument to a different path:

sudo systemctl edit --full varnish-supervisor

To have the changes take effect, restart the service:

sudo systemctl restart varnish-supervisor

Troubleshooting

Check that Varnish is accepting traffic

Varnish has a health-check endpoint at /healthz, and will respond with a 200 OK to all requests on that path regardless of Host.

curl http://localhost/healthz -I

HTTP/1.1 200 OK
Date: Wed, 29 Oct 2025 16:17:17 GMT
Content-Length: 0
Accept-Ranges: bytes
Connection: keep-alive

The default configuration has Varnish listening for HTTP traffic on port 80. If you have changed this to a different port, make sure to curl the right port and protocol (use https:// for HTTPS endpoints).

Insecure Registry

On Mac (and probably Windows), where docker is actually a linux-vm under the hood, you have to add localhost as a insecure registry.

On docker host /etc/docker/daemon.json

{
	"insecure-registries": [ "localhost:80" ]
}

Colima .colima/default/colima.yaml

docker:
  insecure-registries:
    - localhost:80

On Docker Desktop and Podman and other GUI tools this is usually a field under preferences. Find it and add localhost:80 as Insecure Registry