From dbcba1a177a09b428525d7d521dbaa80fff82651 Mon Sep 17 00:00:00 2001 From: VibhavSetlur Date: Tue, 12 May 2026 12:37:41 -0500 Subject: [PATCH 1/3] docs: add deployment guide and update env documentation - Add docs/DEPLOYMENT.md with comprehensive env var reference - Update docs/README.md with deployment section link - Update .env.example with full inline documentation for all variables - Document resolution order, override vs mode defaults, optional vs required --- .env.example | 224 ++++++++++++++++++++++++++---------- docs/DEPLOYMENT.md | 277 +++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + 3 files changed, 441 insertions(+), 61 deletions(-) create mode 100644 docs/DEPLOYMENT.md diff --git a/.env.example b/.env.example index 7bfe261a..305c93df 100644 --- a/.env.example +++ b/.env.example @@ -1,102 +1,204 @@ +# ============================================================================= # .env.example +# ============================================================================= # -# 1) Copy to .env.local -# 2) Choose deployment mode: -# - NEXT_PUBLIC_DEPLOYMENT_MODE=staging|production (recommended) -# - NEXT_PUBLIC_DEPLOYMENT_MODE=manual for strict override mode (requires vars below) +# This file documents every environment variable used by the ModelSEED UI. # -# Local Poplar tunnel example: -# ssh -L 8000:localhost:8000 YOUR_USERNAME@poplar.cels.anl.gov +# HOW TO USE THIS FILE: +# 1. Copy this file to .env.local +# cp .env.example .env.local +# 2. Choose a deployment mode (see DEPLOYMENT MODE section below) +# 3. Fill in any required overrides for your environment +# 4. Restart the dev server or rebuild for changes to take effect +# +# DEPLOYMENT MODES: +# There are two ways to configure endpoints: by deployment mode, or by +# manual override. Deployment mode is the recommended approach. +# +# staging - Points all endpoints at staging.modelseed.org. +# Requires zero override configuration. This is the default +# when NEXT_PUBLIC_DEPLOYMENT_MODE is unset. +# +# production - Points all endpoints at modelseed.org. +# Requires zero override configuration. +# +# manual - Disables automatic endpoint resolution. Every URL must be +# provided explicitly via *_BASE_URL override variables. +# Useful for local development against custom backends. +# If any required override is missing in manual mode, the app +# will throw an error at startup. +# +# RESOLUTION ORDER (for every URL-type variable): +# 1. Override (highest precedence) -- e.g. NEXT_PUBLIC_SITE_BASE_URL +# 2. Mode-specific default -- e.g. NEXT_PUBLIC_SITE_BASE_URL_STAGING +# 3. Hardcoded fallback built into config.ts +# +# OPTIONAL vs REQUIRED: +# - "optional" means the app has a sensible default and will work if you +# leave it blank or unset. +# - "required in manual mode" means you must set it yourself when +# NEXT_PUBLIC_DEPLOYMENT_MODE=manual, but it is ignored otherwise. +# - "required" means the app will not function without it in any mode. +# +# ============================================================================= -# ========================= -# Deployment Mode (required - set to staging, production, or manual) -# ========================= +# ============================================================================= +# DEPLOYMENT MODE +# ============================================================================= + +# Controls which set of endpoint defaults the application uses. +# +# Values: staging | production | manual +# Default: staging (when unset or empty) +# Required: Yes +# +# Set to "staging" or "production" for automatic endpoint configuration. +# Set to "manual" if you want to provide every endpoint URL yourself. NEXT_PUBLIC_DEPLOYMENT_MODE=staging -# ========================= -# Site URL defaults + override -# ========================= -# Override (highest precedence, no trailing slash) +# ============================================================================= +# SITE BASE URL +# ============================================================================= +# The base origin used to derive all relative backend paths. +# No trailing slash. +# +# Override: Required in manual mode, otherwise optional (mode default used) +# Mode default: staging=https://staging.modelseed.org | production=https://modelseed.org +# Hardcoded: (none -- mode defaults always available) NEXT_PUBLIC_SITE_BASE_URL= -# Mode defaults NEXT_PUBLIC_SITE_BASE_URL_STAGING=https://staging.modelseed.org NEXT_PUBLIC_SITE_BASE_URL_PRODUCTION=https://modelseed.org -# ========================= -# modelseed-api defaults + override -# ========================= -# Override (highest precedence, no trailing slash) -# Example local tunnel: -NEXT_PUBLIC_API_BASE_URL=http://localhost:8000 -# Mode defaults +# ============================================================================= +# MODELSEED-API BASE URL (modelseed_support / PMS) +# ============================================================================= +# Base URL for the modelseed-api service. No trailing slash. +# +# Override: Required in manual mode, otherwise optional (mode default used) +# Mode default: staging=https://staging.modelseed.org/PMS | production=https://modelseed.org/PMS +# Fallback: {MODELSEED_SITE_BASE_URL}/PMS +NEXT_PUBLIC_API_BASE_URL= NEXT_PUBLIC_API_BASE_URL_STAGING=https://staging.modelseed.org/PMS NEXT_PUBLIC_API_BASE_URL_PRODUCTION=https://modelseed.org/PMS -# ========================= -# Legacy REST defaults + override (/api/v0) -# ========================= +# ============================================================================= +# LEGACY REST BASE URL (/api/v0) +# ============================================================================= +# Base URL for the legacy ModelSEED REST v0 API. No trailing slash. +# +# Override: Required in manual mode, otherwise optional (mode default used) +# Mode default: staging=https://staging.modelseed.org/api/v0 | production=https://modelseed.org/api/v0 +# Fallback: {MODELSEED_SITE_BASE_URL}/api/v0 NEXT_PUBLIC_REST_BASE_URL= NEXT_PUBLIC_REST_BASE_URL_STAGING=https://staging.modelseed.org/api/v0 NEXT_PUBLIC_REST_BASE_URL_PRODUCTION=https://modelseed.org/api/v0 -# ========================= -# Status endpoint defaults + override (/about/version) -# ========================= +# ============================================================================= +# STATUS API URL (/about/version) +# ============================================================================= +# Endpoint used by the /about/version page to report build and service status. +# No trailing slash. +# +# Override: Required in manual mode, otherwise optional (mode default used) +# Mode default: staging=https://staging.modelseed.org/api/test-service | production=https://modelseed.org/api/test-service +# Fallback: {MODELSEED_SITE_BASE_URL}/api/test-service NEXT_PUBLIC_STATUS_API_URL= NEXT_PUBLIC_STATUS_API_URL_STAGING=https://staging.modelseed.org/api/test-service NEXT_PUBLIC_STATUS_API_URL_PRODUCTION=https://modelseed.org/api/test-service -# ========================= -# Solr base defaults + override -# ========================= -# Override (highest precedence, with or without trailing slash) +# ============================================================================= +# SOLR BASE URL +# ============================================================================= +# Base URL for the Solr search backend. Trailing slash is stripped at runtime. +# +# Override: Required in manual mode, otherwise optional (mode default used) +# Mode default: staging=https://staging.modelseed.org/solr/ | production=https://modelseed.org/solr/ +# Fallback: {MODELSEED_SITE_BASE_URL}/solr/ NEXT_PUBLIC_SOLR_BASE_URL= -# Mode defaults NEXT_PUBLIC_SOLR_BASE_URL_STAGING=https://staging.modelseed.org/solr/ NEXT_PUBLIC_SOLR_BASE_URL_PRODUCTION=https://modelseed.org/solr/ -# ========================= -# Solr collection/core defaults + override -# ========================= -# Overrides (highest precedence) +# ============================================================================= +# SOLR COLLECTION / CORE NAMES +# ============================================================================= +# The Solr core names for the reactions and compounds collections. +# These must match the names configured in your Solr instance. +# +# Override: Required in manual mode, otherwise optional (mode default used) +# Mode default: staging=reactions_staging / compounds_staging +# production=reactions / compounds +# Fallback: staging: "reactions_staging" / "compounds_staging" +# production: "reactions" / "compounds" NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION= NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION= -# Mode defaults NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION_STAGING=reactions_staging -NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION_PRODUCTION=reactions NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION_STAGING=compounds_staging +NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION_PRODUCTION=reactions NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION_PRODUCTION=compounds -# ========================= -# Feature Flags -# ========================= +# ============================================================================= +# FEATURE FLAGS +# ============================================================================= + +# Enables the modelseed-api proxy for workspace operations. +# When false, falls back to the legacy direct Workspace URL. +# Values: true | false +# Default: true NEXT_PUBLIC_USE_MODELSEED_API=true + +# Enables the new proxy layer for backend services. +# When false, certain services (ProbModelSEED, Workspace) fall back to +# legacy direct endpoints. +# Values: true | false +# Default: true NEXT_PUBLIC_USE_NEW_PROXY=true -# ========================= -# ProbModelSEED URL Override -# ========================= -# Override for ProbModelSEED API endpoint (no trailing slash) -# Defaults to {SITE_BASE}/api/model when USE_NEW_PROXY=true +# ============================================================================= +# PROBMODELSEED URL +# ============================================================================= +# Override for the ProbModelSEED API endpoint. No trailing slash. +# +# When NEXT_PUBLIC_USE_NEW_PROXY=true and this is unset, defaults to: +# {MODELSEED_SITE_BASE_URL}/api/model +# +# When NEXT_PUBLIC_USE_NEW_PROXY=false, this is ignored and the legacy URL +# https://p3.theseed.org/services/ProbModelSEED +# is used instead. +# +# Override: Optional (computed from SITE_BASE_URL when using new proxy) NEXT_PUBLIC_PROBMODELSEED_URL= -# ========================= -# RDKit.js URL Override (optional) -# ========================= -# Override for RDKit.js assets (no trailing slash) -# Defaults to unpkg CDN when unset - no need to set unless self-hosting +# ============================================================================= +# RDKIT.JS URL +# ============================================================================= +# Override for self-hosted RDKit.js assets. No trailing slash. +# +# When unset, the app loads RDKit.js from the unpkg CDN: +# https://unpkg.com/@rdkit/rdkit@{VERSION}/dist +# +# Set this only if you are self-hosting RDKit.js (e.g. /public/rdkit). +# Value will have trailing slash stripped at runtime. +# +# Override: Optional. Defaults to unpkg CDN. # NEXT_PUBLIC_RDKIT_BASE_URL= -# ========================= -# Build Metadata (/about/version) -# ========================= -NEXT_PUBLIC_GIT_VERSION=3.0.0 -NEXT_PUBLIC_GIT_BRANCH=staging +# ============================================================================= +# BUILD METADATA +# ============================================================================= +# These values are injected at build time by CI/CD and displayed on the +# /about/version page. They do not affect runtime behavior. +# +# Default: (populated by CI; safe to leave blank for local dev) +NEXT_PUBLIC_GIT_VERSION= +NEXT_PUBLIC_GIT_BRANCH= NEXT_PUBLIC_GIT_COMMIT= NEXT_PUBLIC_DEPLOY_DATE= -# ========================= -# Test Credentials -# ========================= -# PATRIC token for API testing (get from PATRIC website) -PATRIC_TOKEN= +# ============================================================================= +# TEST CREDENTIALS +# ============================================================================= +# PATRIC authentication token for integration testing. +# Get a token from https://p3.theseed.org/user/authenticate +# +# Optional. Not required for application functionality. +PATRIC_TOKEN= \ No newline at end of file diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 00000000..17a41491 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,277 @@ +# Deployment Configuration + +This document describes every environment variable consumed by the ModelSEED UI, +how they are resolved at runtime, and how to configure them for different environments. + +--- + +## Quick Start + +```bash +cp .env.example .env.local +# Edit .env.local to match your environment, then: +npm run dev +``` + +--- + +## Deployment Mode + +The `NEXT_PUBLIC_DEPLOYMENT_MODE` variable selects which set of endpoint defaults +the application uses. It is the **primary switch** that controls all URL resolution. + +| Value | Behavior | +| :----------- | :------- | +| `staging` | All endpoints resolve to `staging.modelseed.org` subdomains. **Default when unset.** | +| `production` | All endpoints resolve to `modelseed.org` subdomains. | +| `manual` | Disables automatic resolution. Every URL override must be set explicitly. The app will throw at startup if any required override is missing. | + +**Default:** `staging` (when the variable is unset or empty) + +**Required:** Yes. The app will not start with an invalid or unrecognized value. + +**Important:** When switching between staging and production, you do not need to +touch any of the individual URL variables. The mode defaults in +`.env.example` (and the hardcoded fallbacks in `lib/api/config.ts`) handle everything. + +--- + +## Resolution Algorithm (for all URL variables) + +Every URL-type variable follows a strict three-tier resolution order: + +``` +1. Override (highest precedence) + e.g. NEXT_PUBLIC_API_BASE_URL=http://localhost:8000 + +2. Mode-specific default + e.g. NEXT_PUBLIC_API_BASE_URL_STAGING=https://staging.modelseed.org/PMS + +3. Hardcoded fallback in lib/api/config.ts + e.g. `${MODELSEED_SITE_BASE_URL}/PMS` +``` + +The app checks tier 1 first. If it is empty, tier 2 is consulted. If that is also +empty (or the variable is not set), the code in `lib/api/config.ts` applies a +computed fallback derived from the site base URL. + +**You only need to set the override tier (`NEXT_PUBLIC_X`) when you want to +deviate from the deployment mode defaults.** For standard staging or production +deployments, leave all override variables **blank** and rely on the mode defaults. + +--- + +## Environment Variable Reference + +### `NEXT_PUBLIC_DEPLOYMENT_MODE` -- REQUIRED + +Controls which mode-default set is active. + +- **Values:** `staging` | `production` | `manual` +- **Default:** `staging` +- **Required:** Yes + +--- + +### Base URLs (no trailing slash) + +#### `NEXT_PUBLIC_SITE_BASE_URL` -- REQUIRED in manual mode, otherwise optional + +The base origin for the ModelSEED website. All other URL fallbacks derive from this. + +- **Override:** Required in manual mode, optional otherwise +- **Mode defaults:** `staging=https://staging.modelseed.org` / `production=https://modelseed.org` +- **Hardcoded fallback:** (none -- mode defaults always available) + +#### `NEXT_PUBLIC_API_BASE_URL` -- REQUIRED in manual mode, otherwise optional + +Base URL for the modelseed-api (Poplar) service. + +- **Override:** Required in manual mode, optional otherwise +- **Mode defaults:** `staging=https://staging.modelseed.org/PMS` / `production=https://modelseed.org/PMS` +- **Fallback:** `{MODELSEED_SITE_BASE_URL}/PMS` +- **Common local setup:** `http://localhost:8000` (via Poplar SSH tunnel) + +#### `NEXT_PUBLIC_REST_BASE_URL` -- REQUIRED in manual mode, otherwise optional + +Base URL for the legacy ModelSEED REST v0 API. + +- **Override:** Required in manual mode, optional otherwise +- **Mode defaults:** `staging=https://staging.modelseed.org/api/v0` / `production=https://modelseed.org/api/v0` +- **Fallback:** `{MODELSEED_SITE_BASE_URL}/api/v0` + +#### `NEXT_PUBLIC_STATUS_API_URL` -- REQUIRED in manual mode, otherwise optional + +Status endpoint used by the `/about/version` page for build and service checks. + +- **Override:** Required in manual mode, optional otherwise +- **Mode defaults:** `staging=https://staging.modelseed.org/api/test-service` / `production=https://modelseed.org/api/test-service` +- **Fallback:** `{MODELSEED_SITE_BASE_URL}/api/test-service` + +--- + +### Solr Configuration + +#### `NEXT_PUBLIC_SOLR_BASE_URL` -- REQUIRED in manual mode, otherwise optional + +Base URL for the Solr search backend. Trailing slash is stripped at runtime. + +- **Override:** Required in manual mode, optional otherwise +- **Mode defaults:** `staging=https://staging.modelseed.org/solr/` / `production=https://modelseed.org/solr/` +- **Fallback:** `{MODELSEED_SITE_BASE_URL}/solr/` + +#### `NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION` -- REQUIRED in manual mode, otherwise optional + +Solr core name for the reactions collection. + +- **Override:** Required in manual mode, optional otherwise +- **Mode defaults:** `staging=reactions_staging` / `production=reactions` +- **Fallback:** `reactions_staging` (staging) / `reactions` (production) + +#### `NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION` -- REQUIRED in manual mode, otherwise optional + +Solr core name for the compounds collection. + +- **Override:** Required in manual mode, optional otherwise +- **Mode defaults:** `staging=compounds_staging` / `production=compounds` +- **Fallback:** `compounds_staging` (staging) / `compounds` (production) + +--- + +### Feature Flags (optional) + +#### `NEXT_PUBLIC_USE_MODELSEED_API` -- Optional + +Enables the modelseed-api (Poplar) proxy for workspace operations. When `false`, +the legacy Workspace URL (`https://p3.theseed.org/services/Workspace`) is used. + +- **Values:** `true` | `false` +- **Default:** `true` + +#### `NEXT_PUBLIC_USE_NEW_PROXY` -- Optional + +Enables the new proxy layer for all backend services. When `false`, the following +services fall back to their legacy endpoints: +- **Workspace:** `https://p3.theseed.org/services/Workspace` +- **ProbModelSEED:** `https://p3.theseed.org/services/ProbModelSEED` + +- **Values:** `true` | `false` +- **Default:** `true` + +--- + +### ProbModelSEED URL (optional) + +#### `NEXT_PUBLIC_PROBMODELSEED_URL` -- Optional + +Override for the ProbModelSEED API endpoint. No trailing slash. + +- **When `USE_NEW_PROXY=true` and this is empty:** Resolves to `{SITE_BASE_URL}/api/model` +- **When `USE_NEW_PROXY=false`:** This is ignored; the legacy URL is used instead. + +--- + +### RDKit.js URL (optional) + +#### `NEXT_PUBLIC_RDKIT_BASE_URL` -- Optional + +Override for self-hosted RDKit.js assets. No trailing slash. + +- **When empty:** RDKit.js loads from the unpkg CDN (`https://unpkg.com/@rdkit/rdkit@{VERSION}/dist`). +- **When set:** Must point to a directory containing `RDKit_minimal.js` and `RDKit_minimal.wasm`. + Example for self-hosting via the `/public` directory: `/public/rdkit` + +--- + +### Build Metadata (displayed on /about/version) + +These are injected at build time by CI/CD and do not affect runtime behavior. +They are safe to leave blank for local development. + +| Variable | Purpose | +| :------------------- | :---------------------------------- | +| `NEXT_PUBLIC_GIT_VERSION` | Semantic version string | +| `NEXT_PUBLIC_GIT_BRANCH` | Git branch name | +| `NEXT_PUBLIC_GIT_COMMIT` | Git commit SHA | +| `NEXT_PUBLIC_DEPLOY_DATE` | Deployment date string | + +--- + +### Test Credentials (optional) + +#### `PATRIC_TOKEN` -- Optional + +PATRIC authentication token for integration testing. Obtain from +. + +Not required for application functionality. + +--- + +## Scenarios + +### Standard Staging Deployment + +Set only the deployment mode. Everything else resolves automatically: + +```env +NEXT_PUBLIC_DEPLOYMENT_MODE=staging +``` + +### Standard Production Deployment + +```env +NEXT_PUBLIC_DEPLOYMENT_MODE=production +``` + +### Local Development (Poplar Tunnel) + +Start a tunnel, then override the API base URL: + +```bash +ssh -L 8000:localhost:8000 YOUR_USERNAME@poplar.cels.anl.gov +``` + +```env +NEXT_PUBLIC_DEPLOYMENT_MODE=staging +NEXT_PUBLIC_API_BASE_URL=http://localhost:8000 +``` + +### Complete Custom (Manual Mode) + +Set every URL explicitly: + +```env +NEXT_PUBLIC_DEPLOYMENT_MODE=manual +NEXT_PUBLIC_SITE_BASE_URL=https://my-custom-host.example.com +NEXT_PUBLIC_API_BASE_URL=https://my-custom-host.example.com/PMS +NEXT_PUBLIC_REST_BASE_URL=https://my-custom-host.example.com/api/v0 +NEXT_PUBLIC_STATUS_API_URL=https://my-custom-host.example.com/api/test-service +NEXT_PUBLIC_SOLR_BASE_URL=https://my-custom-host.example.com/solr/ +NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION=reactions +NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION=compounds +``` + +--- + +## Runtime Configuration Code + +All URL resolution logic lives in: + +- **`lib/api/config.ts`** -- Defines `resolveModeValue()`, `resolveDeploymentMode()`, + and exports all resolved URL constants (`MODELSEED_SITE_BASE_URL`, + `MODELSEED_API_URL`, `MODELSEED_REST_URL`, `SOLR_BASE_LEGACY`, etc.). +- **`lib/rdkit.ts`** -- Handles `NEXT_PUBLIC_RDKIT_BASE_URL` with an unpkg fallback. + +--- + +## Switching Between Environments + +To change the target environment after the app is running: + +1. Update `NEXT_PUBLIC_DEPLOYMENT_MODE` in `.env.local` +2. Restart the dev server (`npm run dev`) or rebuild (`npm run build`) +3. Verify on the `/about/version` page that the correct endpoints are shown + +**Note:** `.env.local` changes require a full server restart. HMR does not pick up +environment variable changes. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index ebdc26f3..6625aad2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,7 @@ This directory contains the technical documentation for the ModelSEED-UI applica | **Scientific Data** | [BIOCHEMISTRY.md](./BIOCHEMISTRY.md) | Solr-indexed reactions/compounds lookup and chemical formula/stoichiometry UX rendering rules. | | **Legacy Codebase** | [LEGACY_TRANSITION.md](./LEGACY_TRANSITION.md) | Transitioning from the AngularJS source code to modern React patterns. | | **Testing Platform** | [TESTING.md](./TESTING.md) | Vitest unit tests, Playwright E2E tests, and CI/CD pipeline. | +| **Deploying** | [DEPLOYMENT.md](./DEPLOYMENT.md) | Environment variables, deployment modes, URL resolution, and configuration guide. | | **Contributing** | [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) | Guidelines for maintaining the documentation. | ## Project Design Principles From 5881365bb06e631afb4210a8fa1295587894b362 Mon Sep 17 00:00:00 2001 From: VibhavSetlur Date: Tue, 12 May 2026 12:37:45 -0500 Subject: [PATCH 2/3] docs: update changelog with v3.0.1 release notes - Add [3.0.1] - 2026-05-12 section with user-facing UI/UX changes - Move [Unreleased] section to top per Keep a Changelog convention - Include only user-visible changes (search, filters, tooltips, comments, polish) - Strip backend/config changes from changelog entries --- CHANGELOG.md | 67 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c2dc32e..73bc1969 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,33 +5,66 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [{{VERSION}}] - 2026-04-06 +## [Unreleased] - TBD + +### Known Issues +- RAST MS FBA not working +- PATRIC-only model submission +- Workspace write operations limited + +### Expected Behaviors +- Models/Media differ between RAST and PATRIC (intentional system design) + +--- + +## [3.0.1] - 2026-05-12 ### Added -- Compound structure images on reaction pages with click-through to compound detail pages -- Comprehensive troubleshooting documentation and enhanced README with SSH tunnel setup instructions +- Find-in-page style search replacing the legacy search bar across the application +- Multiple filter rows with AND/OR logic in the DataControlHeader toolbar +- Case-insensitive Solr matching via case-variant filter clauses +- Hover tooltips and popup dialog for pathway visualization in the reactions table +- Reaction comments API route with modal UI integration +- PlantSEED copy functionality with editing restrictions for reconstructed models +- Branch name and upstream repository link displayed on the `/about/version` screen +- Compound synonym formatting with chemistry-aware scripts and improved list layout +- Gene reactions rendered as linked chips on model detail pages +- Production-quality polish applied to 8 secondary pages ### Changed -- Version display updated to show v{{VERSION}} from environment +- Compound detail and reaction detail pages stabilized with improved metadata presentation +- Reaction structure cards fixed and compound detail refined ### Fixed -- Invalid gapfill URL handling to gracefully return empty results instead of 404 errors -- Improved Reaction/Compound detail drawer with better typography and monospace formatting - -### Documentation -- SSH tunnel requirements, environment variables, and account separation expectations +- Compounds Solr quick search repaired (was using invalid ontology field) +- DataControlHeader hardened across all grid consumers to prevent filter state loss +- Dual-backend filtering in search hardened +- Grid state preserved when using `onApplyFilterModel` for server-side pagination +- Toolbar filter intent preserved correctly across community grid constraint changes +- FBA detail data now loaded by `fba_id` instead of incorrect reference +- Model detail pages now use canonical model ref for both FBA and gapfill data +- Gapfill page fixed to properly parse solution data and handle incorrect API refs +- Explicit unavailable-image placeholders added to prevent broken image UI +- Filtered row count now used in CustomPagination for accurate display +- JSON parse error handling in the comments route returns 400 on malformed input +- Boolean parsing in the comments route fixed with explicit `typeof` check +- React key uniqueness enforced in ChemicalEquation token rendering +- Next.js upgraded to patched **16.2.6** to resolve high-severity advisories --- -## [Unreleased] - TBD +## [3.0.0] - 2026-04-06 -### Known Issues -- RAST MS FBA not working -- PATRIC-only model submission -- Workspace write operations limited +### Added +- Compound structure images on reaction pages with click-through to compound detail pages +- Comprehensive troubleshooting documentation and enhanced README with SSH tunnel setup instructions -### Expected Behaviors -- Models/Media differ between RAST and PATRIC (intentional system design) +### Changed +- Version display updated to show v{{VERSION}} from environment + +### Fixed +- Invalid gapfill URL handling to gracefully return empty results instead of 404 errors +- Improved Reaction/Compound detail drawer with better typography and monospace formatting --- @@ -138,7 +171,7 @@ Below contains a summary of notable changes and deploy dates for each release fr ## [1.3.1-beta] - 2016-03-03 -- Add permalink compound and reaction pages. e.g., [cpd00001](http://modelseed.org/biochem/compounds/cpd00001) and [rxn00001](http://modelseed.org/biochem/reactions/rxn00001) +- Add permalink compound and reaction pages - Add [Fusions](http://modelseed.org/projects/fusions) project - Stylistic fixes From 00061f8a808a0cb166bc31973a3ffc4964e282db Mon Sep 17 00:00:00 2001 From: VibhavSetlur Date: Tue, 12 May 2026 12:53:35 -0500 Subject: [PATCH 3/3] docs: correct deployment guide and env docs per review - .env.example: fix deployment mode required wording, SITE_BASE_URL hardcoded fallback, RDKit.js self-host path - docs/DEPLOYMENT.md: fix deployment mode required wording, SITE_BASE_URL hardcoded fallback, ProbModelSEED proxy var name, RDKit.js /public path, improve clarity --- .env.example | 7 ++--- docs/DEPLOYMENT.md | 66 +++++++++++++++++++++++----------------------- 2 files changed, 37 insertions(+), 36 deletions(-) diff --git a/.env.example b/.env.example index 305c93df..57b040e8 100644 --- a/.env.example +++ b/.env.example @@ -50,7 +50,7 @@ # # Values: staging | production | manual # Default: staging (when unset or empty) -# Required: Yes +# Required: No (optional; defaults to staging when unset or empty) # # Set to "staging" or "production" for automatic endpoint configuration. # Set to "manual" if you want to provide every endpoint URL yourself. @@ -64,7 +64,7 @@ NEXT_PUBLIC_DEPLOYMENT_MODE=staging # # Override: Required in manual mode, otherwise optional (mode default used) # Mode default: staging=https://staging.modelseed.org | production=https://modelseed.org -# Hardcoded: (none -- mode defaults always available) +# Hardcoded: staging=https://staging.modelseed.org | production=https://modelseed.org NEXT_PUBLIC_SITE_BASE_URL= NEXT_PUBLIC_SITE_BASE_URL_STAGING=https://staging.modelseed.org NEXT_PUBLIC_SITE_BASE_URL_PRODUCTION=https://modelseed.org @@ -176,7 +176,8 @@ NEXT_PUBLIC_PROBMODELSEED_URL= # When unset, the app loads RDKit.js from the unpkg CDN: # https://unpkg.com/@rdkit/rdkit@{VERSION}/dist # -# Set this only if you are self-hosting RDKit.js (e.g. /public/rdkit). +# Set this only if you are self-hosting RDKit.js. +# If the assets are in public/rdkit, set NEXT_PUBLIC_RDKIT_BASE_URL=/rdkit. # Value will have trailing slash stripped at runtime. # # Override: Optional. Defaults to unpkg CDN. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 17a41491..15e3f92e 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -28,11 +28,11 @@ the application uses. It is the **primary switch** that controls all URL resolut **Default:** `staging` (when the variable is unset or empty) -**Required:** Yes. The app will not start with an invalid or unrecognized value. +**Required:** No. The app defaults to `staging` automatically. Only set this to `production` or `manual` if you need a different behavior. Invalid non-empty values will cause a startup error. **Important:** When switching between staging and production, you do not need to -touch any of the individual URL variables. The mode defaults in -`.env.example` (and the hardcoded fallbacks in `lib/api/config.ts`) handle everything. +touch any of the individual URL variables. The mode defaults in `.env.example` +(and the hardcoded fallbacks in `lib/api/config.ts`) handle everything. --- @@ -48,7 +48,7 @@ Every URL-type variable follows a strict three-tier resolution order: e.g. NEXT_PUBLIC_API_BASE_URL_STAGING=https://staging.modelseed.org/PMS 3. Hardcoded fallback in lib/api/config.ts - e.g. `${MODELSEED_SITE_BASE_URL}/PMS` + e.g. ${MODELSEED_SITE_BASE_URL}/PMS ``` The app checks tier 1 first. If it is empty, tier 2 is consulted. If that is also @@ -63,27 +63,27 @@ deployments, leave all override variables **blank** and rely on the mode default ## Environment Variable Reference -### `NEXT_PUBLIC_DEPLOYMENT_MODE` -- REQUIRED +### `NEXT_PUBLIC_DEPLOYMENT_MODE` Controls which mode-default set is active. - **Values:** `staging` | `production` | `manual` - **Default:** `staging` -- **Required:** Yes +- **Required:** No. Defaults to `staging` when unset. --- ### Base URLs (no trailing slash) -#### `NEXT_PUBLIC_SITE_BASE_URL` -- REQUIRED in manual mode, otherwise optional +#### `NEXT_PUBLIC_SITE_BASE_URL` -- Required in manual mode, otherwise optional The base origin for the ModelSEED website. All other URL fallbacks derive from this. - **Override:** Required in manual mode, optional otherwise - **Mode defaults:** `staging=https://staging.modelseed.org` / `production=https://modelseed.org` -- **Hardcoded fallback:** (none -- mode defaults always available) +- **Hardcoded fallback:** `SITE_DEFAULTS` in `lib/api/config.ts` (`staging=https://staging.modelseed.org` / `production=https://modelseed.org`) -#### `NEXT_PUBLIC_API_BASE_URL` -- REQUIRED in manual mode, otherwise optional +#### `NEXT_PUBLIC_API_BASE_URL` -- Required in manual mode, otherwise optional Base URL for the modelseed-api (Poplar) service. @@ -92,7 +92,7 @@ Base URL for the modelseed-api (Poplar) service. - **Fallback:** `{MODELSEED_SITE_BASE_URL}/PMS` - **Common local setup:** `http://localhost:8000` (via Poplar SSH tunnel) -#### `NEXT_PUBLIC_REST_BASE_URL` -- REQUIRED in manual mode, otherwise optional +#### `NEXT_PUBLIC_REST_BASE_URL` -- Required in manual mode, otherwise optional Base URL for the legacy ModelSEED REST v0 API. @@ -100,7 +100,7 @@ Base URL for the legacy ModelSEED REST v0 API. - **Mode defaults:** `staging=https://staging.modelseed.org/api/v0` / `production=https://modelseed.org/api/v0` - **Fallback:** `{MODELSEED_SITE_BASE_URL}/api/v0` -#### `NEXT_PUBLIC_STATUS_API_URL` -- REQUIRED in manual mode, otherwise optional +#### `NEXT_PUBLIC_STATUS_API_URL` -- Required in manual mode, otherwise optional Status endpoint used by the `/about/version` page for build and service checks. @@ -112,7 +112,7 @@ Status endpoint used by the `/about/version` page for build and service checks. ### Solr Configuration -#### `NEXT_PUBLIC_SOLR_BASE_URL` -- REQUIRED in manual mode, otherwise optional +#### `NEXT_PUBLIC_SOLR_BASE_URL` -- Required in manual mode, otherwise optional Base URL for the Solr search backend. Trailing slash is stripped at runtime. @@ -120,7 +120,7 @@ Base URL for the Solr search backend. Trailing slash is stripped at runtime. - **Mode defaults:** `staging=https://staging.modelseed.org/solr/` / `production=https://modelseed.org/solr/` - **Fallback:** `{MODELSEED_SITE_BASE_URL}/solr/` -#### `NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION` -- REQUIRED in manual mode, otherwise optional +#### `NEXT_PUBLIC_SOLR_REACTIONS_COLLECTION` -- Required in manual mode, otherwise optional Solr core name for the reactions collection. @@ -128,7 +128,7 @@ Solr core name for the reactions collection. - **Mode defaults:** `staging=reactions_staging` / `production=reactions` - **Fallback:** `reactions_staging` (staging) / `reactions` (production) -#### `NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION` -- REQUIRED in manual mode, otherwise optional +#### `NEXT_PUBLIC_SOLR_COMPOUNDS_COLLECTION` -- Required in manual mode, otherwise optional Solr core name for the compounds collection. @@ -140,7 +140,7 @@ Solr core name for the compounds collection. ### Feature Flags (optional) -#### `NEXT_PUBLIC_USE_MODELSEED_API` -- Optional +#### `NEXT_PUBLIC_USE_MODELSEED_API` Enables the modelseed-api (Poplar) proxy for workspace operations. When `false`, the legacy Workspace URL (`https://p3.theseed.org/services/Workspace`) is used. @@ -148,12 +148,10 @@ the legacy Workspace URL (`https://p3.theseed.org/services/Workspace`) is used. - **Values:** `true` | `false` - **Default:** `true` -#### `NEXT_PUBLIC_USE_NEW_PROXY` -- Optional +#### `NEXT_PUBLIC_USE_NEW_PROXY` -Enables the new proxy layer for all backend services. When `false`, the following -services fall back to their legacy endpoints: -- **Workspace:** `https://p3.theseed.org/services/Workspace` -- **ProbModelSEED:** `https://p3.theseed.org/services/ProbModelSEED` +Enables the new proxy layer for backend services. When `false`, certain services +(ProbModelSEED, Workspace) fall back to their legacy endpoints. - **Values:** `true` | `false` - **Default:** `true` @@ -162,44 +160,46 @@ services fall back to their legacy endpoints: ### ProbModelSEED URL (optional) -#### `NEXT_PUBLIC_PROBMODELSEED_URL` -- Optional +#### `NEXT_PUBLIC_PROBMODELSEED_URL` Override for the ProbModelSEED API endpoint. No trailing slash. -- **When `USE_NEW_PROXY=true` and this is empty:** Resolves to `{SITE_BASE_URL}/api/model` -- **When `USE_NEW_PROXY=false`:** This is ignored; the legacy URL is used instead. +- **When `NEXT_PUBLIC_USE_NEW_PROXY=true` and this is empty:** Resolves to `{SITE_BASE_URL}/api/model` +- **When `NEXT_PUBLIC_USE_NEW_PROXY=false`:** This is ignored; the legacy URL is used instead. --- ### RDKit.js URL (optional) -#### `NEXT_PUBLIC_RDKIT_BASE_URL` -- Optional +#### `NEXT_PUBLIC_RDKIT_BASE_URL` Override for self-hosted RDKit.js assets. No trailing slash. - **When empty:** RDKit.js loads from the unpkg CDN (`https://unpkg.com/@rdkit/rdkit@{VERSION}/dist`). - **When set:** Must point to a directory containing `RDKit_minimal.js` and `RDKit_minimal.wasm`. - Example for self-hosting via the `/public` directory: `/public/rdkit` + Example for self-hosting via the `/public` directory: `/rdkit` + +**Note:** Next.js serves files under `public/` at the site root, so `public/rdkit` maps to the URL `/rdkit`, not `/public/rdkit`. --- ### Build Metadata (displayed on /about/version) -These are injected at build time by CI/CD and do not affect runtime behavior. +These values are injected at build time by CI/CD and do not affect runtime behavior. They are safe to leave blank for local development. -| Variable | Purpose | -| :------------------- | :---------------------------------- | -| `NEXT_PUBLIC_GIT_VERSION` | Semantic version string | -| `NEXT_PUBLIC_GIT_BRANCH` | Git branch name | -| `NEXT_PUBLIC_GIT_COMMIT` | Git commit SHA | -| `NEXT_PUBLIC_DEPLOY_DATE` | Deployment date string | +| Variable | Purpose | +| :--- | :--- | +| `NEXT_PUBLIC_GIT_VERSION` | Semantic version string | +| `NEXT_PUBLIC_GIT_BRANCH` | Git branch name | +| `NEXT_PUBLIC_GIT_COMMIT` | Git commit SHA | +| `NEXT_PUBLIC_DEPLOY_DATE` | Deployment date string | --- ### Test Credentials (optional) -#### `PATRIC_TOKEN` -- Optional +#### `PATRIC_TOKEN` PATRIC authentication token for integration testing. Obtain from .