# rootcoz

> Understand failing CI runs, collaborate on fixes, and create follow-up issues faster.

---

Source: quickstart.md

# Quickstart

You want RootCoz running fast so you can move from failing CI output to a report you can review and act on. The quickest path is to start the bundled Docker stack, create an operator account, and submit one Jenkins, Prow, or JUnit XML analysis from the web UI.

## Prerequisites

- Docker with Docker Compose
- One AI credential for `claude`, `gemini`, or `cursor`
- For Jenkins: a job name, build number, and Jenkins access
- For Prow: a job name, build ID, and access to the relevant Prow/GCS location
- For JUnit XML: a `.xml` file or raw JUnit XML text

## Quick Example

```bash
cp .env.example .env
```

```dotenv
AI_PROVIDER=claude
AI_MODEL=your-model-name
ANTHROPIC_API_KEY=your-anthropic-api-key
DEFAULT_USER_ROLE=operator
REQUIRE_APPROVAL=false
```

```bash
docker compose up -d
curl http://localhost:800/health
```

1. Open `http://localhost:800`.
2. Click `Register`, enter a username, save the API key RootCoz shows once, then click `I've saved my key — Continue`.
3. Open `New Analysis`.
4. Choose `Upload File` or `Paste XML` for the fastest first run, or switch to `Jenkins Job` or `Prow Job`.
5. Click `Submit Analysis`.

XML submissions open the result directly. Jenkins and Prow submissions open a live status page first, then redirect to the report when analysis completes.

> **Note:** The Docker image already includes the supported AI CLIs. For a first run, you only need one working provider credential plus `AI_PROVIDER` and `AI_MODEL`.


