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

Prerequisites​

Kubernetes​

OpsChain requires Kubernetes and will operate on any Kubernetes cluster providing certain minimum requirements are met.

For a single-node evaluation or test environment, we recommend using Docker Desktop (Windows or macOS) or K3s (Linux).

For a multi-node production environment, your cluster must be able to provide the following:

Helm​

You must have Helm version 3 installed.

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.

tip

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 opschain-image-registry.local.gd which resolves to 127.0.0.1. If your Kubernetes host does not resolve this address (e.g. if host opschain-image-registry.local.gd fails), add 127.0.0.1 opschain-image-registry.local.gd to your hosts file.

hostctl can be used to achieve this with the hostctl add domains opschain opschain-image-registry.local.gd command.

note

A hostname other than opschain-image-registry.local.gd 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.

Installation​

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 https://charts.jetstack.io
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.14.4 --set installCRDs=true

Along with internal certificates used by OpsChain, cert-manager will issue self-signed certificates for the OpsChain image registry and API server. To use these certificates, the cert-manager CA certificate must be trusted by the container runtime on your Kubernetes nodes, and by any systems from which you will access the OpsChain API.

Alternatively, cert-manager can be configured to issue certificates from an external certificate authority (e.g. Let's Encrypt, Vault, Venafi) - see the cert-manager documentation for more information.

note

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. The values that will be configured via the opschain server configure command are suitable for an evaluation or test environment, however for a production environment we recommend reviewing the configuration guide and security guide to ensure the configuration is suitable for your needs.

caution

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.

info

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="{.data.ca\.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.