Initial Setup


  • Install Docker Desktop
  • Go to Docker Desktop Preferences
  • Go to the Advanced tab
  • Drag the CPU slider to the halfway point
  • Drag the Memory slider to at least 8GB
  • Go to the Kubernetes tab
  • Enable Kubernetes(there is a known bug when using Kubernetes 1.22+. Please refer to known-issues)


Convox CLI

x86_64 / amd64

    $ curl -L -o /tmp/convox
    $ sudo mv /tmp/convox /usr/local/bin/convox
    $ sudo chmod 755 /usr/local/bin/convox


    $ curl -L -o /tmp/convox
    $ sudo mv /tmp/convox /usr/local/bin/convox
    $ sudo chmod 755 /usr/local/bin/convox


Make sure that your kubectl points at your local docker setup. Ensure that if your KUBECONFIG env var is set, it is pointing at a config file that contains your desktop context. By default, your local context will be installed into ~/.kube/config.

Also ensure that the context is indeed set to docker-desktop. If not, just run:

    $ kubectl config use-context docker-desktop

Install a local Rack named dev.

    $ convox rack install local dev

DNS Setup

Set *.convox to be resolved by the local Rack’s DNS server.

    $ sudo mkdir -p /etc/resolver
    $ sudo bash -c 'echo "nameserver" > /etc/resolver/convox'

CA Trust

To remove browser warnings about untrusted certificates for local applications you can trust the Rack’s CA certificate.

This certificate is generated on your local machine and is unique to your Rack.

    $ kubectl get secret/ca -n dev-system -o jsonpath="{.data.tls\.crt}" | base64 --decode > /tmp/ca
    $ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/ca