Skip to main content
Version: Next

Where to download opscotch

opscotch is available for download as zip files or as docker images.

Download zip files​

Downloads for opscotch can be found on the opscotch github releases

There are 3 zip files to download (available for various operating systems):

  • agent
  • packager
  • test runner

Each zip file contains an executable which you will need to extract to your preferred location.

Verifying Downloads (Signature Verification)​

All Opscotch ZIP downloads are cryptographically signed at release time using keyless signing provided by Sigstore and Cosign.

This allows you to verify that:

  • the file was produced by the opscotch release pipeline
  • the ZIP has not been modified since publication
  • the artifact genuinely originated from opscotch
danger

The ZIP file itself is the signed artifact. Verification should be performed before extracting the archive.

Files provided for each release​

For each ZIP download, the release includes the following files:

  • <artifact>.zip — the downloadable distribution
  • <artifact>.zip.sig — the detached signature
  • <artifact>.zip.pem — the signing certificate

How to verify a download​

Install Cosign​

Cosign is an open-source signing and verification tool from the Sigstore project.

Installation methods vary by operating system and environment.

Please follow the official Cosign installation instructions

Ensure the cosign binary is available on your PATH before continuing.

Verify​

Download the .zip file and the accompanying .zip.sig and .zip.pem.

Run the following command before unzipping:

cosign verify-blob \
  <artifact>.zip \
  --signature <artifact>.zip.sig \
  --certificate <artifact>.zip.pem \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/opscotch/builder/.github/workflows/release.yml@.*$'

If verification succeeds, Cosign will report that:

the signature is valid

the artifact was signed by the expected Opscotch GitHub Actions workflow

Only after successful verification should the ZIP be extracted and used.

Docker​

opscotch is available as a docker image.

Browse available packages here.

Beta channel images are published as ghcr.io/opscotch/opscotch-agent-beta:<tag>.

There are two main tags for the runtime image:

  • latest is the latest production runtime image
  • latest-dev is the latest non-production runtime image

These resolve to:

  • ghcr.io/opscotch/opscotch-agent:latest
  • ghcr.io/opscotch/opscotch-agent:latest-dev

Other published versions and tags can be browsed in the package registry link above.

Verifying Docker Images (Cosign)​

Opscotch Docker images published to GHCR are also signed with Cosign keyless signing.

Docker signatures are produced by:

  • https://github.com/opscotch/builder/.github/workflows/docker-publish.yml

Verify a Docker image signature​

You should verify by digest for immutability.

1. Resolve digest​

docker pull ghcr.io/opscotch/opscotch-agent:latest
docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/opscotch/opscotch-agent:latest

This returns a digest reference like:

ghcr.io/opscotch/opscotch-agent@sha256:...

2. Verify signature​

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/opscotch/builder/.github/workflows/docker-publish.yml@.*$' \
  ghcr.io/opscotch/opscotch-agent@sha256:<digest>

If verification succeeds, the image digest was signed by the expected Opscotch GitHub Actions workflow.

Docker defaults​

By default the agent will run in the /config directory and attempt to load /config/bootstrap.json.

So long as you ensure your configs are in /config and there is a /config/bootstrap you can simply start the container.

Docker running from local filesystem​

To run docker against your local file system, where bootstrap.json is in the current directory you can do this:

docker \
    run \
    -v .:/config \
    ghcr.io/opscotch/opscotch-agent:latest-dev

Building a custom image from Dockerfile​

If you want to create your own image from a dockerfile perhaps for your prod deployment with a packaged opscotch app (assumes the bootstrap references my-opscotch.app), you can do something like this dockerfile:

FROM ghcr.io/opscotch/opscotch-agent:latest

COPY my-opscotch.bootstrap.json /config/bootstrap.json
COPY my-opscotch.app /config/my-opscotch.app

Docker configuration options​

Here is a list of the docker settings that can be set:

  • CONFIG_DIR

    • the working directory and the directory where configuration is expected
    • defaults to /config
    • when running locally, set with a volume mount:
      • -v .:/config
    • override with an environment variable:
      • -e "CONFIG_DIR=/new-config"

  • BOOTSTRAP_FILE

    • the bootstrap file that is passed to the agent
    • defaults to /${CONFIG_DIR}/bootstrap.json
    • override with an environment variable:
      • -e "BOOTSTRAP_FILE=new-bootstrap.json"

  • BOOTSTRAP_B64

    • the boostrap supplied as a base64 string. This takes precedence over the bootstrap file.
    • defaults to nothing
    • override with an environment variable:
      • -e "BOOTSTRAP_B64=...."

  • RESOURCE_DIR

    • this will set the RESOURCE_DIR environment variable for the agent to use.
    • defaults to nothing
    • when overriding, ensure the paths are present in the container by copying or mounting
    • override with an environment variable:
      • -e "RESOURCE_DIR=/resource1;/resource2"
    • note: it is common to mount your own app resources as well as the opscotch community resources:
      • -v ./app-resources:/app-resources
      • -v ./community-resources:/community-resources
      • -e "RESOURCE_DIR=/app-resources;/community-resources"

  • OPSCOTCH_OPTS

    • additional opscotch agent cli arguments