diff --git a/README.md b/README.md index cf0424fe2..507075ee8 100644 --- a/README.md +++ b/README.md @@ -139,9 +139,18 @@ Check out our public roadmap and contribute your ideas or feedback: ### Installation Options -SurfSense provides two 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. +SurfSense provides multiple installation methods: + +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 + 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. + +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) @@ -149,7 +158,7 @@ SurfSense provides two installation methods: - 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. **[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. @@ -303,4 +312,3 @@ For detailed contribution guidelines, please see our [CONTRIBUTING.md](CONTRIBUT --- --- - diff --git a/oneclick-conda-install.sh b/oneclick-conda-install.sh new file mode 100644 index 000000000..b8aa5a90d --- /dev/null +++ b/oneclick-conda-install.sh @@ -0,0 +1,134 @@ +#!/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" +readonly BACKEND_DIR="${PROJECT_ROOT}/surfsense_backend" + +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…" + 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 + 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 + + info "Done! To begin using SurfSense:" + cat <