/bin/bash <(curl -fsSL https://raw.githubusercontent.com/stackrox/stackrox/master/scripts/quick-helm-install.sh)

A default deployment of StackRox has certain CPU and memory requests and may fail on small (e.g. development) clusters if sufficient resources are not available. You may use the --small command-line option in order to install StackRox on smaller clusters with limited resources. Using this option is not recommended for production deployments.

/bin/bash <(curl -fsSL https://raw.githubusercontent.com/stackrox/stackrox/master/scripts/quick-helm-install.sh) --small

The script adds the StackRox helm repository, generates an admin password, installs stackrox-central-services, creates an init bundle for provisioning stackrox-secured-cluster-services, and finally installs stackrox-secured-cluster-services on the same cluster.

Finally, the script will automatically open the browser and log you into StackRox. A certificate warning may be displayed since the certificate is self-signed. See the Accessing the StackRox User Interface (UI) section to read more about the warnings. After authenticating you can access the dashboard using https://localhost:8000/main/dashboard.

First, the StackRox Central Services will be added to your Kubernetes cluster. This includes the UI and Scanner. To start, add the stackrox/helm-charts/opensource repository to Helm.

helm repo add stackrox https://raw.githubusercontent.com/stackrox/helm-charts/main/opensource/

To see all available Helm charts in the repo run (you may add the option --devel to show non-release builds as well)

helm search repo stackrox

To install stackrox-central-services, you will need a secure password. This password will be needed later for UI login and when creating an init bundle.

ROX_ADMIN_PASSWORD="$(openssl rand -base64 20 | tr -d '/=+')"

From here, you can install stackrox-central-services to get Central and Scanner components deployed on your cluster.

Note: You need only one deployed instance of stackrox-central-services even if you plan to secure multiple clusters.

To perform the installation, choose one of the following commands depending on your cluster size.

If you're installing in a reasonably sized cluster, use the default installation command:

helm upgrade --install -n stackrox --create-namespace stackrox-central-services \
  stackrox/stackrox-central-services \
  --set central.adminPassword.value="${ROX_ADMIN_PASSWORD}" \
  --set central.persistence.none="true"

If you're installing in a single node cluster, or the default installation results in pods stuck pending due to lack of resources, use the following command instead to reduce stackrox-central-services resource requirements. Keep in mind that these reduced resource settings are not suited for a production setup.

helm upgrade --install -n stackrox --create-namespace stackrox-central-services \
  stackrox/stackrox-central-services \
  --set central.adminPassword.value="${ROX_ADMIN_PASSWORD}" \
  --set central.persistence.none="true" \
  --set central.resources.requests.memory=1Gi \
  --set central.resources.requests.cpu=1 \
  --set central.resources.limits.memory=4Gi \
  --set central.resources.limits.cpu=1 \
  --set central.db.resources.requests.memory=1Gi \
  --set central.db.resources.requests.cpu=500m \
  --set central.db.resources.limits.memory=4Gi \
  --set central.db.resources.limits.cpu=1 \
  --set scanner.autoscaling.disable=true \
  --set scanner.replicas=1 \
  --set scanner.resources.requests.memory=500Mi \
  --set scanner.resources.requests.cpu=500m \
  --set scanner.resources.limits.memory=2500Mi \
  --set scanner.resources.limits.cpu=2000m

Next, the secured cluster component will need to be deployed to collect information on from the Kubernetes nodes.

Set a meaningful cluster name for your secured cluster in the CLUSTER_NAME shell variable. The cluster will be identified by this name in the clusters list of the StackRox UI.

CLUSTER_NAME="my-secured-cluster"

Set the endpoint of Central the Secured Cluster Services should communicate to. If you're deploying stackrox-secured-cluster-services on the same cluster as stackrox-central-services, leave it as shown, otherwise change the value to the endpoint through which Central is accessible.

CENTRAL_ENDPOINT="central.stackrox.svc:443"

Generate an init bundle containing initialization secrets. The init bundle will be saved in stackrox-init-bundle.yaml, and you will use it to provision secured clusters as shown below.

echo "$ROX_ADMIN_PASSWORD" | \
kubectl -n stackrox exec -i deploy/central -- bash -c 'ROX_ADMIN_PASSWORD=$(cat) roxctl --insecure-skip-tls-verify \
  central init-bundles generate stackrox-init-bundle --output -' > stackrox-init-bundle.yaml

Then install stackrox-secured-cluster-services (with the init bundle you just generated).

To perform the installation, choose one of the following commands depending on your cluster size.

If you're installing in a reasonably sized cluster, use the default installation command:

helm upgrade --install -n stackrox --create-namespace stackrox-secured-cluster-services \
  stackrox/stackrox-secured-cluster-services \
  -f stackrox-init-bundle.yaml \
  --set clusterName="$CLUSTER_NAME" \
  --set centralEndpoint="$CENTRAL_ENDPOINT"

If you're installing in a single node cluster, or the default installation results in pods stuck pending due to lack of resources, use the following command instead to reduce stackrox-secured-cluster-services resource requirements. Keep in mind that these reduced resource settings are not suited for a production setup.

helm upgrade --install -n stackrox --create-namespace stackrox-secured-cluster-services \
  stackrox/stackrox-secured-cluster-services \
  -f stackrox-init-bundle.yaml \
  --set clusterName="$CLUSTER_NAME" \
  --set centralEndpoint="$CENTRAL_ENDPOINT" \
  --set sensor.resources.requests.memory=500Mi \
  --set sensor.resources.requests.cpu=500m \
  --set sensor.resources.limits.memory=500Mi \
  --set sensor.resources.limits.cpu=500m

To further customize your Helm installation consult these documents:

• https://docs.openshift.com/acs/installing/installing_other/install-central-other.html#install-using-helm-customizations-other
• https://docs.openshift.com/acs/installing/installing_other/install-secured-cluster-other.html#configure-secured-cluster-services-helm-chart-customizations-other

Follow the guide below to quickly deploy a specific version of StackRox to your Kubernetes cluster in the stackrox namespace. If you want to install a specific version, make sure to define/set it in MAIN_IMAGE_TAG, otherwise it will install the latest nightly build.

Run the following in your working directory of choice:

git clone [email protected]:stackrox/stackrox.git
cd stackrox
MAIN_IMAGE_TAG=VERSION_TO_USE ./deploy/deploy.sh

After a few minutes, all resources should be deployed, and the command launches an interactive shell after printing connection instructions.

Before deploying on OpenShift, ensure that you have the oc - OpenShift Command Line installed.

Follow the guide below to quickly deploy a specific version of StackRox to your OpenShift cluster in the stackrox namespace. Make sure to add the most recent tag to the MAIN_IMAGE_TAG variable.

Run the following in your working directory of choice:

git clone [email protected]:stackrox/stackrox.git
cd stackrox
MAIN_IMAGE_TAG=VERSION_TO_USE ./deploy/deploy.sh

After a few minutes, all resources should be deployed, and the command launches an interactive shell after printing connection instructions.

Run the following in your working directory of choice:

git clone [email protected]:stackrox/stackrox.git
cd stackrox
MAIN_IMAGE_TAG=latest ./deploy/deploy-local.sh

After a few minutes, all resources should be deployed, and the command launches an interactive shell after printing connection instructions.

After the deployment has completed, the deployment tool (roxie) either exposes central (for on-cloud clusters) or creates a port-forward (for local deployments), for example:

02:24 ✓ Central is ready at: 34.70.21.23:443
[...]
04:07 ⏳ Waiting for Central to be ready at 34.70.21.23:443 (timeout: 5m0s)
04:07 ✓ Central is ready and responding!
[...]
[roxie] Central UI: https://34.70.21.23:443

or

02:20 ✓ Port-forward active at https://127.0.0.1:34693
[...]
02:42 ⏳ Waiting for Central to be ready at 127.0.0.1:34693 (timeout: 5m0s)
02:42 ✓ Central is ready and responding!

Then go to that address in your web browser.

• Username = The default user is admin
• Password = The password is in $ROX_ADMIN_PASSWORD after installation.

• Make
• Go
• Various Go linters that can be installed using make reinstall-dev-tools.
• UI build tooling as specified in ui/README.md.
• Docker
  • Note: Docker Desktop now requires a paid subscription for larger, enterprise companies.
  • Some StackRox devs recommend Colima
• Xcode command line tools (macOS only)
• Bats is used to run certain shell tests. You can obtain it with brew install bats or npm install -g bats.
• oc OpenShift cli tool
• shellcheck for shell scripts linting.

Xcode - macOS Only

Usually you would have these already installed by brew. However, if you get an error when building the golang x/tools, try first making sure the EULA is agreed by:

1. starting Xcode
2. building a new blank app project
3. starting the blank project app in the emulator
4. close both the emulator and the Xcode, then
5. run the following commands:

xcode-select --install
sudo xcode-select --switch /Library/Developer/CommandLineTools # Enable command line tools
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

For more info, see nodejs/node-gyp#569

To sweeten your experience, install the workflow scripts beforehand.

$ cd $GOPATH/src/github.com/stackrox/stackrox
$ make install-dev-tools
$ make image

Now, you need to bring up a Kubernetes cluster yourself before proceeding. Development can either happen in GCP or locally with Docker Desktop, Colima, minikube.

Note: Docker Desktop and Colima are more suited for macOS development, because the cluster will have access to images built with make image locally without additional configuration. Also, Collector has better support for these than minikube where drivers may not be available.

# To keep the StackRox Central's Postgres DB state between database upgrades and restarts, set:
$ export STORAGE=pvc

# To save time on rebuilds by skipping UI builds, set:
$ export SKIP_UI_BUILD=1

# To save time on rebuilds by skipping CLI builds, set:
$ export SKIP_CLI_BUILD=1

# When you deploy locally make sure your kube context points to the desired kubernetes cluster,
# for example Docker Desktop.
# To check the current context you can call a workflow script:
$ roxkubectx

# To deploy locally, call:
$ ./deploy/deploy-local.sh

# Now you can access StackRox dashboard at https://localhost:8000
# or simply call another workflow script:
$ logmein

See Installation via Scripts for further reading. To read more about the environment variables, consult deploy/README.md.

The workflow repository contains some helper scripts which support our development workflow. Explore more commands with roxhelp --list-all.

# Change directory to rox root
$ cdrox

# Handy curl shortcut for your StackRox central instance
# Uses https://localhost:8000 by default or ROX_BASE_URL env variable
# Also uses the admin credentials from your last deployment via deploy.sh
$ roxcurl /v1/metadata

# Run quickstyle checks, faster than stackrox's "make style"
$ quickstyle

# The workflow repository includes some tools for supporting
# working with multiple inter-dependent branches.
# Examples:
$ smart-branch <branch-name>    # create new branch
    ... work on branch...
$ smart-rebase                  # rebase from parent branch
    ... continue working on branch...
$ smart-diff                    # check diff relative to parent branch
    ... git push, etc.

If you're using GoLand for development, the following can help improve the experience.

Make sure the Protocol Buffers plugin is installed. The plugin comes installed by default in GoLand. If it isn't, use Help | Find Action..., type Plugins and hit enter, then switch to Marketplace, type its name and install the plugin.

This plugin does not know where to look for .proto imports by default in GoLand therefore you need to explicitly configure paths for this plugin. See https://github.com/jvolkman/intellij-protobuf-editor#path-settings.

• Go to GoLand | Preferences | Languages & Frameworks | Protocol Buffers.
• Uncheck Configure automatically.
• Click on + button, navigate and select ./proto directory in the root of the repo.
• Optionally, also add $HOME/go/pkg/mod/github.com/gogo/[email protected] and $HOME/go/pkg/mod/github.com/gogo/[email protected]/.
• To verify: use menu Navigate | File... type any .proto file name, e.g. alert_service.proto, and check that all import strings are shown green, not red.

Go tests annotated with //go:build sql_integration require a PostgreSQL server listening on port 5432. Due to how authentication is set up in code, it is the easiest to start Postgres in a container like this:

$ docker run --rm --env POSTGRES_USER="$USER" --env POSTGRES_HOST_AUTH_METHOD=trust --publish 5432:5432 docker.io/library/postgres:15

With that running in the background, sql_integration tests can be triggered from IDE or command-line.

Kubernetes debugger setup

With GoLand, you can naturally use breakpoints and the debugger when running unit tests in IDE.

If you would like to debug local or even remote deployment, follow the procedure below.

1. Create debug build locally by exporting DEBUG_BUILD=yes:

   $ DEBUG_BUILD=yes make image

   Alternatively, debug build will also be created when the branch name contains -debug substring. This works locally with make image and in CI.
2. Deploy the image using instructions from this README file. Works both with deploy-local.sh and deploy.sh.
3. Start the debugger (and port forwarding) in the target pod using roxdebug command from workflow repo.

   # For Central
   $ roxdebug
   # For Sensor
   $ roxdebug deploy/sensor
   # See usage help
   $ roxdebug --help

4. Configure GoLand for remote debugging (should be done only once):
   1. Open Run | Edit Configurations …, click on the + icon to add new configuration, choose Go Remote template.
   2. Choose Host: localhost and Port: 40000. Give this configuration some name.
   3. Select On disconnect: Leave it running (this prevents GoLand forgetting breakpoints on reconnect).
5. Attach GoLand to debugging port: select Run | Debug… and choose configuration you've created. If all done right, you should see Connected message in the Debug | Debugger | Variables window at the lower part of the screen.
6. Set some code breakpoints, trigger corresponding actions and happy debugging!

See Debugging go code running in Kubernetes for more info.

docker run -i --rm quay.io/stackrox-io/main:<tag> central generate interactive > k8s.zip

This will run you through an installer and generate a k8s.zip file.

unzip k8s.zip -d k8s

bash k8s/central.sh

Now Central has been deployed. Use the UI to deploy Sensor.

Note: If using a host mount, you need to allow the container to access it by using sudo chcon -Rt svirt_sandbox_file_t <full volume path>

Take the image-setup.sh script from this repo and run it to do the pull/push to local OpenShift registry. This is a prerequisite for every new cluster.

bash image-setup.sh

docker run -i --rm quay.io/stackrox-io/main:<tag> central generate interactive > openshift.zip

This will run you through an installer and generate a openshift.zip file.

unzip openshift.zip -d openshift

bash openshift/central.sh

The following information has been gathered to help with the installation and operation of the open source StackRox project. These recommendations were developed for the Red Hat Advanced Cluster Security for Kubernetes product and have not been tested with the upstream StackRox project.

Recommended Kubernetes Distributions

The Kubernetes Platforms that StackRox has been deployed onto with minimal issues are listed below.

• Red Hat OpenShift Dedicated (OSD)
• Azure Red Hat OpenShift (ARO)
• Red Hat OpenShift Service on AWS (ROSA)
• Amazon Elastic Kubernetes Service (EKS)
• Google Kubernetes Engine (GKE)
• Microsoft Azure Kubernetes Service (AKS)

If you deploy into a Kubernetes distribution other than the ones listed above you may encounter issues.

Recommended Operating Systems

StackRox is known to work on the recent versions of the following operating systems.

• Ubuntu
• Debian
• Red Hat Enterprise Linux (RHEL)
• CentOS
• Fedora CoreOS
• Flatcar Container Linux
• Google COS
• Amazon Linux
• Garden Linux

Recommended Web Browsers

The following table lists the browsers that can view the StackRox web user interface.

• Google Chrome 88.0 (64-bit)
• Microsoft Internet Explorer Edge
  • Version 44 and later (Windows)
  • Version 81 (Official build) (64-bit)
• Safari on MacOS (Mojave) - Version 14.0
• Mozilla Firefox Version 82.0.2 (64-bit)