docs: Correct update guide based on actual open_rica_report.py behavior

eurunuela · claude · eurunuela · commit 933833ff4d4b · 2026-03-03T09:45:30.000-07:00
The script already auto-downloads the latest Rica from GitHub on every
run. Update the docs and README to reflect the real workflow:
- Just running the script is enough to get the latest version
- --force-download bypasses the cache check
- TEDANA_RICA_PATH env var pins a local/custom build
- Falls back to cache automatically when offline

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -110,28 +110,26 @@ npx gulp
 
 ## Updating Rica Without Rerunning Tedana
 
-Tedana generates an `open_rica_report.py` script in its output directory that bundles a specific version of Rica. If a newer Rica release is available (with bug fixes or new features), you can update without rerunning tedana:
+Tedana generates an `open_rica_report.py` script in its output directory. This script **automatically downloads the latest Rica** from GitHub every time it runs — you usually don't need to do anything special:
 
-### Option A: Use Rica Online (Easiest)
-
-Visit **https://rica-fmri.netlify.app** — always up-to-date, no files to change.
+```bash
+python open_rica_report.py
+```
 
-### Option B: Replace the Local Files
+To force a fresh download regardless of the cached version:
 
-1. Download the latest `index.html` and `rica_server.py` from the [releases page](https://github.com/ME-ICA/rica/releases/latest)
+```bash
+python open_rica_report.py --force-download
+```
 
-2. Copy them into your tedana output folder:
-   ```bash
-   cp index.html rica_server.py /path/to/tedana/output/
-   ```
+To use a local or custom build, set the `TEDANA_RICA_PATH` environment variable to a directory containing `index.html` and `rica_server.py`:
 
-3. Run the updated server instead of `open_rica_report.py`:
-   ```bash
-   cd /path/to/tedana/output/
-   python rica_server.py
-   ```
+```bash
+export TEDANA_RICA_PATH=/path/to/rica/build
+python open_rica_report.py
+```
 
-`rica_server.py` is a drop-in replacement for `open_rica_report.py` — it serves the same data, just with the newer Rica version. See the [full guide](https://me-ica.github.io/rica/updating-rica/) for more details including bulk updates across multiple folders.
+See the [full guide](https://me-ica.github.io/rica/updating-rica/) for details on offline use, pinning versions, and building Rica from source.
 
 ## Required Files
 
diff --git a/docs/updating-rica.md b/docs/updating-rica.md
@@ -1,115 +1,114 @@
 # Updating Rica Without Rerunning Tedana
 
-When tedana runs, it generates an `open_rica_report.py` script in the output directory. This script bundles a specific version of Rica so you can view your results locally. However, Rica is updated independently from tedana — new releases bring bug fixes, new features, and improved visualizations.
+When tedana runs, it generates an `open_rica_report.py` script in the output directory. This script automatically downloads the latest Rica from GitHub every time it runs, so **you usually don't need to do anything special** — just run the script and it will self-update.
 
-This guide explains how to update the Rica version used to view your existing tedana output **without rerunning tedana**.
+This page explains how the update mechanism works and what to do in less common situations (offline use, pinning a specific version, or using a local build).
 
-## Why Update Rica Separately?
+## How `open_rica_report.py` Works
 
-Tedana analyses can take hours or days for large datasets. You should not need to rerun tedana just to get improvements to the visualization tool. Common reasons to update Rica independently:
+Each time you run `open_rica_report.py`, it:
 
-- A bug was fixed in the brain viewer or plots
-- A new feature was added (e.g., new keyboard shortcut, improved table)
-- The online version behaves differently from your local `open_rica_report.py`
-- You want to match the Rica version used by collaborators
+1. Queries the GitHub API for the latest Rica release
+2. Compares it against the version cached at `~/Library/Caches/tedana/rica/` (macOS) or the platform equivalent
+3. Downloads `index.html` and `rica_server.py` if a newer version is available
+4. Copies the files into a `rica/` subdirectory of your tedana output folder
+5. Starts a local HTTP server and opens Rica at `http://localhost:8000/rica/index.html`
 
-## The Simplest Option: Use Rica Online
+So to get the latest Rica, simply run:
 
-The online version at **[rica-fmri.netlify.app](https://rica-fmri.netlify.app)** is always up-to-date with the latest release. You can use it with any tedana output folder — no files to update.
-
-1. Visit [rica-fmri.netlify.app](https://rica-fmri.netlify.app)
-2. Click **Select Folder**
-3. Navigate to your tedana output directory and click **Upload**
-
-!!! tip
-    The online version is the easiest way to always have the latest Rica. Your data never leaves your machine — everything is processed in the browser.
+```bash
+python open_rica_report.py
+```
 
-## Updating the Local Files
+## Forcing a Re-download
 
-If you prefer to run Rica locally (e.g., for large datasets or offline use), you can replace the files that tedana placed in your output directory.
+If you suspect the cache is stale or want to guarantee a fresh download:
 
-### Step 1: Download the Latest Release
+```bash
+python open_rica_report.py --force-download
+```
 
-Go to the [Rica releases page](https://github.com/ME-ICA/rica/releases/latest) and download:
+This bypasses the version comparison and always downloads the latest release.
 
-- `index.html` — the self-contained Rica application
-- `rica_server.py` — the local server script
+## Offline / Air-Gapped Use
 
-### Step 2: Copy Files to Your Tedana Output Directory
+When there is no network access, the script falls back to the last cached version automatically. You will see a warning like:
 
-```bash
-cp index.html rica_server.py /path/to/tedana/output/
+```
+[Rica] Warning: Could not check for updates (...)
+[Rica] Using cached version v2.1.5
 ```
 
-### Step 3: Run the New Server
+No action is needed — Rica continues to work with the cached files.
 
-Instead of running `open_rica_report.py`, use `rica_server.py`:
+If you need to set up Rica on a machine that has never had network access, pre-populate the cache directory manually:
 
-```bash
-cd /path/to/tedana/output/
-python rica_server.py
-```
+| Platform | Cache Path |
+|----------|-----------|
+| macOS | `~/Library/Caches/tedana/rica/` |
+| Linux | `~/.cache/tedana/rica/` |
+| Windows | `%LOCALAPPDATA%\tedana\rica\` |
 
-Rica opens automatically in your browser with all your existing tedana data.
+Place `index.html`, `rica_server.py`, and a `VERSION` file (containing the version tag, e.g. `v2.1.5`) in that directory. Download these from the [Rica releases page](https://github.com/ME-ICA/rica/releases/latest).
 
-!!! note
-    `rica_server.py` is a drop-in replacement for `open_rica_report.py`. It serves the same tedana output files — only the Rica version changes.
+## Using a Local or Custom Build
 
-## Checking Which Version You Are Running
+Set the `TEDANA_RICA_PATH` environment variable to a directory containing `index.html` and `rica_server.py`. The script will use those files directly and skip the GitHub download entirely.
 
-The Rica version is shown in the **About** popup (the `(i)` button in the top-right corner of the interface). Compare this to the [latest release](https://github.com/ME-ICA/rica/releases/latest) to see if an update is available.
+```bash
+export TEDANA_RICA_PATH=/path/to/your/rica/build
+python open_rica_report.py
+```
 
-## Updating Across Multiple Tedana Output Folders
+This is useful for:
 
-If you have several tedana output directories and want to update them all:
+- Testing a development build of Rica against real tedana data
+- Pinning a specific version without auto-updates
+- Air-gapped environments where you manage files manually
+
+To build Rica from source:
 
 ```bash
-# Download once
-curl -L -o index.html https://github.com/ME-ICA/rica/releases/latest/download/index.html
-curl -L -o rica_server.py https://github.com/ME-ICA/rica/releases/latest/download/rica_server.py
-
-# Copy to each output folder
-cp index.html rica_server.py /path/to/subject01/tedana/
-cp index.html rica_server.py /path/to/subject02/tedana/
-# ... and so on
+git clone https://github.com/ME-ICA/rica.git
+cd rica
+npm install
+npm run build
+npx gulp
+# Built files are in build/
+export TEDANA_RICA_PATH=/path/to/rica/build
 ```
 
-## What `open_rica_report.py` Does
+## Checking the Current Version
 
-`open_rica_report.py` is generated by tedana and bundles the version of Rica that was current at the time tedana was released. It:
+The Rica version is shown in the **About** popup (the `(i)` button in the top-right corner). The version of the files installed in your output directory is also stored in `rica/VERSION`:
 
-1. Starts a local HTTP server in your tedana output directory
-2. Serves the bundled `index.html` (the Rica application)
-3. Exposes a `/api/files` endpoint so Rica can auto-discover your tedana files
-4. Opens your browser automatically
+```bash
+cat /path/to/tedana/output/rica/VERSION
+```
 
-`rica_server.py` does exactly the same thing — it is the canonical Rica local server and is kept up-to-date with each Rica release.
+Compare this to the [latest release](https://github.com/ME-ICA/rica/releases/latest) to see if an update is available.
 
 ## Troubleshooting
 
 ### Port Already in Use
 
-If port 8000 is occupied, specify a different one:
+If port 8000 is occupied, the script automatically tries the next available port. You can also specify one explicitly:
 
 ```bash
-python rica_server.py --port 9000
+python open_rica_report.py --port 9000
 ```
 
 ### Browser Does Not Open Automatically
 
-Navigate manually to `http://localhost:8000`, or suppress auto-open:
+Navigate manually to the URL printed in the terminal, or suppress auto-open and open it yourself:
 
 ```bash
-python rica_server.py --no-open
+python open_rica_report.py --no-open
+# Then open http://localhost:8000/rica/index.html
 ```
 
-### Files Not Found
-
-Make sure you run the server from inside the tedana output directory (not a parent folder):
+### Script Can't Find tedana Output Files
 
-```bash
-cd /path/to/tedana/output/
-python rica_server.py
-```
+Make sure `open_rica_report.py` is in the tedana output directory (where the `*_metrics.tsv` files are). The script uses its own location to find data.
 
 See [Troubleshooting](troubleshooting.md) for more help.
