MODSetter
Add conda one-click installer script and documentation
Description
- add a oneclick-conda-install.sh helper that creates (or reuses) a Conda env, installs the FastAPI backend in editable mode, and installs npm dependencies for the web app and browser extension when Node is available
- document the installer in README.md, including prerequisite notes and usage examples
Motivation and Context
- make local setup easier for contributors who prefer Conda over Docker or manual installs
- addresses feature request for a “one-click” style installer FIX #299
FIX #
Changes Overview
- add oneclick-conda-install.sh with env creation, dependency installs, and post-install tips
- update README.md installation section with instructions and environment variable overrides for the new installer
Screenshots
API Changes
- [ ] This PR includes API changes
Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Performance improvement (non-breaking change which enhances performance)
- [x] Documentation update
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
Testing
- [x] I have tested these changes locally
- [ ] I have added/updated unit tests
- [ ] I have added/updated integration tests
Checklist:
- [x] My code follows the code style of this project
- [x] My change requires documentation updates
- [x] I have updated the documentation accordingly
- [ ] My change requires dependency updates
- [ ] I have updated the dependencies accordingly
- [x] My code builds clean without any errors or warnings
- [x] All new and existing tests passed
High-level PR Summary
This PR introduces an experimental Conda-based one-click installer script (oneclick-conda-install.sh) to simplify local setup for contributors. The script automates the creation of a Conda environment, installs backend dependencies in editable mode, and handles frontend dependencies for both the web app and browser extension when Node.js is available. The README is updated with installation instructions including environment variable customization options for the Conda environment name and Python version.
⏱️ Estimated Review Time: 5-15 minutes
💡 Review Order Suggestion
| Order | File Path |
|---|---|
| 1 | surfsense_web/oneclick-conda-install.sh |
| 2 | README.md |
Summary by CodeRabbit
-
New Features
- Added a one‑click Conda installer to streamline setup: creates or reuses a Conda environment, upgrades Python tooling, installs backend dependencies, optionally installs frontend assets when Node/npm are available, and prints guided post‑install steps. Honors environment name and Python version overrides and is idempotent on reruns.
-
Documentation
- Expanded installation guide with the Conda option, explicit usage steps, prerequisites (Conda, Node.js 18+, required API keys), ETL/service options, re-ordered install methods, and minor wording/formatting cleanup.
@Akilesh-Sahaj is attempting to deploy a commit to the Rohan Verma's projects Team on Vercel.
A member of the Team first needs to authorize it.
![vercel[bot] avatar](https://avatars.githubusercontent.com/in/8329?v=4 "Published by a pub.dev verified publisher"){kind=small}
Walkthrough
Adds a new Conda one‑click installer script and updates README: documents prerequisites, usage, environment variables, and post‑install steps. The script creates or reuses a Conda env, upgrades packaging tools, installs backend deps (editable), optional dev tools, and conditionally installs frontend/extension via npm.
Changes
| Cohort / File(s) | Summary |
|---|---|
Documentation: README updateREADME.md |
Adds a Conda One‑Click Installer option and a prerequisites/setup section (Miniconda/Anaconda, Node.js 18+, API keys, ETL options), documents SURFSENSE_ENV_NAME and SURFSENSE_PYTHON_VERSION, reorders installation methods, adds usage instructions (chmod +x + run), and minor wording/format cleanup. |
Tooling: Conda one‑click installeroneclick-conda-install.sh |
New Bash installer that validates conda, defines project paths and env defaults, idempotently creates/reuses a Conda env (configurable Python), upgrades pip/setuptools/wheel, installs backend in editable mode and optional dev tools, conditionally installs frontend/extension via npm (checks Node.js v18+), and prints post‑install guidance. |
Sequence Diagram(s)
sequenceDiagram
autonumber
actor User
participant Script as oneclick-conda-install.sh
participant Conda
participant Env as Conda Env
participant Python as Backend (pip)
participant NPM as Frontend (npm / Node.js)
User->>Script: ./oneclick-conda-install.sh
Script->>Conda: require conda available
Script->>Conda: conda env list / check Env exists
alt Env missing
Script->>Conda: conda create (name, Python version)
else Env exists
Script->>Env: reuse existing env
end
Script->>Env: conda run python -m pip install -U pip setuptools wheel
Script->>Python: install backend (editable) and dev tools (e.g., pre-commit)
Script->>NPM: check npm and Node.js version (v18+)
alt npm & Node.js OK
Script->>NPM: npm install frontend & extension deps
else npm/Node.js missing or too old
Note right of Script #f9f0c1: Skip frontend install (warn)
end
Script-->>User: print activation and run instructions (uvicorn / npm)
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
- MODSetter/SurfSense#148 — Related README wording and ETL/service prerequisite clarifications.
- MODSetter/SurfSense#61 — Overlapping changes to installation docs and installer wording.
- MODSetter/SurfSense#58 — Related installation/documentation edits.
Poem
hop hop, I scripted a gentle hatch,
conda hums, the env will match,
pip will plant and npm may sing,
one click starts the dev‑stage spring,
carrots, commits, and a tiny hop 🐇✨
Pre-merge checks and finishing touches
❌ Failed checks (2 warnings)
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Linked Issues Check | ⚠️ Warning | The PR implements an automated Conda installer script and updates the documentation as requested by issue [#299], achieving the core objective of streamlining local setup for contributors. However, the script currently suffers from an unbound variable error on BACKEND_DIR which prevents it from fully automating environment creation and dependency installation. | Define and export BACKEND_DIR before its usage or provide a default fallback to ensure the variable is always initialized, eliminating the unbound variable error and restoring full automation. |
| Docstring Coverage | ⚠️ Warning | Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. | You can run @coderabbitai generate docstrings to improve docstring coverage. |
✅ Passed checks (3 passed)
| Check name | Status | Explanation |
|---|---|---|
| Title Check | ✅ Passed | The title clearly underscores the primary change by specifying the addition of a Conda one-click installer script along with updated documentation, making it easy to understand the main contribution at a glance. This phrasing is concise and accurately reflects the contents of the pull request without extraneous details. |
| Out of Scope Changes Check | ✅ Passed | All modifications are confined to the README and the new Conda installer script, which directly support the one-click installer feature requested in the linked issue. There are no unrelated or out-of-scope changes in other modules or files. |
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
✨ Finishing touches
- [ ] 📝 Generate docstrings
🧪 Generate unit tests (beta)
- [ ] Create PR with unit tests
- [ ] Post copyable unit tests in a comment
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands and usage tips.
![coderabbitai[bot] avatar](https://avatars.githubusercontent.com/in/347564?v=4 "Published by a pub.dev verified publisher"){kind=small}
Planning on reviewing this later - but over a quick glance I think the doc need some further changes. Looking at the script I assume the script only depends on the conda installed? If that is the case it would be better to make the conda installation write out of quote block of docker & manual installation to help clarify things.
Okay the script seems not working on my machine - as RecurseML have pointed out I think there is this unbound variable issue on line 77. It was marked as resolved though...
22:59:23 [natsumeryuhane@Ryuhane-MBP_M2]
/Users/natsumeryuhane/playground/SurfSense > ./oneclick-conda-install.sh [#1036] [1] [%]
[INFO] SurfSense one-click Conda installer starting…
[INFO] Conda environment 'surfsense' already exists. Reusing it.
[INFO] Upgrading pip/setuptools/wheel inside 'surfsense'…
Requirement already satisfied: pip in /opt/homebrew/Caskroom/miniconda/base/envs/surfsense/lib/python3.12/site-packages (25.2)
Requirement already satisfied: setuptools in /opt/homebrew/Caskroom/miniconda/base/envs/surfsense/lib/python3.12/site-packages (80.9.0)
Requirement already satisfied: wheel in /opt/homebrew/Caskroom/miniconda/base/envs/surfsense/lib/python3.12/site-packages (0.45.1)
[INFO] Installing SurfSense backend dependencies…
./oneclick-conda-install.sh: line 77: BACKEND_DIR: unbound variable
Okay the script seems not working on my machine - as RecurseML have pointed out I think there is this unbound variable issue on line 77. It was marked as resolved though...
22:59:23 [natsumeryuhane@Ryuhane-MBP_M2] /Users/natsumeryuhane/playground/SurfSense > ./oneclick-conda-install.sh [#1036] [1] [%] [INFO] SurfSense one-click Conda installer starting… [INFO] Conda environment 'surfsense' already exists. Reusing it. [INFO] Upgrading pip/setuptools/wheel inside 'surfsense'… Requirement already satisfied: pip in /opt/homebrew/Caskroom/miniconda/base/envs/surfsense/lib/python3.12/site-packages (25.2) Requirement already satisfied: setuptools in /opt/homebrew/Caskroom/miniconda/base/envs/surfsense/lib/python3.12/site-packages (80.9.0) Requirement already satisfied: wheel in /opt/homebrew/Caskroom/miniconda/base/envs/surfsense/lib/python3.12/site-packages (0.45.1) [INFO] Installing SurfSense backend dependencies… ./oneclick-conda-install.sh: line 77: BACKEND_DIR: unbound variable
@Aki-07 Can you please fix this.
