Skip to main content

Installation guide

This guide takes you through installing and configuring OpsChain.

After following this guide you should know how to:

  • install OpsChain pre-requisites
  • configure Docker Hub access
  • install, configure and start OpsChain
  • create an OpsChain user
  • download the OpsChain CLI


Required software


In order to clone the latest release of the OpsChain repository you will need a Git client.


As part of configuring the environment, the OpenSSL utility is called to generate various keys.


You must have Helm version 3 installed.


OpsChain supports the following Kubernetes distributions on a single node only:

  • macOS - Docker Desktop Community 3.1.0 and above
  • Linux - the latest stable k3s with the Docker container runtime selected
  • Windows Subsystem for Linux (WSL) - the latest Docker Desktop release (installed in the WSL environment).
Windows Subsystem for Linux (WSL)

For a better CLI experience we suggest using a modern terminal (like the Windows Terminal from the Microsoft Store or a WSL terminal).

Hardware/VM requirements

OpsChain requires a minimum of 2GB of ram to function. We recommend 4GB if you intend to run our more advanced examples.

OpsChain requires a minimum of 30GB of disk to function. We recommend 100GB if you intend to run our examples without having to perform manual cleanup activities very frequently.

If using Docker for Mac the configuration UI allows you to adjust the ram and disk allocation for Docker. After changing the configuration you will need to restart the Docker service.

If using Docker for Windows the WSL configuration (or the per distribution configuration) allows you to modify the ram allocation. There is no need to adjust the disk allocation. If WSL is already running it will need to be restarted.


When using macOS or Windows we suggest ensuring that your Docker installation is not allocated too much of your system ram - or the rest of your system may struggle. As a rough guide, we suggest not allocating more than 50% of your system ram.

Image registry hostname (Linux only)

The OpsChain image registry requires a hostname different to the OpsChain API hostname (that will resolve to the Kubernetes host) to allow it to route the registry traffic.

By default OpsChain will attempt to use which resolves to If your Kubernetes host does not resolve this address (e.g. if host fails), add to your hosts file.

hostctl can be used to achieve this with the hostctl add domains opschain command.


A hostname other than can be used if desired - the value would need to be manually updated in the .env file and values.yaml file after the opschain server configure script below has been run. Alternatively the value could be added to a values.override.yaml configuration override file - see an example.


Install the OpsChain licence

Copy the opschain.lic licence file into the current folder or set the OPSCHAIN_LICENCE environment variable to the path where you stored opschain.lic.

Create a GitHub personal access token

To access the private OpsChain repositories you will need to create a GitHub personal access token.

This token will also be used for access to the example OpsChain Git repositories that been created to provide sample code for the getting started guide, and examples of how you might implement different types of changes.

Install cert-manager

OpsChain depends on cert-manager to manage its internal SSL/TLS certificates.

helm repo add jetstack
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.11.0 --set installCRDs=true

cert-manager is now ready for OpsChain to use - no additional cert-manager configuration is required.


Please contact OpsChain support if you would like the option to use OpsChain without installing cert-manager.

Install the OpsChain CLI

OpsChain has native CLI binaries for Windows, macOS and Linux. See the installation section of our CLI reference guide to download and configure the opschain executable.

The OpsChain CLI is used to configure the OpsChain server installation.

Configure OpsChain

OpsChain needs to be configured before first run (and when upgrading) by executing the opschain server configure command. This command will generate (or update) a number of configuration files in the current directory. For this reason we recommend creating a specific OpsChain configuration folder that should be used whenever you execute any opschain server subcommands.

mkdir ~/opschain-configuration # use another directory as desired
cd ~/opschain-configuration
opschain server configure

You will be asked to confirm whether you would like to use certain features and provide your credentials for the OpsChain installation.


All future opschain server commands must be run in the ~/opschain-configuration (or equivalent) directory to ensure that the right configuration is used.

Deploy the OpsChain containers

opschain server deploy

This will start the OpsChain server and its dependent services in separate Kubernetes pods. For more information on these containers see the architecture overview.

The command may take several minutes to start, especially with slower internet connections as the OpsChain images are downloaded.

The kubectl command can be used to see the deployment progress:

kubectl get all -n opschain

Once the opschain server deploy script has returned you can continue with the rest of the setup process.

Create an OpsChain user

The OpsChain API server requires a valid username and password. To create a user, execute:

opschain server utils "create_user[opschain,password]"
No spaces

Please ensure there are no spaces included in the parameter you supply to opschain server utils.

Configure the OpsChain CLI's API access

Create a CLI configuration file in your home directory based on the example:

vi ~/.opschainrc

If you changed the username or password in the create_user command above, ensure you modify the .opschainrc file to reflect your changes.

In addition, the apiBaseUrl configuration in ~/.opschainrc must be updated to reflect the external OpsChain API address. This address reflects the OpsChain listening port specified as part of the opschain server configure script. If you accepted the default setting, this will be http://localhost:3000.

Learn more about the opschainrc configuration in the CLI configuration guide.


If you create a .opschainrc file in your current directory, this will be used in precedence to the version in your home directory.

Setup the custom CA (macOS only)

On macOS, to ensure that the OpsChain registry certificate is trusted by Kubernetes the following setup is required:

kubectl -n opschain get secret opschain-ca-key-pair -o jsonpath="{\.crt}" | base64 -d > opschain-ca.pem
security add-trusted-cert -k ~/Library/Keychains/login.keychain-db -p ssl opschain-ca.pem
# You will be prompted for your admin password in a macOS dialog
Restart Docker Desktop

You must restart Docker Desktop to complete the custom CA setup.

OpsChain development environment setup (optional)

If you intend to use the OpsChain development environment (used when creating new action definitions) you will need to setup the CLI dev subcommand dependencies.

What to do next

  • (optional) OpsChain is supplied with an LDAP server for authentication. If you'd prefer to use your own LDAP server, follow the OpsChain LDAP guide to alter the OpsChain authentication configuration.
  • Return to the getting started guide to learn more about OpsChain.