automatic import of python-crc-bonfire

1 files changed, 975 insertions, 0 deletions

diff --git a/python-crc-bonfire.spec b/python-crc-bonfire.spec
new file mode 100644
index 0000000..0ee5b44
--- /dev/null
+++ b/python-crc-bonfire.spec
@@ -0,0 +1,975 @@
+%global _empty_manifest_terminate_build 0
+Name:		python-crc-bonfire
+Version:	4.12.1
+Release:	1
+Summary:	A CLI tool used to deploy ephemeral environments for testing cloud.redhat.com applications
+License:	MIT
+URL:		https://www.github.com/RedHatInsights/bonfire
+Source0:	https://mirrors.nju.edu.cn/pypi/web/packages/d8/34/c839b0e43c6b11d900d339b22e7b56673140bffed7e7e9bb623a14f8a2e7/crc-bonfire-4.12.1.tar.gz
+BuildArch:	noarch
+
+Requires:	python3-cached-property
+Requires:	python3-chardet
+Requires:	python3-multidict
+Requires:	python3-click
+Requires:	python3-gql
+Requires:	python3-PyYAML
+Requires:	python3-requests
+Requires:	python3-sh
+Requires:	python3-wait-for
+Requires:	python3-tabulate
+Requires:	python3-dotenv
+Requires:	python3-ocviapy
+Requires:	python3-app-common-python
+Requires:	python3-junitparser
+Requires:	python3-importlib-metadata
+Requires:	python3-mock
+Requires:	python3-pytest
+Requires:	python3-pytest-mock
+
+%description
+# bonfire <!-- omit in toc -->
+
+A CLI tool used by Red Hat engineers to deploy console.redhat.com applications into kubernetes/OpenShift. This tool is mainly used for the purpose of creating ephemeral test environments.
+
+As an example, typing `bonfire deploy host-inventory` leads to the host-inventory application and all its dependencies being deployed and ready to run in under 4 minutes:
+
+![Demo gif](demo.gif)
+
+
+# Table of Contents <!-- omit in toc -->
+
+- [About](#about)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Deploying](#deploying)
+  - [Namespace Management](#namespace-management)
+  - [Namespace Context](#namespace-context)
+- [Examples for Common Use Cases](#examples-for-common-use-cases)
+- [Commonly Used CLI Options](#commonly-used-cli-options)
+  - [Deploying/Processing](#deployingprocessing)
+- [Interactions with Ephemeral Namespace Operator](#interactions-with-ephemeral-namespace-operator)
+- [Interactions with Clowder Operator](#interactions-with-clowder-operator)
+  - [ClowdEnvironments](#clowdenvironments)
+  - [Dependency Processing](#dependency-processing)
+- [Configuration Details](#configuration-details)
+  - [Using a local config](#using-a-local-config)
+  - [Local config examples](#local-config-examples)
+    - [Deploying local repo changes](#deploying-local-repo-changes)
+    - [Deploying changes changes in a remote git branch](#deploying-changes-changes-in-a-remote-git-branch)
+  - [Advanced](#advanced)
+    - [Running a local qontract-server](#running-a-local-qontract-server)
+
+# About
+
+`bonfire` interacts with a running instance of [qontract-server](https://github.com/app-sre/qontract-server) (the component that powers the [AppSRE team](https://github.com/app-sre/)'s internal `app-interface` graphql API) to obtain applications' OpenShift templates, process them, and deploy them. A local configuration file can be defined that allows you to override an application config if you wish.
+
+It also interacts with the [ephemeral namespace operator](https://github.com/RedHatInsights/ephemeral-namespace-operator) to manage the reservation of ephemeral namespaces for testing.
+
+It has special functionality related to the [Clowder operator](https://github.com/RedHatInsights/clowder) and [Frontend operator](https://github.com/RedHatInsights/frontend-operator/) such as auto-deploying ClowdApp dependencies.
+
+A wide range of CLI options allow you to customize exactly what combination of components get deployed into a namespace.
+
+> NOTE: for information related to app-interface configurations, see the internal [ConsoleDot Docs](https://consoledot.pages.redhat.com/)
+
+# Installation
+
+We'd recommend setting up a virtual environment for bonfire:
+
+```bash
+VENV_DIR=~/bonfire_venv
+mkdir -p $VENV_DIR
+python3 -m venv $VENV_DIR
+. $VENV_DIR/bin/activate
+pip install crc-bonfire
+```
+
+To prevent GitHub rate limiting issues when bonfire reaches out to GitHub APIs, [create a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) on your GitHub account which grants bonfire read access to your repos. Configure bonfire to use the token with:
+```
+echo 'GITHUB_TOKEN=<your api token>' >> ~/.config/bonfire/env
+```
+
+
+# Quick Start
+
+Start with `bonfire --help` to familiarize yourself with the basic command groups. Don't forget to use the `--help` flag on sub-commmands as well if you are curious to learn more about different CLI commands, options, and arguments.
+
+## Deploying
+
+The command you are most likely to use is `bonfire deploy`.
+
+If you are on the Red Hat VPN, `bonfire` will communicate with an internal instance of the App-SRE team's `qontract-server` API. You need to use `oc login` to log in to the ephemeral cluster.
+
+Once logged in, you should be able to type `bonfire deploy advisor`
+
+This will cause `bonfire` to do the following:
+1. reserve a namespace
+2. fetch the templates for all components in the 'advisor' app and process them. By default, bonfire will look up the template and commit hash using the 'main'/'master' branch of each component defined in the app. It will look up the git commit hash for this branch and automatically set the `IMAGE_TAG` parameter passed to the templates. 
+3. if ClowdApp resources are found, figure out which additional ClowdApps to fetch and process
+4. apply all the processed template resources into your reserved namespace
+5. wait for all the resources to reach a 'ready' state
+
+Run `bonfire namespace list --mine` and you will see your namespace.
+
+Switch into that namespace with `oc project <NAMESPACE>`
+
+Run `oc get clowdapp` in your namespace and you should see several ClowdApps have been deployed.
+
+If you want to to extend the time you have to work with your namespace, use `bonfire namespace extend <NAMESPACE>`
+
+When you are done working with your namespace, type `bonfire namespace release <NAMESPACE>` to instruct the ephemeral namespace operator to delete your reservation.
+
+The deploy command is an 'all-in-one' command that ties together 4 steps:
+1. `bonfire namespace reserve` to reserve a namespace
+2. `bonfire process` to fetch and process app templates
+3. `oc apply` to apply the processed app templates into the namespace
+4. `bonfire namespace wait-on-resources <NAMESPACE>` to wait on all resources in the namespace to reach 'ready' state
+
+## Namespace Management
+
+* Reserve a namespace with: `bonfire namespace reserve`
+    * By default, the duration is 1 hour. Increase it with `-d/--duration <time>` -- example time format: `48h`
+    * Different namespace pools are set up to provide different test environment configurations. Use `--pool <pool>` if you need to select a non-default pool. To get a list of valid pools, use `bonfire pool list`
+* Look up namespaces with: `bonfire namespace list`
+    * use `--mine` to see only ones reserved in your name
+* Extend your reservation with: `bonfire namespace extend <NAMESPACE> -d <time>` -- example time format: `48h`
+* Release your namespace reservation with: `bonfire namespace release <NAMESPACE>`
+
+## Namespace Context
+
+As of v4.12.0, `bonfire` now analyzes the namespace set in your oc/kubectl context. This means you can run commands such as `namespace extend`, `namespace release`, or `deploy` after you have switched into a namespace using `oc project` and you no longer need to specify the namespace on the CLI. `bonfire` will attempt to use your current namespace (it will run checks to ensure that you own it first and warn if you do not). In addition, when a new namespace is reserved using `bonfire deploy` or `bonfire namespace reserve`, bonfire will also go ahead and run `oc project <NAMESPACE>` for you to switch your context into that new namespace.
+
+The `deploy` command can be run using the `--reserve` flag if you wish to ignore the current namespace and force a namespace reservation to occur.
+
+The automatic 'oc' context switching into a newly reserved namespace is disabled when bonfire is operating in "bot" mode (i.e. when the env var `BONFIRE_BOT` is set to `true`). When using bonfire in an automated CI/CD environment such as Jenkins, you should run in bot mode to disable automatic context switching.
+
+# Examples for Common Use Cases
+
+In these examples, we will use the 'advisor' app which has a ClowdApp component named 'advisor-backend'
+
+* Deploy advisor-backend using a custom git branch:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=custom_branch
+```
+
+* Deploy advisor-backend using a custom git commit:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=df0d7a620b1ac02e59c5718eb22fe82b8a4cfd3d
+```
+
+* Use a certain branch to process the advisor-backend template, but set a different image tag on the container:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=some_branch --set-parameter advisor-backend/IMAGE_TAG=some_tag
+```
+
+* Deploy the production version of advisor and its dependencies:
+```
+bonfire deploy advisor --ref-env insights-production
+```
+
+* Deploy the production version of everything but use a dev branch for advisor-backend:
+```
+bonfire deploy advisor --ref-env insights-production --set-template-ref advisor-backend=dev_branch
+```
+
+* Adjust the 'REPLICAS' parameter value at deploy time:
+```
+bonfire deploy advisor --set-parameter advisor-backend/REPLICAS=3
+```
+
+* Override the tag for all occurences of a specific container image:
+```
+bonfire deploy advisor --set-image-tag quay.io/cloudservices/advisor-backend=my_tag
+```
+
+# Commonly Used CLI Options
+## Deploying/Processing
+
+* `--frontends=true` -- by default, bonfire will not deploy Frontend resources. Use this flag to enable the deployment of app frontends.
+* `--set-image-tag <image uri>=<tag>` -- use this to change the image tag of a container image that appears in your templates. This does a search/replace for all occurences of `<image uri>` and sets the tag to be `<tag>`
+* `--target-env` -- this changes which deploy target `bonfire` looks up to determine the parameters to apply when processing app templates. By default, the target env is set to `insights-ephemeral`
+* `--ref-env` -- this changes which deploy target `bonfire` looks up to determine the git ref to fetch for your app configuration. For example, using `--ref-env insights-stage` would cause bonfire to deploy the stage git ref of your app and `--ref-env insights-production` would cause bonfire to deploy the production git ref of your app. If a target matching the environment is not found, `bonfire` defaults back to deploying the 'main'/'master' branch.
+* `--set-template-ref <component>=<ref>` -- use this to change the git ref deployed for just a single component.
+* `--set-parameter <component>/<name>=<value>` -- use this to set a parameter value on a specific component's template.
+* `--optional-deps-method <hybrid|all|none>` -- change the way that bonfire processes ClowdApp optional dependencies (see "Dependency Processing" section)
+
+
+# Interactions with Ephemeral Namespace Operator
+
+`bonfire` creates/modifies `NamespaceReservation` resources on the cluster to reserve and release namespaces. The template for the object that bonfire applies into the cluster can be found [here](bonfire/resources/reservation-template.yaml)
+
+For more information about how the ephemeral namespace operator works, see its documentation [here](https://github.com/RedHatInsights/ephemeral-namespace-operator)
+
+# Interactions with Clowder Operator
+
+## ClowdEnvironments
+
+* `bonfire` expects a Clowder `ClowdEnvironment` resource to be created for a namespace before it can deploy into it. This `ClowdEnvironment` is already created by the ephemeral namespace operator.
+
+* When `bonfire deploy` is executed for a namespace, it will attempt to find the ClowdEnvironment associated with that namespace and set the `ENV_NAME` parameter accordingly for all templates it processes. All templates that define a `ClowdApp` resource should set the `environment` mapping in their spec using a parameter named `${ENV_NAME}`.
+
+## Dependency Processing
+
+In a ClowdApp definition, an app listed under `dependencies` is considered an app that MUST be present for your app to function, while an app listed under `optionalDependencies` is considered an app that might be absent, but your app could still come up and function without it.
+
+When bonfire processes templates, if it finds a ClowdApp, it will do the following:
+* if the ClowdApp has `dependencies`, it will try to look up the config for that ClowdApp in app-interface and also fetch its templates
+* if the ClowdApp has `optionalDependencies`, it will behave differently based on with optional dependencies method is selected:
+
+  * `hybrid` (default): if an app group was explicitly specified on the CLI (example: when running `bonfire deploy app-a` the app group 'app-a' is being explicitly specified) then the `optionalDependencies` will be deployed for it. For any ClowdApp `bonfire` comes across that is not a member of an explicitly specified app group, the `optionalDependencies` will NOT be deployed. As an example:
+    * `app-a` has `app-b-clowdapp` listed under `optionalDependencies`
+    * `app-b-clowdapp` has `app-c-clowdapp` listed under its `optionalDependencies`
+    * You will end up with all components of `app-a` and `app-b-clowdapp` in your namespace. `app-c-clowdapp` would NOT be deployed into the namespace.
+  * `all`: `bonfire` will deploy all `optionalDependencies` for all ClowdApps it encounters. It will recursively process dependencies. As an example:
+    * `app-a` has `app-b-clowdapp` listed under `optionalDependencies`
+    * `app-b-clowdapp` has `app-c-clowdapp` listed under its `optionalDependencies`
+    * You will end up with all components of `app-a`, `app-b-clowdapp`, AND `app-c-clowdapp` deployed into the namespace.
+  * `none`: `bonfire` will ignore the `optionalDependencies` on all ClowdApps that it encounters
+
+# Configuration Details 
+
+> NOTE: for information related to app-interface configurations, see the internal [ConsoleDot Docs](https://consoledot.pages.redhat.com/)
+
+When running `bonfire process`/`bonfire deploy`, by default the app-sre team's internal GraphQL API server is used. `bonfire` will query the GraphQL API and read the application's deploy configuration.
+
+*NOTE*: You need to be on the internal VPN in order to access the default GraphQL API URL.
+
+`bonfire` relies on a few key pieces of info to process app configs:
+
+1. The application name. This is typically the name of the listed in `app.yaml` in `app-interface`
+2. A 'target env' -- the name of the `app-interface` environment that bonfire looks at to determine the parameters to apply when processing app templates. An app's config will only be processed if it has a deploy target set up that is pointing to a namespace in this environment (default: "ephemeral")
+3. A 'ref env' -- the name of the `app-interface` environment that we want to use in order to figure out which git ref of the components to deploy and which `IMAGE_TAG` value to set. By default, none is set which causes bonfire to use the 'main'/'master' git branch for all components.
+4. Any template refs you wish to override (optional)
+5. Any image tags you wish to override (optional)
+6. Any parameters you wish to override (optional)
+
+By default, if app components use `ClowdApp` resources in their templates, then `bonfire` will dynamically load dependencies (see "Dependency Processing" section)
+
+## Using a local config
+
+`bonfire` ships with a [default config](bonfire/resources/default_config.yaml) that should be enough to get started for most internal Red Hat employees.
+
+By default, the configuration file will be stored in `~/.config/bonfire/config.yaml`.
+
+If you wish to override any app configurations, you can edit your local configuration file by typing `bonfire config edit`. If you define an app under the `apps` key of the config, it will take precedence over that app's configuration that was fetched from app-interface. Note that defining a local app configuration here will replace the configuration defined in app-interface for ALL components within that app.
+
+You can reset the config to default at any time using `bonfire config write-default`.
+
+## Local config examples
+
+### Deploying local repo changes
+
+If you wanted to test out some changes you're making to an app but you have not yet pushed these changes to a git repo, the local config could look similar to:
+
+```
+apps:
+- name: my_app
+  components:
+    - name: service
+      host: local
+      repo: ~/dev/projects/my-app
+      path: /clowdapp.yaml
+```
+
+- Where **host** set `local` indicates to look for the repo in a local directory
+- Where **repo** indicates the path to your git repo folder
+- Where **path** specifies the relative path to your ClowdApp template file in your git repo
+
+By default, `bonfire` will run `git rev-parse` to determine the current working commit hash in your repo folder, and this determines what IMAGE_TAG to set when the template is deployed. This means you would need to have a valid container image pushed for this commit hash. However, you can use `--set-image-tag` or `--set-parameter` to override the image you wish to use during the deployment.
+
+### Deploying changes changes in a remote git branch
+
+If you wanted to deploy changes to your app that you were working on which have been pushed to a PR/branch, the local config could look similar to:
+
+```
+apps:
+- name: my_app
+  components:
+    - name: service
+      host: github
+      repo: MyOrg/MyRepo
+      ref: my_branch
+      path: /clowdapp.yaml
+```
+
+- Where **host** set to `github` or `gitlab` indicates where the repo is hosted
+- Where **repo** indicates the `OrganizationName/RepoName`
+- Where **path** specifies the relative path to your ClowdApp template file in your git repo
+- Where **ref** specifies the branch or commit of the repo you want to deploy
+
+By default, bonfire will use the latest commit hash found at the specified git ref to determine what IMAGE_TAG pass on to the deployment templates.
+
+## Advanced
+### Running a local qontract-server
+
+bonfire is configured to point to the app-sre team's internal GraphQL API by default, but by using env variables you can point to your your own instance of `qontract-server`:
+
+```bash
+export QONTRACT_BASE_URL="https://localhost:4000/graphql"
+export QONTRACT_USERNAME=myUsername
+export QONTRACT_PASSWORD=myPassword
+```
+
+For testing/debug purposes, instead of committing changes directly to app-interface, you can run your own local copy of the app-interface API server.
+
+1. Clone https://github.com/app-sre/qontract-server
+2. Clone the internal `app-interface` repo
+
+In `qontract-server`, run:
+```
+npm install yarn
+yarn install
+yarn build
+make bundle APP_INTERFACE_PATH=/path/to/app-interface
+LOAD_METHOD=fs DATAFILES_FILE=bundle/bundle.json yarn run server
+```
+
+
+%package -n python3-crc-bonfire
+Summary:	A CLI tool used to deploy ephemeral environments for testing cloud.redhat.com applications
+Provides:	python-crc-bonfire
+BuildRequires:	python3-devel
+BuildRequires:	python3-setuptools
+BuildRequires:	python3-pip
+%description -n python3-crc-bonfire
+# bonfire <!-- omit in toc -->
+
+A CLI tool used by Red Hat engineers to deploy console.redhat.com applications into kubernetes/OpenShift. This tool is mainly used for the purpose of creating ephemeral test environments.
+
+As an example, typing `bonfire deploy host-inventory` leads to the host-inventory application and all its dependencies being deployed and ready to run in under 4 minutes:
+
+![Demo gif](demo.gif)
+
+
+# Table of Contents <!-- omit in toc -->
+
+- [About](#about)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Deploying](#deploying)
+  - [Namespace Management](#namespace-management)
+  - [Namespace Context](#namespace-context)
+- [Examples for Common Use Cases](#examples-for-common-use-cases)
+- [Commonly Used CLI Options](#commonly-used-cli-options)
+  - [Deploying/Processing](#deployingprocessing)
+- [Interactions with Ephemeral Namespace Operator](#interactions-with-ephemeral-namespace-operator)
+- [Interactions with Clowder Operator](#interactions-with-clowder-operator)
+  - [ClowdEnvironments](#clowdenvironments)
+  - [Dependency Processing](#dependency-processing)
+- [Configuration Details](#configuration-details)
+  - [Using a local config](#using-a-local-config)
+  - [Local config examples](#local-config-examples)
+    - [Deploying local repo changes](#deploying-local-repo-changes)
+    - [Deploying changes changes in a remote git branch](#deploying-changes-changes-in-a-remote-git-branch)
+  - [Advanced](#advanced)
+    - [Running a local qontract-server](#running-a-local-qontract-server)
+
+# About
+
+`bonfire` interacts with a running instance of [qontract-server](https://github.com/app-sre/qontract-server) (the component that powers the [AppSRE team](https://github.com/app-sre/)'s internal `app-interface` graphql API) to obtain applications' OpenShift templates, process them, and deploy them. A local configuration file can be defined that allows you to override an application config if you wish.
+
+It also interacts with the [ephemeral namespace operator](https://github.com/RedHatInsights/ephemeral-namespace-operator) to manage the reservation of ephemeral namespaces for testing.
+
+It has special functionality related to the [Clowder operator](https://github.com/RedHatInsights/clowder) and [Frontend operator](https://github.com/RedHatInsights/frontend-operator/) such as auto-deploying ClowdApp dependencies.
+
+A wide range of CLI options allow you to customize exactly what combination of components get deployed into a namespace.
+
+> NOTE: for information related to app-interface configurations, see the internal [ConsoleDot Docs](https://consoledot.pages.redhat.com/)
+
+# Installation
+
+We'd recommend setting up a virtual environment for bonfire:
+
+```bash
+VENV_DIR=~/bonfire_venv
+mkdir -p $VENV_DIR
+python3 -m venv $VENV_DIR
+. $VENV_DIR/bin/activate
+pip install crc-bonfire
+```
+
+To prevent GitHub rate limiting issues when bonfire reaches out to GitHub APIs, [create a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) on your GitHub account which grants bonfire read access to your repos. Configure bonfire to use the token with:
+```
+echo 'GITHUB_TOKEN=<your api token>' >> ~/.config/bonfire/env
+```
+
+
+# Quick Start
+
+Start with `bonfire --help` to familiarize yourself with the basic command groups. Don't forget to use the `--help` flag on sub-commmands as well if you are curious to learn more about different CLI commands, options, and arguments.
+
+## Deploying
+
+The command you are most likely to use is `bonfire deploy`.
+
+If you are on the Red Hat VPN, `bonfire` will communicate with an internal instance of the App-SRE team's `qontract-server` API. You need to use `oc login` to log in to the ephemeral cluster.
+
+Once logged in, you should be able to type `bonfire deploy advisor`
+
+This will cause `bonfire` to do the following:
+1. reserve a namespace
+2. fetch the templates for all components in the 'advisor' app and process them. By default, bonfire will look up the template and commit hash using the 'main'/'master' branch of each component defined in the app. It will look up the git commit hash for this branch and automatically set the `IMAGE_TAG` parameter passed to the templates. 
+3. if ClowdApp resources are found, figure out which additional ClowdApps to fetch and process
+4. apply all the processed template resources into your reserved namespace
+5. wait for all the resources to reach a 'ready' state
+
+Run `bonfire namespace list --mine` and you will see your namespace.
+
+Switch into that namespace with `oc project <NAMESPACE>`
+
+Run `oc get clowdapp` in your namespace and you should see several ClowdApps have been deployed.
+
+If you want to to extend the time you have to work with your namespace, use `bonfire namespace extend <NAMESPACE>`
+
+When you are done working with your namespace, type `bonfire namespace release <NAMESPACE>` to instruct the ephemeral namespace operator to delete your reservation.
+
+The deploy command is an 'all-in-one' command that ties together 4 steps:
+1. `bonfire namespace reserve` to reserve a namespace
+2. `bonfire process` to fetch and process app templates
+3. `oc apply` to apply the processed app templates into the namespace
+4. `bonfire namespace wait-on-resources <NAMESPACE>` to wait on all resources in the namespace to reach 'ready' state
+
+## Namespace Management
+
+* Reserve a namespace with: `bonfire namespace reserve`
+    * By default, the duration is 1 hour. Increase it with `-d/--duration <time>` -- example time format: `48h`
+    * Different namespace pools are set up to provide different test environment configurations. Use `--pool <pool>` if you need to select a non-default pool. To get a list of valid pools, use `bonfire pool list`
+* Look up namespaces with: `bonfire namespace list`
+    * use `--mine` to see only ones reserved in your name
+* Extend your reservation with: `bonfire namespace extend <NAMESPACE> -d <time>` -- example time format: `48h`
+* Release your namespace reservation with: `bonfire namespace release <NAMESPACE>`
+
+## Namespace Context
+
+As of v4.12.0, `bonfire` now analyzes the namespace set in your oc/kubectl context. This means you can run commands such as `namespace extend`, `namespace release`, or `deploy` after you have switched into a namespace using `oc project` and you no longer need to specify the namespace on the CLI. `bonfire` will attempt to use your current namespace (it will run checks to ensure that you own it first and warn if you do not). In addition, when a new namespace is reserved using `bonfire deploy` or `bonfire namespace reserve`, bonfire will also go ahead and run `oc project <NAMESPACE>` for you to switch your context into that new namespace.
+
+The `deploy` command can be run using the `--reserve` flag if you wish to ignore the current namespace and force a namespace reservation to occur.
+
+The automatic 'oc' context switching into a newly reserved namespace is disabled when bonfire is operating in "bot" mode (i.e. when the env var `BONFIRE_BOT` is set to `true`). When using bonfire in an automated CI/CD environment such as Jenkins, you should run in bot mode to disable automatic context switching.
+
+# Examples for Common Use Cases
+
+In these examples, we will use the 'advisor' app which has a ClowdApp component named 'advisor-backend'
+
+* Deploy advisor-backend using a custom git branch:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=custom_branch
+```
+
+* Deploy advisor-backend using a custom git commit:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=df0d7a620b1ac02e59c5718eb22fe82b8a4cfd3d
+```
+
+* Use a certain branch to process the advisor-backend template, but set a different image tag on the container:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=some_branch --set-parameter advisor-backend/IMAGE_TAG=some_tag
+```
+
+* Deploy the production version of advisor and its dependencies:
+```
+bonfire deploy advisor --ref-env insights-production
+```
+
+* Deploy the production version of everything but use a dev branch for advisor-backend:
+```
+bonfire deploy advisor --ref-env insights-production --set-template-ref advisor-backend=dev_branch
+```
+
+* Adjust the 'REPLICAS' parameter value at deploy time:
+```
+bonfire deploy advisor --set-parameter advisor-backend/REPLICAS=3
+```
+
+* Override the tag for all occurences of a specific container image:
+```
+bonfire deploy advisor --set-image-tag quay.io/cloudservices/advisor-backend=my_tag
+```
+
+# Commonly Used CLI Options
+## Deploying/Processing
+
+* `--frontends=true` -- by default, bonfire will not deploy Frontend resources. Use this flag to enable the deployment of app frontends.
+* `--set-image-tag <image uri>=<tag>` -- use this to change the image tag of a container image that appears in your templates. This does a search/replace for all occurences of `<image uri>` and sets the tag to be `<tag>`
+* `--target-env` -- this changes which deploy target `bonfire` looks up to determine the parameters to apply when processing app templates. By default, the target env is set to `insights-ephemeral`
+* `--ref-env` -- this changes which deploy target `bonfire` looks up to determine the git ref to fetch for your app configuration. For example, using `--ref-env insights-stage` would cause bonfire to deploy the stage git ref of your app and `--ref-env insights-production` would cause bonfire to deploy the production git ref of your app. If a target matching the environment is not found, `bonfire` defaults back to deploying the 'main'/'master' branch.
+* `--set-template-ref <component>=<ref>` -- use this to change the git ref deployed for just a single component.
+* `--set-parameter <component>/<name>=<value>` -- use this to set a parameter value on a specific component's template.
+* `--optional-deps-method <hybrid|all|none>` -- change the way that bonfire processes ClowdApp optional dependencies (see "Dependency Processing" section)
+
+
+# Interactions with Ephemeral Namespace Operator
+
+`bonfire` creates/modifies `NamespaceReservation` resources on the cluster to reserve and release namespaces. The template for the object that bonfire applies into the cluster can be found [here](bonfire/resources/reservation-template.yaml)
+
+For more information about how the ephemeral namespace operator works, see its documentation [here](https://github.com/RedHatInsights/ephemeral-namespace-operator)
+
+# Interactions with Clowder Operator
+
+## ClowdEnvironments
+
+* `bonfire` expects a Clowder `ClowdEnvironment` resource to be created for a namespace before it can deploy into it. This `ClowdEnvironment` is already created by the ephemeral namespace operator.
+
+* When `bonfire deploy` is executed for a namespace, it will attempt to find the ClowdEnvironment associated with that namespace and set the `ENV_NAME` parameter accordingly for all templates it processes. All templates that define a `ClowdApp` resource should set the `environment` mapping in their spec using a parameter named `${ENV_NAME}`.
+
+## Dependency Processing
+
+In a ClowdApp definition, an app listed under `dependencies` is considered an app that MUST be present for your app to function, while an app listed under `optionalDependencies` is considered an app that might be absent, but your app could still come up and function without it.
+
+When bonfire processes templates, if it finds a ClowdApp, it will do the following:
+* if the ClowdApp has `dependencies`, it will try to look up the config for that ClowdApp in app-interface and also fetch its templates
+* if the ClowdApp has `optionalDependencies`, it will behave differently based on with optional dependencies method is selected:
+
+  * `hybrid` (default): if an app group was explicitly specified on the CLI (example: when running `bonfire deploy app-a` the app group 'app-a' is being explicitly specified) then the `optionalDependencies` will be deployed for it. For any ClowdApp `bonfire` comes across that is not a member of an explicitly specified app group, the `optionalDependencies` will NOT be deployed. As an example:
+    * `app-a` has `app-b-clowdapp` listed under `optionalDependencies`
+    * `app-b-clowdapp` has `app-c-clowdapp` listed under its `optionalDependencies`
+    * You will end up with all components of `app-a` and `app-b-clowdapp` in your namespace. `app-c-clowdapp` would NOT be deployed into the namespace.
+  * `all`: `bonfire` will deploy all `optionalDependencies` for all ClowdApps it encounters. It will recursively process dependencies. As an example:
+    * `app-a` has `app-b-clowdapp` listed under `optionalDependencies`
+    * `app-b-clowdapp` has `app-c-clowdapp` listed under its `optionalDependencies`
+    * You will end up with all components of `app-a`, `app-b-clowdapp`, AND `app-c-clowdapp` deployed into the namespace.
+  * `none`: `bonfire` will ignore the `optionalDependencies` on all ClowdApps that it encounters
+
+# Configuration Details 
+
+> NOTE: for information related to app-interface configurations, see the internal [ConsoleDot Docs](https://consoledot.pages.redhat.com/)
+
+When running `bonfire process`/`bonfire deploy`, by default the app-sre team's internal GraphQL API server is used. `bonfire` will query the GraphQL API and read the application's deploy configuration.
+
+*NOTE*: You need to be on the internal VPN in order to access the default GraphQL API URL.
+
+`bonfire` relies on a few key pieces of info to process app configs:
+
+1. The application name. This is typically the name of the listed in `app.yaml` in `app-interface`
+2. A 'target env' -- the name of the `app-interface` environment that bonfire looks at to determine the parameters to apply when processing app templates. An app's config will only be processed if it has a deploy target set up that is pointing to a namespace in this environment (default: "ephemeral")
+3. A 'ref env' -- the name of the `app-interface` environment that we want to use in order to figure out which git ref of the components to deploy and which `IMAGE_TAG` value to set. By default, none is set which causes bonfire to use the 'main'/'master' git branch for all components.
+4. Any template refs you wish to override (optional)
+5. Any image tags you wish to override (optional)
+6. Any parameters you wish to override (optional)
+
+By default, if app components use `ClowdApp` resources in their templates, then `bonfire` will dynamically load dependencies (see "Dependency Processing" section)
+
+## Using a local config
+
+`bonfire` ships with a [default config](bonfire/resources/default_config.yaml) that should be enough to get started for most internal Red Hat employees.
+
+By default, the configuration file will be stored in `~/.config/bonfire/config.yaml`.
+
+If you wish to override any app configurations, you can edit your local configuration file by typing `bonfire config edit`. If you define an app under the `apps` key of the config, it will take precedence over that app's configuration that was fetched from app-interface. Note that defining a local app configuration here will replace the configuration defined in app-interface for ALL components within that app.
+
+You can reset the config to default at any time using `bonfire config write-default`.
+
+## Local config examples
+
+### Deploying local repo changes
+
+If you wanted to test out some changes you're making to an app but you have not yet pushed these changes to a git repo, the local config could look similar to:
+
+```
+apps:
+- name: my_app
+  components:
+    - name: service
+      host: local
+      repo: ~/dev/projects/my-app
+      path: /clowdapp.yaml
+```
+
+- Where **host** set `local` indicates to look for the repo in a local directory
+- Where **repo** indicates the path to your git repo folder
+- Where **path** specifies the relative path to your ClowdApp template file in your git repo
+
+By default, `bonfire` will run `git rev-parse` to determine the current working commit hash in your repo folder, and this determines what IMAGE_TAG to set when the template is deployed. This means you would need to have a valid container image pushed for this commit hash. However, you can use `--set-image-tag` or `--set-parameter` to override the image you wish to use during the deployment.
+
+### Deploying changes changes in a remote git branch
+
+If you wanted to deploy changes to your app that you were working on which have been pushed to a PR/branch, the local config could look similar to:
+
+```
+apps:
+- name: my_app
+  components:
+    - name: service
+      host: github
+      repo: MyOrg/MyRepo
+      ref: my_branch
+      path: /clowdapp.yaml
+```
+
+- Where **host** set to `github` or `gitlab` indicates where the repo is hosted
+- Where **repo** indicates the `OrganizationName/RepoName`
+- Where **path** specifies the relative path to your ClowdApp template file in your git repo
+- Where **ref** specifies the branch or commit of the repo you want to deploy
+
+By default, bonfire will use the latest commit hash found at the specified git ref to determine what IMAGE_TAG pass on to the deployment templates.
+
+## Advanced
+### Running a local qontract-server
+
+bonfire is configured to point to the app-sre team's internal GraphQL API by default, but by using env variables you can point to your your own instance of `qontract-server`:
+
+```bash
+export QONTRACT_BASE_URL="https://localhost:4000/graphql"
+export QONTRACT_USERNAME=myUsername
+export QONTRACT_PASSWORD=myPassword
+```
+
+For testing/debug purposes, instead of committing changes directly to app-interface, you can run your own local copy of the app-interface API server.
+
+1. Clone https://github.com/app-sre/qontract-server
+2. Clone the internal `app-interface` repo
+
+In `qontract-server`, run:
+```
+npm install yarn
+yarn install
+yarn build
+make bundle APP_INTERFACE_PATH=/path/to/app-interface
+LOAD_METHOD=fs DATAFILES_FILE=bundle/bundle.json yarn run server
+```
+
+
+%package help
+Summary:	Development documents and examples for crc-bonfire
+Provides:	python3-crc-bonfire-doc
+%description help
+# bonfire <!-- omit in toc -->
+
+A CLI tool used by Red Hat engineers to deploy console.redhat.com applications into kubernetes/OpenShift. This tool is mainly used for the purpose of creating ephemeral test environments.
+
+As an example, typing `bonfire deploy host-inventory` leads to the host-inventory application and all its dependencies being deployed and ready to run in under 4 minutes:
+
+![Demo gif](demo.gif)
+
+
+# Table of Contents <!-- omit in toc -->
+
+- [About](#about)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Deploying](#deploying)
+  - [Namespace Management](#namespace-management)
+  - [Namespace Context](#namespace-context)
+- [Examples for Common Use Cases](#examples-for-common-use-cases)
+- [Commonly Used CLI Options](#commonly-used-cli-options)
+  - [Deploying/Processing](#deployingprocessing)
+- [Interactions with Ephemeral Namespace Operator](#interactions-with-ephemeral-namespace-operator)
+- [Interactions with Clowder Operator](#interactions-with-clowder-operator)
+  - [ClowdEnvironments](#clowdenvironments)
+  - [Dependency Processing](#dependency-processing)
+- [Configuration Details](#configuration-details)
+  - [Using a local config](#using-a-local-config)
+  - [Local config examples](#local-config-examples)
+    - [Deploying local repo changes](#deploying-local-repo-changes)
+    - [Deploying changes changes in a remote git branch](#deploying-changes-changes-in-a-remote-git-branch)
+  - [Advanced](#advanced)
+    - [Running a local qontract-server](#running-a-local-qontract-server)
+
+# About
+
+`bonfire` interacts with a running instance of [qontract-server](https://github.com/app-sre/qontract-server) (the component that powers the [AppSRE team](https://github.com/app-sre/)'s internal `app-interface` graphql API) to obtain applications' OpenShift templates, process them, and deploy them. A local configuration file can be defined that allows you to override an application config if you wish.
+
+It also interacts with the [ephemeral namespace operator](https://github.com/RedHatInsights/ephemeral-namespace-operator) to manage the reservation of ephemeral namespaces for testing.
+
+It has special functionality related to the [Clowder operator](https://github.com/RedHatInsights/clowder) and [Frontend operator](https://github.com/RedHatInsights/frontend-operator/) such as auto-deploying ClowdApp dependencies.
+
+A wide range of CLI options allow you to customize exactly what combination of components get deployed into a namespace.
+
+> NOTE: for information related to app-interface configurations, see the internal [ConsoleDot Docs](https://consoledot.pages.redhat.com/)
+
+# Installation
+
+We'd recommend setting up a virtual environment for bonfire:
+
+```bash
+VENV_DIR=~/bonfire_venv
+mkdir -p $VENV_DIR
+python3 -m venv $VENV_DIR
+. $VENV_DIR/bin/activate
+pip install crc-bonfire
+```
+
+To prevent GitHub rate limiting issues when bonfire reaches out to GitHub APIs, [create a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) on your GitHub account which grants bonfire read access to your repos. Configure bonfire to use the token with:
+```
+echo 'GITHUB_TOKEN=<your api token>' >> ~/.config/bonfire/env
+```
+
+
+# Quick Start
+
+Start with `bonfire --help` to familiarize yourself with the basic command groups. Don't forget to use the `--help` flag on sub-commmands as well if you are curious to learn more about different CLI commands, options, and arguments.
+
+## Deploying
+
+The command you are most likely to use is `bonfire deploy`.
+
+If you are on the Red Hat VPN, `bonfire` will communicate with an internal instance of the App-SRE team's `qontract-server` API. You need to use `oc login` to log in to the ephemeral cluster.
+
+Once logged in, you should be able to type `bonfire deploy advisor`
+
+This will cause `bonfire` to do the following:
+1. reserve a namespace
+2. fetch the templates for all components in the 'advisor' app and process them. By default, bonfire will look up the template and commit hash using the 'main'/'master' branch of each component defined in the app. It will look up the git commit hash for this branch and automatically set the `IMAGE_TAG` parameter passed to the templates. 
+3. if ClowdApp resources are found, figure out which additional ClowdApps to fetch and process
+4. apply all the processed template resources into your reserved namespace
+5. wait for all the resources to reach a 'ready' state
+
+Run `bonfire namespace list --mine` and you will see your namespace.
+
+Switch into that namespace with `oc project <NAMESPACE>`
+
+Run `oc get clowdapp` in your namespace and you should see several ClowdApps have been deployed.
+
+If you want to to extend the time you have to work with your namespace, use `bonfire namespace extend <NAMESPACE>`
+
+When you are done working with your namespace, type `bonfire namespace release <NAMESPACE>` to instruct the ephemeral namespace operator to delete your reservation.
+
+The deploy command is an 'all-in-one' command that ties together 4 steps:
+1. `bonfire namespace reserve` to reserve a namespace
+2. `bonfire process` to fetch and process app templates
+3. `oc apply` to apply the processed app templates into the namespace
+4. `bonfire namespace wait-on-resources <NAMESPACE>` to wait on all resources in the namespace to reach 'ready' state
+
+## Namespace Management
+
+* Reserve a namespace with: `bonfire namespace reserve`
+    * By default, the duration is 1 hour. Increase it with `-d/--duration <time>` -- example time format: `48h`
+    * Different namespace pools are set up to provide different test environment configurations. Use `--pool <pool>` if you need to select a non-default pool. To get a list of valid pools, use `bonfire pool list`
+* Look up namespaces with: `bonfire namespace list`
+    * use `--mine` to see only ones reserved in your name
+* Extend your reservation with: `bonfire namespace extend <NAMESPACE> -d <time>` -- example time format: `48h`
+* Release your namespace reservation with: `bonfire namespace release <NAMESPACE>`
+
+## Namespace Context
+
+As of v4.12.0, `bonfire` now analyzes the namespace set in your oc/kubectl context. This means you can run commands such as `namespace extend`, `namespace release`, or `deploy` after you have switched into a namespace using `oc project` and you no longer need to specify the namespace on the CLI. `bonfire` will attempt to use your current namespace (it will run checks to ensure that you own it first and warn if you do not). In addition, when a new namespace is reserved using `bonfire deploy` or `bonfire namespace reserve`, bonfire will also go ahead and run `oc project <NAMESPACE>` for you to switch your context into that new namespace.
+
+The `deploy` command can be run using the `--reserve` flag if you wish to ignore the current namespace and force a namespace reservation to occur.
+
+The automatic 'oc' context switching into a newly reserved namespace is disabled when bonfire is operating in "bot" mode (i.e. when the env var `BONFIRE_BOT` is set to `true`). When using bonfire in an automated CI/CD environment such as Jenkins, you should run in bot mode to disable automatic context switching.
+
+# Examples for Common Use Cases
+
+In these examples, we will use the 'advisor' app which has a ClowdApp component named 'advisor-backend'
+
+* Deploy advisor-backend using a custom git branch:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=custom_branch
+```
+
+* Deploy advisor-backend using a custom git commit:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=df0d7a620b1ac02e59c5718eb22fe82b8a4cfd3d
+```
+
+* Use a certain branch to process the advisor-backend template, but set a different image tag on the container:
+```
+bonfire deploy advisor --set-template-ref advisor-backend=some_branch --set-parameter advisor-backend/IMAGE_TAG=some_tag
+```
+
+* Deploy the production version of advisor and its dependencies:
+```
+bonfire deploy advisor --ref-env insights-production
+```
+
+* Deploy the production version of everything but use a dev branch for advisor-backend:
+```
+bonfire deploy advisor --ref-env insights-production --set-template-ref advisor-backend=dev_branch
+```
+
+* Adjust the 'REPLICAS' parameter value at deploy time:
+```
+bonfire deploy advisor --set-parameter advisor-backend/REPLICAS=3
+```
+
+* Override the tag for all occurences of a specific container image:
+```
+bonfire deploy advisor --set-image-tag quay.io/cloudservices/advisor-backend=my_tag
+```
+
+# Commonly Used CLI Options
+## Deploying/Processing
+
+* `--frontends=true` -- by default, bonfire will not deploy Frontend resources. Use this flag to enable the deployment of app frontends.
+* `--set-image-tag <image uri>=<tag>` -- use this to change the image tag of a container image that appears in your templates. This does a search/replace for all occurences of `<image uri>` and sets the tag to be `<tag>`
+* `--target-env` -- this changes which deploy target `bonfire` looks up to determine the parameters to apply when processing app templates. By default, the target env is set to `insights-ephemeral`
+* `--ref-env` -- this changes which deploy target `bonfire` looks up to determine the git ref to fetch for your app configuration. For example, using `--ref-env insights-stage` would cause bonfire to deploy the stage git ref of your app and `--ref-env insights-production` would cause bonfire to deploy the production git ref of your app. If a target matching the environment is not found, `bonfire` defaults back to deploying the 'main'/'master' branch.
+* `--set-template-ref <component>=<ref>` -- use this to change the git ref deployed for just a single component.
+* `--set-parameter <component>/<name>=<value>` -- use this to set a parameter value on a specific component's template.
+* `--optional-deps-method <hybrid|all|none>` -- change the way that bonfire processes ClowdApp optional dependencies (see "Dependency Processing" section)
+
+
+# Interactions with Ephemeral Namespace Operator
+
+`bonfire` creates/modifies `NamespaceReservation` resources on the cluster to reserve and release namespaces. The template for the object that bonfire applies into the cluster can be found [here](bonfire/resources/reservation-template.yaml)
+
+For more information about how the ephemeral namespace operator works, see its documentation [here](https://github.com/RedHatInsights/ephemeral-namespace-operator)
+
+# Interactions with Clowder Operator
+
+## ClowdEnvironments
+
+* `bonfire` expects a Clowder `ClowdEnvironment` resource to be created for a namespace before it can deploy into it. This `ClowdEnvironment` is already created by the ephemeral namespace operator.
+
+* When `bonfire deploy` is executed for a namespace, it will attempt to find the ClowdEnvironment associated with that namespace and set the `ENV_NAME` parameter accordingly for all templates it processes. All templates that define a `ClowdApp` resource should set the `environment` mapping in their spec using a parameter named `${ENV_NAME}`.
+
+## Dependency Processing
+
+In a ClowdApp definition, an app listed under `dependencies` is considered an app that MUST be present for your app to function, while an app listed under `optionalDependencies` is considered an app that might be absent, but your app could still come up and function without it.
+
+When bonfire processes templates, if it finds a ClowdApp, it will do the following:
+* if the ClowdApp has `dependencies`, it will try to look up the config for that ClowdApp in app-interface and also fetch its templates
+* if the ClowdApp has `optionalDependencies`, it will behave differently based on with optional dependencies method is selected:
+
+  * `hybrid` (default): if an app group was explicitly specified on the CLI (example: when running `bonfire deploy app-a` the app group 'app-a' is being explicitly specified) then the `optionalDependencies` will be deployed for it. For any ClowdApp `bonfire` comes across that is not a member of an explicitly specified app group, the `optionalDependencies` will NOT be deployed. As an example:
+    * `app-a` has `app-b-clowdapp` listed under `optionalDependencies`
+    * `app-b-clowdapp` has `app-c-clowdapp` listed under its `optionalDependencies`
+    * You will end up with all components of `app-a` and `app-b-clowdapp` in your namespace. `app-c-clowdapp` would NOT be deployed into the namespace.
+  * `all`: `bonfire` will deploy all `optionalDependencies` for all ClowdApps it encounters. It will recursively process dependencies. As an example:
+    * `app-a` has `app-b-clowdapp` listed under `optionalDependencies`
+    * `app-b-clowdapp` has `app-c-clowdapp` listed under its `optionalDependencies`
+    * You will end up with all components of `app-a`, `app-b-clowdapp`, AND `app-c-clowdapp` deployed into the namespace.
+  * `none`: `bonfire` will ignore the `optionalDependencies` on all ClowdApps that it encounters
+
+# Configuration Details 
+
+> NOTE: for information related to app-interface configurations, see the internal [ConsoleDot Docs](https://consoledot.pages.redhat.com/)
+
+When running `bonfire process`/`bonfire deploy`, by default the app-sre team's internal GraphQL API server is used. `bonfire` will query the GraphQL API and read the application's deploy configuration.
+
+*NOTE*: You need to be on the internal VPN in order to access the default GraphQL API URL.
+
+`bonfire` relies on a few key pieces of info to process app configs:
+
+1. The application name. This is typically the name of the listed in `app.yaml` in `app-interface`
+2. A 'target env' -- the name of the `app-interface` environment that bonfire looks at to determine the parameters to apply when processing app templates. An app's config will only be processed if it has a deploy target set up that is pointing to a namespace in this environment (default: "ephemeral")
+3. A 'ref env' -- the name of the `app-interface` environment that we want to use in order to figure out which git ref of the components to deploy and which `IMAGE_TAG` value to set. By default, none is set which causes bonfire to use the 'main'/'master' git branch for all components.
+4. Any template refs you wish to override (optional)
+5. Any image tags you wish to override (optional)
+6. Any parameters you wish to override (optional)
+
+By default, if app components use `ClowdApp` resources in their templates, then `bonfire` will dynamically load dependencies (see "Dependency Processing" section)
+
+## Using a local config
+
+`bonfire` ships with a [default config](bonfire/resources/default_config.yaml) that should be enough to get started for most internal Red Hat employees.
+
+By default, the configuration file will be stored in `~/.config/bonfire/config.yaml`.
+
+If you wish to override any app configurations, you can edit your local configuration file by typing `bonfire config edit`. If you define an app under the `apps` key of the config, it will take precedence over that app's configuration that was fetched from app-interface. Note that defining a local app configuration here will replace the configuration defined in app-interface for ALL components within that app.
+
+You can reset the config to default at any time using `bonfire config write-default`.
+
+## Local config examples
+
+### Deploying local repo changes
+
+If you wanted to test out some changes you're making to an app but you have not yet pushed these changes to a git repo, the local config could look similar to:
+
+```
+apps:
+- name: my_app
+  components:
+    - name: service
+      host: local
+      repo: ~/dev/projects/my-app
+      path: /clowdapp.yaml
+```
+
+- Where **host** set `local` indicates to look for the repo in a local directory
+- Where **repo** indicates the path to your git repo folder
+- Where **path** specifies the relative path to your ClowdApp template file in your git repo
+
+By default, `bonfire` will run `git rev-parse` to determine the current working commit hash in your repo folder, and this determines what IMAGE_TAG to set when the template is deployed. This means you would need to have a valid container image pushed for this commit hash. However, you can use `--set-image-tag` or `--set-parameter` to override the image you wish to use during the deployment.
+
+### Deploying changes changes in a remote git branch
+
+If you wanted to deploy changes to your app that you were working on which have been pushed to a PR/branch, the local config could look similar to:
+
+```
+apps:
+- name: my_app
+  components:
+    - name: service
+      host: github
+      repo: MyOrg/MyRepo
+      ref: my_branch
+      path: /clowdapp.yaml
+```
+
+- Where **host** set to `github` or `gitlab` indicates where the repo is hosted
+- Where **repo** indicates the `OrganizationName/RepoName`
+- Where **path** specifies the relative path to your ClowdApp template file in your git repo
+- Where **ref** specifies the branch or commit of the repo you want to deploy
+
+By default, bonfire will use the latest commit hash found at the specified git ref to determine what IMAGE_TAG pass on to the deployment templates.
+
+## Advanced
+### Running a local qontract-server
+
+bonfire is configured to point to the app-sre team's internal GraphQL API by default, but by using env variables you can point to your your own instance of `qontract-server`:
+
+```bash
+export QONTRACT_BASE_URL="https://localhost:4000/graphql"
+export QONTRACT_USERNAME=myUsername
+export QONTRACT_PASSWORD=myPassword
+```
+
+For testing/debug purposes, instead of committing changes directly to app-interface, you can run your own local copy of the app-interface API server.
+
+1. Clone https://github.com/app-sre/qontract-server
+2. Clone the internal `app-interface` repo
+
+In `qontract-server`, run:
+```
+npm install yarn
+yarn install
+yarn build
+make bundle APP_INTERFACE_PATH=/path/to/app-interface
+LOAD_METHOD=fs DATAFILES_FILE=bundle/bundle.json yarn run server
+```
+
+
+%prep
+%autosetup -n crc-bonfire-4.12.1
+
+%build
+%py3_build
+
+%install
+%py3_install
+install -d -m755 %{buildroot}/%{_pkgdocdir}
+if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
+if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
+if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
+if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
+pushd %{buildroot}
+if [ -d usr/lib ]; then
+	find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+if [ -d usr/lib64 ]; then
+	find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+if [ -d usr/bin ]; then
+	find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+if [ -d usr/sbin ]; then
+	find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst
+fi
+touch doclist.lst
+if [ -d usr/share/man ]; then
+	find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst
+fi
+popd
+mv %{buildroot}/filelist.lst .
+mv %{buildroot}/doclist.lst .
+
+%files -n python3-crc-bonfire -f filelist.lst
+%dir %{python3_sitelib}/*
+
+%files help -f doclist.lst
+%{_docdir}/*
+
+%changelog
+* Wed Apr 12 2023 Python_Bot <Python_Bot@openeuler.org> - 4.12.1-1
+- Package Spec generated