From 099e3331bda19137ee20ae5195034b2d00c107e1 Mon Sep 17 00:00:00 2001 From: Aki-07 Date: Sun, 12 Oct 2025 11:15:38 +0530 Subject: [PATCH 1/5] feat: add conda one-click installer --- surfsense_web/oneclick-conda-install.sh | 110 ++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 surfsense_web/oneclick-conda-install.sh diff --git a/surfsense_web/oneclick-conda-install.sh b/surfsense_web/oneclick-conda-install.sh new file mode 100644 index 000000000..47dd94b5e --- /dev/null +++ b/surfsense_web/oneclick-conda-install.sh @@ -0,0 +1,110 @@ +#!/usr/bin/env bash +set -euo pipefail + +###################################################################### +# SurfSense one-click installer (Conda based) +# +# This script bootstraps the SurfSense stack by: +# 1. Creating a Conda environment with Python 3.12 (configurable) +# 2. Installing the backend in editable mode with all Python deps +# 3. Installing frontend dependencies (Next.js app + browser extension) +# +# Requirements: +# - Miniconda/Anaconda available on PATH (`conda --version`) +# - Node.js LTS (v18+) with npm for the frontend pieces +# +# Usage: +# chmod +x oneclick-conda-install.sh +# ./oneclick-conda-install.sh # installs into env `surfsense` +# SURFSENSE_ENV_NAME=custom ./oneclick-conda-install.sh +# SURFSENSE_PYTHON_VERSION=3.11 ./oneclick-conda-install.sh +# +# The script is idempotent — rerunning will reuse the Conda environment +# and only reinstall missing dependencies. +###################################################################### + +readonly PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly FRONTEND_DIR="${PROJECT_ROOT}/surfsense_web" +readonly EXTENSION_DIR="${PROJECT_ROOT}/surfsense_browser_extension" + +ENV_NAME="${SURFSENSE_ENV_NAME:-surfsense}" +PYTHON_VERSION="${SURFSENSE_PYTHON_VERSION:-3.12}" + +info() { + printf "\033[1;32m[INFO]\033[0m %s\n" "$*" +} + +warn() { + printf "\033[1;33m[WARN]\033[0m %s\n" "$*" >&2 +} + +error() { + printf "\033[1;31m[ERROR]\033[0m %s\n" "$*" >&2 + exit 1 +} + +require_command() { + local cmd="$1" + if ! command -v "$cmd" >/dev/null 2>&1; then + error "Command '$cmd' not found. Please install it and re-run." + fi +} + +conda_env_exists() { + conda env list | awk '{print $1}' | grep -Fxq "$ENV_NAME" +} + +conda_run() { + conda run --no-capture-output -n "$ENV_NAME" "$@" +} + +main() { + info "SurfSense one-click Conda installer starting…" + + require_command conda + + if ! conda_env_exists; then + info "Creating Conda environment '$ENV_NAME' with Python ${PYTHON_VERSION}…" + conda create -y -n "$ENV_NAME" "python=${PYTHON_VERSION}" + else + info "Conda environment '$ENV_NAME' already exists. Reusing it." + fi + + info "Upgrading pip/setuptools/wheel inside '$ENV_NAME'…" + conda_run python -m pip install --upgrade pip setuptools wheel + + info "Installing SurfSense backend dependencies…" + conda_run python -m pip install -e "${BACKEND_DIR}" + + info "Installing optional developer helpers…" + conda_run python -m pip install "pre-commit>=3.8.0" + + if command -v npm >/dev/null 2>&1; then + info "Installing frontend dependencies (surfsense_web)…" + (cd "${FRONTEND_DIR}" && npm install) + + info "Installing browser extension dependencies (surfsense_browser_extension)…" + (cd "${EXTENSION_DIR}" && npm install) + else + warn "npm not found; skipping frontend dependency installation. Install Node.js 18+ to enable the web UI." + fi + + info "Done! To begin using SurfSense:" + cat < Date: Sun, 12 Oct 2025 11:14:38 +0530 Subject: [PATCH 2/5] docs: document conda one-click installer --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cf0424fe2..89164ca55 100644 --- a/README.md +++ b/README.md @@ -151,6 +151,15 @@ SurfSense provides two installation methods: 2. **[Manual Installation (Recommended)](https://www.surfsense.net/docs/manual-installation)** - For users who prefer more control over their setup or need to customize their deployment. +3. **Conda One-Click Installer (Experimental)** - Create a ready-to-use Conda environment and install backend/frontend dependencies automatically. + - Requires Miniconda/Anaconda plus Node.js 18+ (for the web UI). + - From the repository root run: + ```bash + chmod +x oneclick-conda-install.sh + ./oneclick-conda-install.sh + ``` + - Use `SURFSENSE_ENV_NAME` and `SURFSENSE_PYTHON_VERSION` env vars to customise the Conda environment. + Both installation guides include detailed OS-specific instructions for Windows, macOS, and Linux. Before installation, make sure to complete the [prerequisite setup steps](https://www.surfsense.net/docs/) including: @@ -303,4 +312,3 @@ For detailed contribution guidelines, please see our [CONTRIBUTING.md](CONTRIBUT --- --- - From 8b150cf0ec3a0dcf059cccf8bffc6c308369ecef Mon Sep 17 00:00:00 2001 From: Aki-07 Date: Sun, 12 Oct 2025 11:18:46 +0530 Subject: [PATCH 3/5] feat: move script to the project root --- .../oneclick-conda-install.sh => oneclick-conda-install.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename surfsense_web/oneclick-conda-install.sh => oneclick-conda-install.sh (100%) diff --git a/surfsense_web/oneclick-conda-install.sh b/oneclick-conda-install.sh similarity index 100% rename from surfsense_web/oneclick-conda-install.sh rename to oneclick-conda-install.sh From 0a11de9e956f0896cac02538fba32b664d348fb3 Mon Sep 17 00:00:00 2001 From: Aki-07 Date: Thu, 16 Oct 2025 20:10:17 +0530 Subject: [PATCH 4/5] feat: Prioritize Conda one-click installer in README Reordered the installation options in README.md to highlight the Conda one-click installer as the recommended method for most users. This change aims to clarify and streamline the setup process. --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 89164ca55..507075ee8 100644 --- a/README.md +++ b/README.md @@ -139,19 +139,9 @@ Check out our public roadmap and contribute your ideas or feedback: ### Installation Options -SurfSense provides two installation methods: +SurfSense provides multiple installation methods: -1. **[Docker Installation](https://www.surfsense.net/docs/docker-installation)** - The easiest way to get SurfSense up and running with all dependencies containerized. - - Includes pgAdmin for database management through a web UI - - Supports environment variable customization via `.env` file - - Flexible deployment options (full stack or core services only) - - No need to manually edit configuration files between environments - - See [Docker Setup Guide](DOCKER_SETUP.md) for detailed instructions - - For deployment scenarios and options, see [Deployment Guide](DEPLOYMENT_GUIDE.md) - -2. **[Manual Installation (Recommended)](https://www.surfsense.net/docs/manual-installation)** - For users who prefer more control over their setup or need to customize their deployment. - -3. **Conda One-Click Installer (Experimental)** - Create a ready-to-use Conda environment and install backend/frontend dependencies automatically. +1. **Conda One-Click Installer (Recommended for most users)** - Create a ready-to-use Conda environment and install backend/frontend dependencies automatically. - Requires Miniconda/Anaconda plus Node.js 18+ (for the web UI). - From the repository root run: ```bash @@ -160,6 +150,16 @@ SurfSense provides two installation methods: ``` - Use `SURFSENSE_ENV_NAME` and `SURFSENSE_PYTHON_VERSION` env vars to customise the Conda environment. +2. **[Docker Installation](https://www.surfsense.net/docs/docker-installation)** - The easiest way to get SurfSense up and running with all dependencies containerized. + - Includes pgAdmin for database management through a web UI + - Supports environment variable customization via `.env` file + - Flexible deployment options (full stack or core services only) + - No need to manually edit configuration files between environments + - See [Docker Setup Guide](DOCKER_SETUP.md) for detailed instructions + - For deployment scenarios and options, see [Deployment Guide](DEPLOYMENT_GUIDE.md) + +3. **[Manual Installation](https://www.surfsense.net/docs/manual-installation)** - For users who prefer more control over their setup or need to customize their deployment. + Both installation guides include detailed OS-specific instructions for Windows, macOS, and Linux. Before installation, make sure to complete the [prerequisite setup steps](https://www.surfsense.net/docs/) including: From 184df08f8032fc530d15f5b76bde191fec06fd86 Mon Sep 17 00:00:00 2001 From: Aki-07 Date: Thu, 16 Oct 2025 20:15:14 +0530 Subject: [PATCH 5/5] fix: Define BACKEND_DIR and correct usage in oneclick-conda-install.sh --- oneclick-conda-install.sh | 38 +++++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/oneclick-conda-install.sh b/oneclick-conda-install.sh index 47dd94b5e..b8aa5a90d 100644 --- a/oneclick-conda-install.sh +++ b/oneclick-conda-install.sh @@ -26,6 +26,7 @@ set -euo pipefail readonly PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" readonly FRONTEND_DIR="${PROJECT_ROOT}/surfsense_web" readonly EXTENSION_DIR="${PROJECT_ROOT}/surfsense_browser_extension" +readonly BACKEND_DIR="${PROJECT_ROOT}/surfsense_backend" ENV_NAME="${SURFSENSE_ENV_NAME:-surfsense}" PYTHON_VERSION="${SURFSENSE_PYTHON_VERSION:-3.12}" @@ -74,17 +75,41 @@ main() { conda_run python -m pip install --upgrade pip setuptools wheel info "Installing SurfSense backend dependencies…" + if [[ ! -d "${BACKEND_DIR}" ]]; then + error "Backend directory not found at '${BACKEND_DIR}'. Verify repository layout and adjust BACKEND_DIR." + fi conda_run python -m pip install -e "${BACKEND_DIR}" info "Installing optional developer helpers…" conda_run python -m pip install "pre-commit>=3.8.0" if command -v npm >/dev/null 2>&1; then - info "Installing frontend dependencies (surfsense_web)…" - (cd "${FRONTEND_DIR}" && npm install) - - info "Installing browser extension dependencies (surfsense_browser_extension)…" - (cd "${EXTENSION_DIR}" && npm install) + if command -v node >/dev/null 2>&1; then + NODE_MAJOR="$(node -v | sed -E 's/^v([0-9]+).*/\1/')" + if [[ "${NODE_MAJOR}" -lt 18 ]]; then + warn "Detected Node.js v$(node -v). Require >= v18; skipping frontend installs." + NODE_OK=false + else + NODE_OK=true + fi + else + warn "node not found (only npm present); skipping frontend installs." + NODE_OK=false + fi + if [[ "${NODE_OK:-false}" == true ]]; then + if [[ -d "${FRONTEND_DIR}" ]]; then + info "Installing frontend dependencies (surfsense_web)…" + (cd "${FRONTEND_DIR}" && npm install) + else + warn "Frontend directory not found at '${FRONTEND_DIR}'. Skipping web app install." + fi + if [[ -d "${EXTENSION_DIR}" ]]; then + info "Installing browser extension dependencies (surfsense_browser_extension)…" + (cd "${EXTENSION_DIR}" && npm install) + else + warn "Extension directory not found at '${EXTENSION_DIR}'. Skipping extension install." + fi + fi else warn "npm not found; skipping frontend dependency installation. Install Node.js 18+ to enable the web UI." fi @@ -96,7 +121,7 @@ main() { conda activate ${ENV_NAME} 2. Start the backend API: - (cd ${BACKEND_DIR} && uvicorn app.app:app --reload) + (cd "${BACKEND_DIR}" && uvicorn app.app:app --reload) or refer to DEPLOYMENT_GUIDE.md for production options. 3. Start the web app (if npm was available): @@ -107,4 +132,3 @@ EOF } main "$@" -