> **Warning:** `DEFAULT_USER_ROLE=operator` and `REQUIRE_APPROVAL=false` are convenient for a local trial. For a shared deployment, keep approval enabled and manage roles deliberately. See [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.

## Step-by-Step

1. Prepare `.env`.

   Start from `.env.example`, then add one AI provider, model, and the two quickstart lines shown above.

   | If your first analysis is... | Add before startup | You can also enter it in `New Analysis` |
   | --- | --- | --- |
   | JUnit XML | nothing else | n/a |
   | Jenkins | `JENKINS_URL`, `JENKINS_USER`, `JENKINS_PASSWORD` | yes |
   | Prow | `PROW_URL`, `GCS_BUCKET` | yes |

   | AI provider | Credential variable |
   | --- | --- |
   | Claude | `ANTHROPIC_API_KEY` |
   | Gemini | `GEMINI_API_KEY` |
   | Cursor | `CURSOR_API_KEY` |

   > **Warning:** The bundled Compose file uses example Jenkins values when you do not override them. Replace those placeholders before you submit a Jenkins run, or type the correct values into the form for that specific submission.

2. Start RootCoz.

   ```bash
   docker compose up -d
   curl http://localhost:800/health
   ```

   The web UI and API are both served from `http://localhost:800`. If the health check succeeds, the service is up and ready.

3. Sign in with a user that can submit analyses.

   With the quickstart config above, click `Register`, choose a username, save the API key, and continue into the app. RootCoz creates an active `operator` session immediately after registration.

   > **Tip:** If you already have an operator or admin API key, use `Log in` instead of `Register`.


   > **Tip:** Leave `GitHub Token`, `Jira Email`, and `Jira Token` blank for your first run. Add them later when you are ready to create issues or link external trackers. See [Managing Your Account and Notifications](manage-account-and-notifications.html) for details.

4. Open `New Analysis` and choose the input mode that matches what you already have.

   | Choose in the UI | Required fields | Optional first-run fields | What opens after submit |
   | --- | --- | --- | --- |
   | `Upload File` | a `.xml` file | `AI Provider`, `AI Model`, tags | Result page |
   | `Paste XML` | JUnit XML content | `AI Provider`, `AI Model`, tags | Result page |
   | `Jenkins Job` | `Job Name`, `Build Number` | `Jenkins URL`, `Jenkins User`, `Jenkins Password / Token`, `Wait for build completion` | Status page, then result |
   | `Prow Job` | `Job Name`, numeric `Build ID` | `Prow URL`, `GCS Bucket`, `GCS Prefix` | Status page, then result |

   Leave `GCS Prefix` empty unless you want to override auto-detection. For Jenkins, `Wait for build completion` is enabled by default.

   > **Tip:** `Upload File` and `Paste XML` are the fastest first-run options because they do not depend on Jenkins or Prow connectivity.

5. Submit and review the first result.

   Click `Submit Analysis`. RootCoz keeps the job on the dashboard so you can reopen it later without resubmitting.

   See [Submitting Analyses](submit-analyses.html) for details. See [Reviewing and Classifying Failures](review-and-classify-failures.html) for the next workflow. See [Tracking Analysis Progress](track-analysis-progress.html) for the live status view.

## Advanced Usage

- If you want admin login on day one, set `ADMIN_KEY` before startup, then log in as `admin` with that key.
- If you want to keep approval enabled, set `REQUIRE_APPROVAL=true`, log in as `admin`, and approve or create an `operator` before submitting jobs. See [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.
- If you want self-registered users to submit analyses without admin role changes, keep `DEFAULT_USER_ROLE=operator` before you start the stack.
- If you want richer analysis on the first run, add a tests repository, extra repositories, peer review models, or Jira search settings from the form. See [Configuring Analysis Context](configure-analysis-context.html) for details.
- If you prefer terminal automation once the server is running, see [Automating Common Tasks with the CLI](automate-common-tasks-with-the-cli.html) and [CLI Command Reference](cli-reference.html).
- If you need a production-style installation instead of the local Docker stack, see [Deploying RootCoz](deploy-rootcoz.html) for details.

## Troubleshooting

- If `docker compose up -d` fails with `AI_PROVIDER is required` or `AI_MODEL is required`, add both values to `.env` and start again.
- If you can log in but do not see `New Analysis`, your account is not `operator` or `admin`. Set `DEFAULT_USER_ROLE=operator` for a local trial or ask an admin to change your role.
- If registration succeeds but RootCoz says your account is awaiting approval, either disable approval for the local quickstart with `REQUIRE_APPROVAL=false` or have an admin approve the account.
- If a Jenkins submission fails immediately, verify `JENKINS_URL`, `JENKINS_USER`, and `JENKINS_PASSWORD`, or enter them directly on the form for that run.
- If a Prow submission fails immediately, provide `Prow URL` and `GCS Bucket` in the form or set `PROW_URL` and `GCS_BUCKET` in `.env` before restarting.
- If XML submission finishes with no useful report, make sure you pasted or uploaded real JUnit XML, not console output or HTML. RootCoz only analyzes failures and errors from the XML.# Quickstart

You want RootCoz running fast so you can move from failing CI output to a report you can review and act on. The quickest path is to start the bundled Docker stack, create an operator account, and submit one Jenkins, Prow, or JUnit XML analysis from the web UI.

## Prerequisites

- Docker with Docker Compose
- One AI credential for `claude`, `gemini`, or `cursor`
- For Jenkins: a job name, build number, and Jenkins access
- For Prow: a job name, build ID, and access to the relevant Prow/GCS location
- For JUnit XML: a `.xml` file or raw JUnit XML text

## Quick Example

```bash
cp .env.example .env
```

```dotenv
AI_PROVIDER=claude
AI_MODEL=your-model-name
ANTHROPIC_API_KEY=your-anthropic-api-key
DEFAULT_USER_ROLE=operator
REQUIRE_APPROVAL=false
```

```bash
docker compose up -d
curl http://localhost:8000/health
```

1. Open `http://localhost:8000`.
2. Click `Register`, enter a username, save the API key RootCoz shows once, then click `I've saved my key — Continue`.
3. Open `New Analysis`.
4. Choose `Upload File` or `Paste XML` for the fastest first run, or switch to `Jenkins Job` or `Prow Job`.
5. Click `Submit Analysis`.

XML submissions open the result directly. Jenkins and Prow submissions open a live status page first, then redirect to the report when analysis completes.

> **Note:** The Docker image already includes the supported AI CLIs. For a first run, you only need one working provider credential plus `AI_PROVIDER` and `AI_MODEL`.


> **Warning:** `DEFAULT_USER_ROLE=operator` and `REQUIRE_APPROVAL=false` are convenient for a local trial. For a shared deployment, keep approval enabled and manage roles deliberately. See [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.

## Step-by-Step

1. Prepare `.env`.

   Start from `.env.example`, then add one AI provider, model, and the two quickstart lines shown above.

   | If your first analysis is... | Add before startup | You can also enter it in `New Analysis` |
   | --- | --- | --- |
   | JUnit XML | nothing else | n/a |
   | Jenkins | `JENKINS_URL`, `JENKINS_USER`, `JENKINS_PASSWORD` | yes |
   | Prow | `PROW_URL`, `GCS_BUCKET` | yes |

   | AI provider | Credential variable |
   | --- | --- |
   | Claude | `ANTHROPIC_API_KEY` |
   | Gemini | `GEMINI_API_KEY` |
   | Cursor | `CURSOR_API_KEY` |

   > **Warning:** The bundled Compose file uses example Jenkins values when you do not override them. Replace those placeholders before you submit a Jenkins run, or type the correct values into the form for that specific submission.

2. Start RootCoz.

   ```bash
   docker compose up -d
   curl http://localhost:8000/health
   ```

   The web UI and API are both served from `http://localhost:8000`. If the health check succeeds, the service is up and ready.

3. Sign in with a user that can submit analyses.

   With the quickstart config above, click `Register`, choose a username, save the API key, and continue into the app. RootCoz creates an active `operator` session immediately after registration.

   > **Tip:** If you already have an operator or admin API key, use `Log in` instead of `Register`.


   > **Tip:** Leave `GitHub Token`, `Jira Email`, and `Jira Token` blank for your first run. Add them later when you are ready to create issues or link external trackers. See [Managing Your Account and Notifications](manage-account-and-notifications.html) for details.

4. Open `New Analysis` and choose the input mode that matches what you already have.

   | Choose in the UI | Required fields | Optional first-run fields | What opens after submit |
   | --- | --- | --- | --- |
   | `Upload File` | a `.xml` file | `AI Provider`, `AI Model`, tags | Result page |
   | `Paste XML` | JUnit XML content | `AI Provider`, `AI Model`, tags | Result page |
   | `Jenkins Job` | `Job Name`, `Build Number` | `Jenkins URL`, `Jenkins User`, `Jenkins Password / Token`, `Wait for build completion` | Status page, then result |
   | `Prow Job` | `Job Name`, numeric `Build ID` | `Prow URL`, `GCS Bucket`, `GCS Prefix` | Status page, then result |

   Leave `GCS Prefix` empty unless you want to override auto-detection. For Jenkins, `Wait for build completion` is enabled by default.

   > **Tip:** `Upload File` and `Paste XML` are the fastest first-run options because they do not depend on Jenkins or Prow connectivity.

5. Submit and review the first result.

   Click `Submit Analysis`. RootCoz keeps the job on the dashboard so you can reopen it later without resubmitting.

   See [Submitting Analyses](submit-analyses.html) for details. See [Reviewing and Classifying Failures](review-and-classify-failures.html) for the next workflow. See [Tracking Analysis Progress](track-analysis-progress.html) for the live status view.

## Advanced Usage

- If you want admin login on day one, set `ADMIN_KEY` before startup, then log in as `admin` with that key.
- If you want to keep approval enabled, set `REQUIRE_APPROVAL=true`, log in as `admin`, and approve or create an `operator` before submitting jobs. See [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.
- If you want self-registered users to submit analyses without admin role changes, keep `DEFAULT_USER_ROLE=operator` before you start the stack.
- If you want richer analysis on the first run, add a tests repository, extra repositories, peer review models, or Jira search settings from the form. See [Configuring Analysis Context](configure-analysis-context.html) for details.
- If you prefer terminal automation once the server is running, see [Automating Common Tasks with the CLI](automate-common-tasks-with-the-cli.html) and [CLI Command Reference](cli-reference.html).
- If you need a production-style installation instead of the local Docker stack, see [Deploying RootCoz](deploy-rootcoz.html) for details.

## Troubleshooting

- If `docker compose up -d` fails with `AI_PROVIDER is required` or `AI_MODEL is required`, add both values to `.env` and start again.
- If you can log in but do not see `New Analysis`, your account is not `operator` or `admin`. Set `DEFAULT_USER_ROLE=operator` for a local trial or ask an admin to change your role.
- If registration succeeds but RootCoz says your account is awaiting approval, either disable approval for the local quickstart with `REQUIRE_APPROVAL=false` or have an admin approve the account.
- If a Jenkins submission fails immediately, verify `JENKINS_URL`, `JENKINS_USER`, and `JENKINS_PASSWORD`, or enter them directly on the form for that run.
- If a Prow submission fails immediately, provide `Prow URL` and `GCS Bucket` in the form or set `PROW_URL` and `GCS_BUCKET` in `.env` before restarting.
- If XML submission finishes with no useful report, make sure you pasted or uploaded real JUnit XML, not console output or HTML. RootCoz only analyzes failures and errors from the XML.

## Related Pages

- [Deploying RootCoz](deploy-rootcoz.html)
- [Submitting Analyses](submit-analyses.html)
- [Configuring Analysis Context](configure-analysis-context.html)
- [Tracking Analysis Progress](track-analysis-progress.html)
- [Reviewing and Classifying Failures](review-and-classify-failures.html)

---

Source: review-and-classify-failures.md

# Reviewing and Classifying Failures

Use the report page when you need to decide whether RootCoz got a failure right and save the final answer your team should trust. This is where you compare the AI’s reasoning, finish human review, and correct the labels before the result drives follow-up work or downstream reporting.

## Prerequisites
- A completed analysis result.
- `reviewer`, `operator`, or `admin` access to mark failures reviewed or change their labels.
- `operator` or `admin` access if you plan to re-analyze a job or a single failure.
- If you want to use the CLI examples, a configured CLI profile.

See [Tracking Analysis Progress](track-analysis-progress.html) for details. See [Automating Common Tasks with the CLI](automate-common-tasks-with-the-cli.html) for details.

## Quick Example
```bash
rootcoz results review-status JOB_ID
rootcoz results set-reviewed JOB_ID --test "TEST_NAME" --reviewed
rootcoz override-classification JOB_ID --test "TEST_NAME" --classification "PRODUCT BUG"
rootcoz override-pattern JOB_ID --test "TEST_NAME" --pattern "REGRESSION"
```

Use this when you already know the job ID and test name and only need to confirm review state, mark the failure reviewed, and correct both labels. The rest of this page shows the same workflow in the web report, where you can inspect grouped failures and compare AI reasoning first.

## Step-by-Step
1. Open the result you want to review.

   Start from a completed job in the dashboard or history. If you need to find an older run or a recurring failure first, see [Exploring History and Reports](explore-history-and-reports.html) for details.

2. Triage the report header before you open individual failures.

   The header shows total failures, review progress, and the AI used for the run. If peer analysis was enabled, the `Peer Analysis` summary near the top also shows how many debates reached `Consensus` and how many did not.

3. Expand one failure card and confirm the scope.

   A card can represent one failing test or several tests with the same error. When a group contains more than one test, RootCoz shows `Affected Tests` and gives you a group-level `Review All` button.

> **Note:** Review state is tracked per test, but classification and pattern changes apply to the whole same-error group. Check `Affected Tests` before you change a grouped card.

4. Compare the current answer with the evidence.

   Start with `Analysis`, then read `Artifacts Evidence`. If the failure has been re-run before, open `Previous Analysis` to compare the earlier answer with the current one.

   If peer analysis was enabled, expand `Peer Analysis` on the failure card to inspect each round and see whether the models agreed. This is the fastest way to decide whether the current answer looks solid or needs correction.

5. Mark the review complete.

   Click `Review` on a single failure when you are satisfied with it. On grouped cards, use `Review All` when the whole group is ready, or review individual tests from the `Affected Tests` list if only part of the group is ready.

   The button changes to `Reviewed` and shows who reviewed it. Click it again if you need to reopen the failure.

6. Correct the labels when the default answer is wrong.

   Use the `Classify` row on the failure card to change the root cause and the failure pattern.

   | Change this | Choices | Use it when |
   | --- | --- | --- |
   | Root cause | `CODE ISSUE`, `PRODUCT BUG`, `INFRASTRUCTURE` | The AI blamed the wrong owner or system |
   | Pattern | `NEW`, `REGRESSION`, `FLAKY`, `INTERMITENT`, `KNOWN BUG`, `PERSISTENT` | The root cause is right, but the failure's behavior over time is wrong |

7. Repeat the same flow inside child jobs when the report contains nested failures.

   If the result includes a `Child Jobs` section, expand the relevant job and review it the same way. Review and classification controls stay scoped to that child job instead of the top-level failure list.

8. Finish the job after everything is reviewed.

   When every failure in the result is marked reviewed and Report Portal is available, RootCoz prompts you to update Report Portal. If you need to create or link follow-up issues after the review is final, see [Creating Follow-Up Issues and Pushing Results](create-follow-up-issues-and-push-results.html) for details.

## Advanced Usage
Use re-analysis when you want a better answer, not just a different badge. `Re-Analyze` in the page header creates a new result for the whole job, while `Re-analyze` on a failure card updates only that failure in place and keeps the earlier answer under `Previous Analysis`.

If peer analysis showed disagreement, or if the explanation is thin, re-run with different AI settings instead of stacking manual overrides. You can change the AI provider and model, peer analysis settings, tests repo, additional repositories, Jira search, artifact collection, and raw prompt. See [Configuring Analysis Context](configure-analysis-context.html) for details.

For child-job failures, add child scope in the CLI:

```bash
rootcoz results set-reviewed JOB_ID --test "TEST_NAME" --reviewed --child-job "CHILD_JOB" --child-build 12345
rootcoz override-pattern JOB_ID --test "TEST_NAME" --pattern "KNOWN_BUG" --child-job "CHILD_JOB" --child-build 12345
```

> **Tip:** The UI label `KNOWN BUG` uses the CLI value `KNOWN_BUG`.

Use `--not-reviewed` instead of `--reviewed` when you need to reopen a failure from the terminal. See [CLI Command Reference](cli-reference.html) for details.

## Troubleshooting
- `I can open the report but I can't change anything.`  
  You likely have viewer access. Review and classification actions require reviewer access, and re-analysis requires operator or admin access.

- `My change affected several tests.`  
  That card represents a same-error group. RootCoz applies classification and pattern changes across the whole group, so confirm the `Affected Tests` list before you save.

- `The label changed, but the explanation still needs work.`  
  Overrides update the labels immediately, but they do not replace the full AI narrative. Use `Re-analyze` if you want a fresh explanation that matches your corrected label.

- `A section disappeared after I changed the classification.`  
  That is expected. Switching to `CODE ISSUE` removes old bug-report content, switching to `PRODUCT BUG` removes old suggested-fix content, and switching to `INFRASTRUCTURE` removes both.

- `I never see the Report Portal prompt.`  
  The `All failures reviewed. Update Report Portal?` prompt only appears when every failure in the job is reviewed and Report Portal is enabled for the server.# Reviewing and Classifying Failures

Use the report page when you need to decide whether RootCoz got a failure right and save the final answer your team should trust. This is where you compare the AI’s reasoning, finish human review, and correct the labels before the result drives follow-up work or downstream reporting.

## Prerequisites
- A completed analysis result.
- `reviewer`, `operator`, or `admin` access to mark failures reviewed or change their labels.
- `operator` or `admin` access if you plan to re-analyze a job or a single failure.
- If you want to use the CLI examples, a configured CLI profile.

See [Tracking Analysis Progress](track-analysis-progress.html) for details. See [Automating Common Tasks with the CLI](automate-common-tasks-with-the-cli.html) for details.

## Quick Example
```bash
rootcoz results review-status JOB_ID
rootcoz results set-reviewed JOB_ID --test "TEST_NAME" --reviewed
rootcoz override-classification JOB_ID --test "TEST_NAME" --classification "PRODUCT BUG"
rootcoz override-pattern JOB_ID --test "TEST_NAME" --pattern "REGRESSION"
```

Use this when you already know the job ID and test name and only need to confirm review state, mark the failure reviewed, and correct both labels. The rest of this page shows the same workflow in the web report, where you can inspect grouped failures and compare AI reasoning first.

## Step-by-Step
1. Open the result you want to review.

   Start from a completed job in the dashboard or history. If you need to find an older run or a recurring failure first, see [Exploring History and Reports](explore-history-and-reports.html) for details.

2. Triage the report header before you open individual failures.

   The header shows total failures, review progress, and the AI used for the run. If peer analysis was enabled, the `Peer Analysis` summary near the top also shows how many debates reached `Consensus` and how many did not.

3. Expand one failure card and confirm the scope.

   A card can represent one failing test or several tests with the same error. When a group contains more than one test, RootCoz shows `Affected Tests` and gives you a group-level `Review All` button.

> **Note:** Review state is tracked per test, but classification and pattern changes apply to the whole same-error group. Check `Affected Tests` before you change a grouped card.

4. Compare the current answer with the evidence.

   Start with `Analysis`, then read `Artifacts Evidence`. If the failure has been re-run before, open `Previous Analysis` to compare the earlier answer with the current one.

   If peer analysis was enabled, expand `Peer Analysis` on the failure card to inspect each round and see whether the models agreed. This is the fastest way to decide whether the current answer looks solid or needs correction.

5. Mark the review complete.

   Click `Review` on a single failure when you are satisfied with it. On grouped cards, use `Review All` when the whole group is ready, or review individual tests from the `Affected Tests` list if only part of the group is ready.

   The button changes to `Reviewed` and shows who reviewed it. Click it again if you need to reopen the failure.

6. Correct the labels when the default answer is wrong.

   Use the `Classify` row on the failure card to change the root cause and the failure pattern.

   | Change this | Choices | Use it when |
   | --- | --- | --- |
   | Root cause | `CODE ISSUE`, `PRODUCT BUG`, `INFRASTRUCTURE` | The AI blamed the wrong owner or system |
   | Pattern | `NEW`, `REGRESSION`, `FLAKY`, `INTERMITTENT`, `KNOWN BUG`, `PERSISTENT` | The root cause is right, but the failure's behavior over time is wrong |

7. Repeat the same flow inside child jobs when the report contains nested failures.

   If the result includes a `Child Jobs` section, expand the relevant job and review it the same way. Review and classification controls stay scoped to that child job instead of the top-level failure list.

8. Finish the job after everything is reviewed.

   When every failure in the result is marked reviewed and Report Portal is available, RootCoz prompts you to update Report Portal. If you need to create or link follow-up issues after the review is final, see [Creating Follow-Up Issues and Pushing Results](create-follow-up-issues-and-push-results.html) for details.

## Advanced Usage
Use re-analysis when you want a better answer, not just a different badge. `Re-Analyze` in the page header creates a new result for the whole job, while `Re-analyze` on a failure card updates only that failure in place and keeps the earlier answer under `Previous Analysis`.

If peer analysis showed disagreement, or if the explanation is thin, re-run with different AI settings instead of stacking manual overrides. You can change the AI provider and model, peer analysis settings, tests repo, additional repositories, Jira search, artifact collection, and raw prompt. See [Configuring Analysis Context](configure-analysis-context.html) for details.

For child-job failures, add child scope in the CLI:

```bash
rootcoz results set-reviewed JOB_ID --test "TEST_NAME" --reviewed --child-job "CHILD_JOB" --child-build 12345
rootcoz override-pattern JOB_ID --test "TEST_NAME" --pattern "KNOWN_BUG" --child-job "CHILD_JOB" --child-build 12345
```

> **Tip:** The UI label `KNOWN BUG` uses the CLI value `KNOWN_BUG`.

Use `--not-reviewed` instead of `--reviewed` when you need to reopen a failure from the terminal. See [CLI Command Reference](cli-reference.html) for details.

## Troubleshooting
- `I can open the report but I can't change anything.`  
  You likely have viewer access. Review and classification actions require reviewer access, and re-analysis requires operator or admin access.

- `My change affected several tests.`  
  That card represents a same-error group. RootCoz applies classification and pattern changes across the whole group, so confirm the `Affected Tests` list before you save.

- `The label changed, but the explanation still needs work.`  
  Overrides update the labels immediately, but they do not replace the full AI narrative. Use `Re-analyze` if you want a fresh explanation that matches your corrected label.

- `A section disappeared after I changed the classification.`  
  That is expected. Switching to `CODE ISSUE` removes old bug-report content, switching to `PRODUCT BUG` removes old suggested-fix content, and switching to `INFRASTRUCTURE` removes both.

- `I never see the Report Portal prompt.`  
  The `All failures reviewed. Update Report Portal?` prompt only appears when every failure in the job is reviewed and Report Portal is enabled for the server.

## Related Pages

- [Tracking Analysis Progress](track-analysis-progress.html)
- [Collaborating on Results](collaborate-on-results.html)
- [Creating Follow-Up Issues and Pushing Results](create-follow-up-issues-and-push-results.html)
- [Exploring History and Reports](explore-history-and-reports.html)
- [Configuring Analysis Context](configure-analysis-context.html)

---

Source: explore-history-and-reports.md

# Exploring History and Reports

Use RootCoz's history views when you need to answer two practical questions quickly: has this failure happened before, and is it part of a broader trend? These screens help you move from one test failure to per-test history and then out to filtered team summaries.

## Prerequisites
- You are signed in to RootCoz.
- At least one analysis result already exists. See [Submitting Analyses](submit-analyses.html) for details.
- Your account has access to `Reports` if you want the team summary views.

## Quick Example
```bash
rootcoz history failures --search tests.test_auth.test_login
rootcoz history test "tests.test_auth.test_login"
rootcoz reports totals --team alpha --from 2025-01-01 --to 2025-06-01 --review-status reviewed
```

Use the first command to find matching failures, the second to inspect one test over time, and the third to compare reviewed work for one team in a date window.

## Step-by-Step
1. Start in the right place.

| If you want to... | Open | Best for |
| --- | --- | --- |
| Check one failing test or result | `History` | Repeats, classifications, and recent runs |
| Compare filtered job totals across teams or releases | `Reports` | Dates, metadata, labels, and review progress |
| See where reviewers changed RootCoz's answer | `Reports` | Classification override patterns |
| See what follow-up work already exists | `Reports` | GitHub and Jira issue summaries |

2. Search recurring failures in `History`.
Open `History`, use the search box to narrow the table by test name, then add a classification filter or date range if the list is still noisy. Click a row to open that result, or click the test name itself to open that test's dedicated history page.

3. Read the test history page.
Start with `Failure Rate`, `Total Runs`, `Failures`, and `Consecutive` to understand whether the test is stable, degrading, or repeatedly broken. Then read the classification badges, comments, `First seen`, and `Last seen`, and open any row in `Recent Runs` to jump back to a specific result.

4. Move to `Reports` for broader trends.
Choose `Total Failures` when you want summary counts, `Classification Overrides` when you want review changes, or `Issues Created` when you want follow-up visibility. Use the filters across the top to narrow by `Team`, `Tier`, `Version`, `Status`, `Review status`, date range, and label include/exclude chips.

> **Note:** If you leave the status filter empty, report summaries start with completed jobs only.

5. Read the report detail that matches your question.
In `Total Failures`, expand `Job Details` to compare jobs in the current slice. In `Classification Overrides`, expand a `from -> to` group to see which tests changed and who changed them; in `Issues Created`, open the external issue link or the linked result to inspect the original analysis.

When you find a specific result you want to confirm or correct, see [Reviewing and Classifying Failures](review-and-classify-failures.html) for details.

## Advanced Usage
Use the CLI when you want repeatable lookups or want to save filters in shell history.

```bash
rootcoz history failures --classification "INFRASTRUCTURE" --limit 50
rootcoz history test "tests.test_auth.test_login" --limit 50
rootcoz history stats "test-job"
rootcoz reports overrides --status completed --tags nightly,smoke
rootcoz reports issues --team alpha --review-status reviewed
```

> **Tip:** The `Reports` page keeps its active tab and filters in the URL, so you can refresh, bookmark, or share the same filtered view.

See [CLI Command Reference](cli-reference.html) for all flags, or see [API Endpoint Reference](api-reference.html) if you want to script the same lookups.

## Troubleshooting
- I do not see `Reports` in the sidebar.  
  Ask an administrator to grant report access, then reload the page.

- `History` is empty for a test I expect to find.  
  Remove the classification filter, widen the date range, or search with the full test name.

- A report looks smaller than expected.  
  Add the statuses you care about, then re-check your team, version, and label filters.

- There is no data to explore yet.  
  Run an analysis first. See [Submitting Analyses](submit-analyses.html) for details.

## Related Pages

- [Reviewing and Classifying Failures](review-and-classify-failures.html)
- [Creating Follow-Up Issues and Pushing Results](create-follow-up-issues-and-push-results.html)
- [Submitting Analyses](submit-analyses.html)
- [Use Server Chat for Cross-Job Analysis](use-server-chat-for-cross-job-analysis.html)
- [CLI Command Reference](cli-reference.html)

---

Source: use-server-chat-for-cross-job-analysis.md

# Use Server Chat for Cross-Job Analysis

Ask RootCoz questions across all jobs when you need trends, summaries, or reusable reports without opening runs one by one. This guide shows administrators how to start a server-wide chat, switch models for one question, follow replies, and keep or clear the session on their own terms.

## Prerequisites

- An admin account in RootCoz. The `Chat` page in the admin sidebar is admin-only.
- A default AI provider and model configured on the server, or a provider and model you can choose before sending a message. See [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.
- For CLI use, the `rootcoz` CLI installed and authenticated with an admin API key. See [Automating Common Tasks with the CLI](automate-common-tasks-with-the-cli.html) for details.

## Quick Example

```bash
export ROOTCOZ_SERVER="https://rootcoz.example.com"
read -rsp "Admin API key: " ROOTCOZ_API_KEY
export ROOTCOZ_API_KEY
echo

rootcoz auth whoami
rootcoz admin-chat send "Summarize the top failure trends from the last 7 days."
```

This confirms the CLI is using an admin identity, then asks a server-wide question and waits for the assistant reply.

> **Note:** Server Chat is separate from chat on a single analysis result. For job-specific chat and comments, see [Collaborating on Results](collaborate-on-results.html) for details.

## Step-by-Step

1. Open Server Chat or confirm CLI admin access.

   In the web UI, open `Chat` from the admin section of the sidebar. The empty state prompts you to `Ask about server analytics`, which is the right place for cross-job questions such as failure trends, user activity, or report summaries.

   In the CLI, run this first when you want to confirm which admin account the shell is using:

   ```bash
   rootcoz auth whoami
   ```

2. Choose how RootCoz should pick the model.

   RootCoz can use the server default AI settings or a one-off override for the next question.

   | If you want | Web UI | CLI |
   | --- | --- | --- |
   | Use the server default | Leave the provider and model already loaded in the header. | Omit `--provider` and `--model`. |
   | Override for one question | Pick a different provider and model in the header before sending. | Add `--provider` and `--model` to `rootcoz admin-chat send`. |
   | Keep using the same override | Leave the header selection in place. | Repeat the same flags on the next `send` command. |

   If you need to change the shared defaults for everyone, see [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.

3. Ask a cross-job question and follow the reply.

   In the web UI, type your question and press `Enter` to send it. Use `Shift+Enter` when you want a newline instead. While RootCoz is working, the thread shows `Thinking...` and keeps the response in the same conversation.

   In the CLI, send the question directly:

   ```bash
   rootcoz admin-chat send "Show where humans overrode the AI most often this month."
   ```

   The CLI waits for the assistant reply when it can. If you want to come back later, or the response takes longer than expected, check the stored conversation:

   ```bash
   rootcoz admin-chat history --limit 20
   ```

   > **Tip:** Use the web UI when you want the clearest live experience. It shows the active reply immediately and gives you a `Stop` button while the assistant is still working.

4. Stop the current reply or start over.

   Use the web UI `Stop` button when a reply is still running and you want to cancel it. When you want a completely fresh conversation, click `New Session` in the web UI or clear the current chat from the CLI:

   ```bash
   rootcoz admin-chat clear
   ```

   `New Session` and `clear` both reset your current Server Chat history so the next question starts clean.

   > **Note:** Server Chat history and saved artifacts are scoped to the current admin account, not shared across all admins.


   > **Warning:** Starting a new session in the web UI or running `rootcoz admin-chat clear` in the CLI also removes saved report artifacts for your account.

5. Save or download HTML report artifacts.

   Use artifacts when you want a reusable HTML summary that can be downloaded later. The CLI can upload a local HTML file into the Server Chat artifact store and download it back by ID.

   ```bash
   rootcoz admin-chat save-artifact ./weekly-summary.html
   rootcoz admin-chat save-artifact ./weekly-summary.html --filename "failure-summary-2026-07-31.html"
   rootcoz admin-chat download-artifact <artifact-id> --output ./failure-summary.html
   ```

   `save-artifact` returns a download URL. `download-artifact` writes the file to the path you choose, and when you do not pass `--output`, RootCoz creates a local HTML filename automatically.

   In the web UI, when a Server Chat reply contains one of these artifact links, RootCoz renders it as a download button instead of a raw URL.

## Advanced Usage

Use one-off model overrides when you want to compare answers without changing the server default:

```bash
rootcoz admin-chat send \
  "Compare issue-creation trends for the last 30 days." \
  --provider claude \
  --model claude-opus-4-6
```

Use JSON history output when you want to hand the conversation to another script or save a machine-readable record:

```bash
rootcoz --json admin-chat history --limit 50
```

Use custom filenames when you are saving reports for teammates or recurring reviews:

```bash
rootcoz admin-chat save-artifact ./report.html --filename "platform-weekly-review"
```

If the filename does not end in `.html`, RootCoz adds the extension for you.

These prompt patterns work well in Server Chat because they match the built-in cross-job reporting tools:

| Goal | Example prompt |
| --- | --- |
| Failure trends | `Summarize the top failure patterns from the last 7 days.` |
| Review accuracy | `Show where reviewers changed the AI classification most often this month.` |
| Follow-up volume | `Which jobs created the most GitHub issues or Jira bugs this quarter?` |

For every available command and flag, see [CLI Command Reference](cli-reference.html) for details. For raw endpoints, see [API Endpoint Reference](api-reference.html) for details.

## Troubleshooting

- The `Send` button is disabled in the web UI: choose both an AI provider and a model, type a message, and wait for any current reply to finish.
- `rootcoz admin-chat send` fails with an admin error: verify the CLI is using an admin API key with `rootcoz auth whoami`.
- Server Chat says AI is not configured or the page never finishes initializing: configure the default AI provider and model in Server Settings. See [Managing Users and Server Settings](manage-users-and-server-settings.html) and [Configuration Reference](configuration-reference.html) for details.
- A saved artifact link returns `404`: you likely started a new session or ran `rootcoz admin-chat clear`, which removes saved artifacts for your account.
- The CLI did not show a final answer: check later with `rootcoz admin-chat history --limit 20`. If you need the raw endpoints instead, see [API Endpoint Reference](api-reference.html) for details.

## Related Pages

- [Exploring History and Reports](explore-history-and-reports.html)
- [Managing Users and Server Settings](manage-users-and-server-settings.html)
- [Collaborating on Results](collaborate-on-results.html)
- [CLI Command Reference](cli-reference.html)
- [API Endpoint Reference](api-reference.html)

---

Source: deploy-rootcoz.md

# Deploying RootCoz

> **Note:** The Helm chart bootstraps RootCoz itself. Configure Jenkins, Jira, GitHub, Report Portal, and other runtime settings in the UI after first login. See [Configuration Reference](configuration-reference.html) and [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.


> **Warning:** The Helm chart is single-replica and expects one persistent volume. Enable either `route` or `ingress`, not both.

## Start locally with Docker Compose

Bring up a local RootCoz on `http://localhost:800` with persistent data in `./data`.

```bash
cat > .env <<'EOF'
JENKINS_URL=https://jenkins.example.com
JENKINS_USER=ci-reader
JENKINS_PASSWORD=jenkins-api-token
JENKINS_SSL_VERIFY=true
AI_PROVIDER=gemini
AI_MODEL=gemini-2.5-pro
GEMINI_API_KEY=replace-with-real-gemini-key
LOG_LEVEL=INFO
DEBUG=false
EOF

docker compose up -d
curl http://localhost:800/health
```

This uses the repo’s `docker-compose.yaml`, builds the local image, and keeps the SQLite database in `./data`. Use it for laptops, demos, and single-user environments where `localhost` access is enough.

- After changing `.env`, reload with `docker compose up -d --force-recreate rootcoz`.
- Continue with [Quickstart](quickstart.html) once the health check returns `{"status":"ok"}`.

## Bootstrap a shared cluster interactively

Use the setup script to generate safe Helm values files outside the repo and install the chart in one pass.

```bash
mkdir -p "$HOME/.config/rootcoz/helm"

uv run python scripts/helm-setup.py \
  --release rootcoz \
  --namespace rootcoz \
  --output-dir "$HOME/.config/rootcoz/helm"
```

The script prompts for cluster type, hostname, AI provider, credentials, and the bootstrap admin key, then writes `values.generated.yaml` and `values.secrets.yaml` before running `helm upgrade --install`. Use this when you want the fastest first-time shared deployment without hand-editing values files.

- Add `--skip-helm` to write files only.
- Add `--dry-run` to pass `--dry-run` through to Helm.

## Install on OpenShift with a Route

Publish RootCoz on OpenShift with a stable route and keep sensitive values outside the git checkout.

```bash
NAMESPACE=rootcoz
VALUES_DIR="$HOME/.config/rootcoz/helm"
mkdir -p "$VALUES_DIR"

cat > "$VALUES_DIR/values.generated.yaml" <<'EOF'
route:
  enabled: true
  host: rootcoz.apps.example.com
ingress:
  enabled: false
ai:
  provider: gemini
  model: gemini-2.5-pro
EOF

cat > "$VALUES_DIR/values.secrets.yaml" <<'EOF'
ai:
  geminiApiKey: "replace-with-real-gemini-key"
admin:
  key: "rootcoz-admin-2026-demo-key-please-change"
encryptionKey: "7d7f4cef5a224778a3a1a5d8af4c12b62"
EOF

helm upgrade --install rootcoz ./chart \
  --namespace "$NAMESPACE" --create-namespace \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"

oc get route -n "$NAMESPACE"
```

This uses the chart’s default OpenShift-friendly path: a Route on top of the `rootcoz` service, persistent storage, and a bootstrap admin key you control from day one. Use it when you want a shared internal deployment with the smallest amount of cluster-specific tuning.

- Omit `route.host` or set it to `""` if you want OpenShift to generate the hostname.
- After the route exists, sign in as `admin` and continue with [Quickstart](quickstart.html).

## Install on Kubernetes with TLS Ingress

Run RootCoz behind a standard Kubernetes Ingress and a TLS secret so browser sessions stay on HTTPS.

```bash
NAMESPACE=rootcoz
VALUES_DIR="$HOME/.config/rootcoz/helm"
mkdir -p "$VALUES_DIR" /tmp/rootcoz-tls

kubectl create namespace "$NAMESPACE" --dry-run=client -o yaml | kubectl apply -f -

openssl req -x509 -nodes -newkey rsa:2048 \
  -keyout /tmp/rootcoz-tls/tls.key \
  -out /tmp/rootcoz-tls/tls.crt \
  -days 365 \
  -subj "/CN=rootcoz.example.com"

kubectl create secret tls rootcoz-tls \
  --cert=/tmp/rootcoz-tls/tls.crt \
  --key=/tmp/rootcoz-tls/tls.key \
  -n "$NAMESPACE" \
  --dry-run=client -o yaml | kubectl apply -f -

cat > "$VALUES_DIR/values.generated.yaml" <<'EOF'
route:
  enabled: false
ingress:
  enabled: true
  host: rootcoz.example.com
  className: nginx
  tls:
    enabled: true
    secretName: rootcoz-tls
ai:
  provider: gemini
  model: gemini-2.5-pro
EOF

cat > "$VALUES_DIR/values.secrets.yaml" <<'EOF'
ai:
  geminiApiKey: "replace-with-real-gemini-key"
admin:
  key: "rootcoz-admin-2026-demo-key-please-change"
encryptionKey: "7d7f4cef5a224778a3a1a5d8af4c12b62"
EOF

helm upgrade --install rootcoz ./chart \
  --namespace "$NAMESPACE" --create-namespace \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"
```

This recipe is for vanilla Kubernetes clusters where you want shared browser access and secure cookies from the start. The self-signed certificate keeps the recipe copy-pasteable; swap it for your normal cluster TLS secret or cert-manager output before exposing the service broadly.

- Replace `className: nginx` with your actual ingress class if needed.
- For production certificates, keep the same `secretName` and remove the `openssl` step.

## Run a private ClusterIP-only release and port-forward it

Use this when you want a shared in-cluster deployment without exposing RootCoz through a Route or Ingress yet.

```bash
NAMESPACE=rootcoz
VALUES_DIR="$HOME/.config/rootcoz/helm"
mkdir -p "$VALUES_DIR"

cat > "$VALUES_DIR/values.generated.yaml" <<'EOF'
route:
  enabled: false
ingress:
  enabled: false
ai:
  provider: gemini
  model: gemini-2.5-pro
EOF

cat > "$VALUES_DIR/values.secrets.yaml" <<'EOF'
ai:
  geminiApiKey: "replace-with-real-gemini-key"
admin:
  key: "rootcoz-admin-2026-demo-key-please-change"
encryptionKey: "7d7f4cef5a224778a3a1a5d8af4c12b62"
EOF

helm upgrade --install rootcoz ./chart \
  --namespace "$NAMESPACE" --create-namespace \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"

kubectl port-forward svc/rootcoz 800:800 -n "$NAMESPACE"
```

This keeps the service internal to the cluster and gives you temporary browser and API access on `http://localhost:800` through `kubectl port-forward`. Use it for admin-only testing, locked-down evaluation clusters, or the period before your ingress or route is approved.

- With no Route or TLS Ingress, the chart automatically falls back to non-secure cookies for this HTTP-only access pattern.
- When you are ready to publish it, switch to the Route or Ingress recipe instead of editing the Service directly.

## Upgrade and smoke-test a Helm release

Apply new values, wait for the rollout, and run the chart’s built-in health test after any deployment change.

```bash
VALUES_DIR="$HOME/.config/rootcoz/helm"

helm upgrade rootcoz ./chart -n rootcoz \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"

kubectl rollout status deployment/rootcoz -n rootcoz
helm test rootcoz -n rootcoz
```

This is the shortest safe path for normal Helm updates once your release is already running. The `helm test` pod curls `/health`, so you get a quick verification that the app is listening after the rollout finishes.

- If you changed external secrets out of band, follow with `kubectl rollout restart deployment/rootcoz -n rootcoz`.
- For first-login and first-analysis steps after the rollout, see [Quickstart](quickstart.html).# Deploying RootCoz

> **Note:** The Helm chart bootstraps RootCoz itself. Configure Jenkins, Jira, GitHub, Report Portal, and other runtime settings in the UI after first login. See [Configuration Reference](configuration-reference.html) and [Managing Users and Server Settings](manage-users-and-server-settings.html) for details.


> **Warning:** The Helm chart is single-replica and expects one persistent volume. Enable either `route` or `ingress`, not both.

## Start locally with Docker Compose

Bring up a local RootCoz on `http://localhost:8000` with persistent data in `./data`.

```bash
cat > .env <<'EOF'
JENKINS_URL=https://jenkins.example.com
JENKINS_USER=ci-reader
JENKINS_PASSWORD=jenkins-api-token
JENKINS_SSL_VERIFY=true
AI_PROVIDER=gemini
AI_MODEL=gemini-2.5-pro
GEMINI_API_KEY=replace-with-real-gemini-key
LOG_LEVEL=INFO
DEBUG=false
EOF

docker compose up -d
curl http://localhost:8000/health
```

This uses the repo’s `docker-compose.yaml`, builds the local image, and keeps the SQLite database in `./data`. Use it for laptops, demos, and single-user environments where `localhost` access is enough.

- After changing `.env`, reload with `docker compose up -d --force-recreate rootcoz`.
- Continue with [Quickstart](quickstart.html) once the health check returns `{"status":"ok"}`.

## Bootstrap a shared cluster interactively

Use the setup script to generate safe Helm values files outside the repo and install the chart in one pass.

```bash
mkdir -p "$HOME/.config/rootcoz/helm"

uv run python scripts/helm-setup.py \
  --release rootcoz \
  --namespace rootcoz \
  --output-dir "$HOME/.config/rootcoz/helm"
```

The script prompts for cluster type, hostname, AI provider, credentials, and the bootstrap admin key, then writes `values.generated.yaml` and `values.secrets.yaml` before running `helm upgrade --install`. Use this when you want the fastest first-time shared deployment without hand-editing values files.

- Add `--skip-helm` to write files only.
- Add `--dry-run` to pass `--dry-run` through to Helm.

## Install on OpenShift with a Route

Publish RootCoz on OpenShift with a stable route and keep sensitive values outside the git checkout.

```bash
NAMESPACE=rootcoz
VALUES_DIR="$HOME/.config/rootcoz/helm"
mkdir -p "$VALUES_DIR"

cat > "$VALUES_DIR/values.generated.yaml" <<'EOF'
route:
  enabled: true
  host: rootcoz.apps.example.com
ingress:
  enabled: false
ai:
  provider: gemini
  model: gemini-2.5-pro
EOF

cat > "$VALUES_DIR/values.secrets.yaml" <<'EOF'
ai:
  geminiApiKey: "replace-with-real-gemini-key"
admin:
  key: "rootcoz-admin-2026-demo-key-please-change"
encryptionKey: "7d7f4cef5a224778a3a1a5d8af4c12b62"
EOF

helm upgrade --install rootcoz ./chart \
  --namespace "$NAMESPACE" --create-namespace \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"

oc get route -n "$NAMESPACE"
```

This uses the chart’s default OpenShift-friendly path: a Route on top of the `rootcoz` service, persistent storage, and a bootstrap admin key you control from day one. Use it when you want a shared internal deployment with the smallest amount of cluster-specific tuning.

- Omit `route.host` or set it to `""` if you want OpenShift to generate the hostname.
- After the route exists, sign in as `admin` and continue with [Quickstart](quickstart.html).

## Install on Kubernetes with TLS Ingress

Run RootCoz behind a standard Kubernetes Ingress and a TLS secret so browser sessions stay on HTTPS.

```bash
NAMESPACE=rootcoz
VALUES_DIR="$HOME/.config/rootcoz/helm"
mkdir -p "$VALUES_DIR" /tmp/rootcoz-tls

kubectl create namespace "$NAMESPACE" --dry-run=client -o yaml | kubectl apply -f -

openssl req -x509 -nodes -newkey rsa:2048 \
  -keyout /tmp/rootcoz-tls/tls.key \
  -out /tmp/rootcoz-tls/tls.crt \
  -days 365 \
  -subj "/CN=rootcoz.example.com"

kubectl create secret tls rootcoz-tls \
  --cert=/tmp/rootcoz-tls/tls.crt \
  --key=/tmp/rootcoz-tls/tls.key \
  -n "$NAMESPACE" \
  --dry-run=client -o yaml | kubectl apply -f -

cat > "$VALUES_DIR/values.generated.yaml" <<'EOF'
route:
  enabled: false
ingress:
  enabled: true
  host: rootcoz.example.com
  className: nginx
  tls:
    enabled: true
    secretName: rootcoz-tls
ai:
  provider: gemini
  model: gemini-2.5-pro
EOF

cat > "$VALUES_DIR/values.secrets.yaml" <<'EOF'
ai:
  geminiApiKey: "replace-with-real-gemini-key"
admin:
  key: "rootcoz-admin-2026-demo-key-please-change"
encryptionKey: "7d7f4cef5a224778a3a1a5d8af4c12b62"
EOF

helm upgrade --install rootcoz ./chart \
  --namespace "$NAMESPACE" --create-namespace \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"
```

This recipe is for vanilla Kubernetes clusters where you want shared browser access and secure cookies from the start. The self-signed certificate keeps the recipe copy-pasteable; swap it for your normal cluster TLS secret or cert-manager output before exposing the service broadly.

- Replace `className: nginx` with your actual ingress class if needed.
- For production certificates, keep the same `secretName` and remove the `openssl` step.

## Run a private ClusterIP-only release and port-forward it

Use this when you want a shared in-cluster deployment without exposing RootCoz through a Route or Ingress yet.

```bash
NAMESPACE=rootcoz
VALUES_DIR="$HOME/.config/rootcoz/helm"
mkdir -p "$VALUES_DIR"

cat > "$VALUES_DIR/values.generated.yaml" <<'EOF'
route:
  enabled: false
ingress:
  enabled: false
ai:
  provider: gemini
  model: gemini-2.5-pro
EOF

cat > "$VALUES_DIR/values.secrets.yaml" <<'EOF'
ai:
  geminiApiKey: "replace-with-real-gemini-key"
admin:
  key: "rootcoz-admin-2026-demo-key-please-change"
encryptionKey: "7d7f4cef5a224778a3a1a5d8af4c12b62"
EOF

helm upgrade --install rootcoz ./chart \
  --namespace "$NAMESPACE" --create-namespace \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"

kubectl port-forward svc/rootcoz 8000:8000 -n "$NAMESPACE"
```

This keeps the service internal to the cluster and gives you temporary browser and API access on `http://localhost:8000` through `kubectl port-forward`. Use it for admin-only testing, locked-down evaluation clusters, or the period before your ingress or route is approved.

- With no Route or TLS Ingress, the chart automatically falls back to non-secure cookies for this HTTP-only access pattern.
- When you are ready to publish it, switch to the Route or Ingress recipe instead of editing the Service directly.

## Upgrade and smoke-test a Helm release

Apply new values, wait for the rollout, and run the chart’s built-in health test after any deployment change.

```bash
VALUES_DIR="$HOME/.config/rootcoz/helm"

helm upgrade rootcoz ./chart -n rootcoz \
  -f "$VALUES_DIR/values.generated.yaml" \
  -f "$VALUES_DIR/values.secrets.yaml"

kubectl rollout status deployment/rootcoz -n rootcoz
helm test rootcoz -n rootcoz
```

This is the shortest safe path for normal Helm updates once your release is already running. The `helm test` pod curls `/health`, so you get a quick verification that the app is listening after the rollout finishes.

- If you changed external secrets out of band, follow with `kubectl rollout restart deployment/rootcoz -n rootcoz`.
- For first-login and first-analysis steps after the rollout, see [Quickstart](quickstart.html).

## Related Pages

- [Quickstart](quickstart.html)
- [Configuration Reference](configuration-reference.html)
- [Managing Users and Server Settings](manage-users-and-server-settings.html)
- [API Endpoint Reference](api-reference.html)
- [Submitting Analyses](submit-analyses.html)

---
