ScanHubs Documentation Updates

docs/source/_getting_started/deployment.rst

@@ -0,0 +1,55 @@
+.. Copyright (C) 2023, BRAIN-LINK UG (haftungsbeschränkt). All Rights Reserved.
+   SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-ScanHub-Commercial
+
+=========================
+Deployment (production)
+=========================
+
+**Status:** initial notes. Validate for your environment before clinical/research use.
+
+Prerequisites
+=============
+
+- Linux server with Docker & Docker Compose
+- Domain (e.g., ``scanhub.example.org``)
+- Valid TLS certificate + private key
+
+Steps (high-level)
+==================
+
+1) Provision server and DNS
+---------------------------
+- Point A/AAAA records to your server.
+
+2) Configure TLS and secrets
+----------------------------
+- Place your **private key** and **certificate** under ``secrets/`` (do **not** commit).
+
+3) Update hostnames and CORS
+----------------------------
+Replace ``localhost`` with your domain in:
+
+- **NGINX**: ``infrastructure/nginx_config.conf`` (``server_name``, HTTP→HTTPS redirect)
+- **UI base URLs**: ``scanhub-ui/src/utils/Urls.tsx``
+- **Allowed origins** in API services:  
+  - ``services/device-manager/app/main.py``  
+  - ``services/exam-manager/app/main.py``  
+  - ``services/mri/sequence-manager/app/main.py``  
+  - ``services/patient-manager/app/main.py``  
+  - ``services/user-login-manager/app/main.py``  
+  - ``services/workflow-manager/app/main.py``
+
+4) Build & start
+----------------
+::
+  docker compose build
+  docker compose up -d
+
+5) Create users
+---------------
+Use the UI to create admin/operator accounts with strong passwords.
+
+Security notes
+==============
+- Limit admin endpoints; consider a reverse proxy/WAF, backups, logging, and secrets management.
+- Review data protection requirements for your use case.

docs/source/_getting_started/installation.rst

@@ -0,0 +1,66 @@
+.. Copyright (C) 2023, BRAIN-LINK UG (haftungsbeschränkt). All Rights Reserved.
+   SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-ScanHub-Commercial
+
+==============================
+Installation (detailed, local)
+==============================
+
+This page expands the Quickstart with additional notes useful for development and CI.
+
+Build strategy
+==============
+
+Base image
+----------
+
+ScanHub services share a **base image**. You can:
+
+- **Build locally** (best when you modify base libs)::
+
+    cd services/base
+    docker build -t scanhub-base .
+    cd ../..
+    docker compose build --build-arg BASE_IMG=scanhub-base:latest
+
+- **Use the GHCR base image** (fastest to begin)::
+
+    docker compose build
+
+Rebuild when needed
+-------------------
+
+Rebuild containers whenever you change the base image, install new libraries, or alter structural aspects of a service.::
+
+  docker compose build
+
+Start/stop lifecycle
+====================
+
+- Start (detached):: 
+
+    docker compose up --detach
+
+- Stop and remove containers::
+
+    docker compose down
+
+Local HTTPS (development)
+=========================
+
+By default, ScanHub runs with a **self-signed certificate**. Browsers will warn; for **localhost** in development you can proceed. For production, see :doc:`deployment`.
+
+Default credentials
+===================
+
+If no user exists, the UI presents a **Create first user** form. Enforce a strong password (≥12 chars).
+
+Where to change URLs and CORS
+=============================
+
+For production hosts you will later change **localhost** to your domain in:
+
+- NGINX config (see deployment page)
+- UI URL configuration
+- Allowed origins in API services
+
+(Exact file paths are summarized in :doc:`deployment`.)

docs/source/_getting_started/quickstart.rst

@@ -0,0 +1,58 @@
+.. Copyright (C) 2023, BRAIN-LINK UG (haftungsbeschränkt). All Rights Reserved.
+   SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-ScanHub-Commercial
+
+=========================
+Quickstart (5–10 minutes)
+=========================
+
+This quickstart gets you running **locally** using Docker Compose.
+
+Prerequisites
+=============
+
+- Docker and Docker Compose installed on your machine.
+- Internet connection to build/pull images.
+
+Steps
+=====
+
+1. **Clone the repository**::
+
+   git clone https://github.com/brain-link/scanhub.git
+   cd scanhub
+
+2. **Build images**
+
+   **Option A (recommended for development)** – build with local base image::
+
+     cd services/base
+     docker build -t scanhub-base .
+     cd ../..
+     docker compose build --build-arg BASE_IMG=scanhub-base:latest
+
+   **Option B (convenience)** – use base image from GHCR::
+
+     docker compose build
+
+3. **Start ScanHub**::
+
+   docker compose up --detach
+
+4. **Open the UI**
+
+   Navigate to **https://localhost/**. 
+   Your browser will warn about the self-signed certificate (development default) – continue anyway.
+
+5. **Create the first user**
+
+   If the database is empty, ScanHub prompts you to create an admin-level user. Use a **strong password (≥12 chars)**.
+
+6. **Stop ScanHub**::
+
+   docker compose down
+
+Next steps
+==========
+
+- See :doc:`using_scanhub` to plan an exam, run a simulation, and view results.
+- See :doc:`troubleshooting` if you hit Docker or HTTPS issues.

docs/source/_getting_started/troubleshooting.rst

@@ -0,0 +1,34 @@
+.. Copyright (C) 2023, BRAIN-LINK UG (haftungsbeschränkt). All Rights Reserved.
+   SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-ScanHub-Commercial
+
+========================
+Troubleshooting & FAQs
+========================
+
+Browser warns about HTTPS
+=========================
+
+**Symptom:** Browser shows a certificate warning on https://localhost/.
+
+**Cause:** Development uses a self-signed certificate.
+
+**Fix:** Proceed in development, or configure a real certificate for production (see :doc:`deployment`).
+
+I changed code but nothing updates
+==================================
+
+**Symptom:** UI or services still behave like before a change.
+
+**Cause:** Containers need a rebuild after structural/library changes.
+
+**Fix:** Rebuild and restart::
+
+  docker compose build
+  docker compose up -d
+
+Docker Compose command not found
+================================
+
+**Symptom:** Script uses ``docker compose`` but your system has ``docker-compose`` (hyphenated).
+
+**Fix:** Use the command available on your system, or install the latest Docker Compose.

docs/source/_getting_started/using_scanhub.rst

@@ -0,0 +1,58 @@
+.. Copyright (C) 2023, BRAIN-LINK UG (haftungsbeschränkt). All Rights Reserved.
+   SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-ScanHub-Commercial
+
+=============================
+Using the ScanHub Web UI
+=============================
+
+All user interaction with **ScanHub** happens through its **Web UI**, a browser-based interface that provides access to the complete imaging workflow — from planning to viewing results.
+
+Accessing the Web UI
+====================
+After starting the system with ``docker compose up -d``, open your browser at:
+
+   **https://localhost/**
+
+For production deployments, replace *localhost* with your configured domain.
+
+First login
+===========
+When the system runs for the first time, the Web UI will prompt you to create an administrator account.  
+Use a strong password (at least 12 characters). You can later add standard user accounts under *Settings → User Management*.
+
+Typical workflow
+================
+
+1. **Login**  
+   Sign in using your administrator or user credentials.
+
+2. **Plan an exam**  
+   Define a new exam by specifying the subject, study details, and imaging sequence.  
+   (In the development setup, simulated devices and test sequences are preconfigured.)
+
+3. **Run the acquisition or simulation**  
+   Start the exam. Data will be acquired or simulated and processed automatically in the background.  
+   No additional configuration or manual processing steps are required.
+
+4. **Inspect results**  
+   Once processing completes, you can view and download reconstructed DICOM images directly from the Web UI.
+
+5. **Manage data**  
+   Review previous exams, manage subjects, and organize studies from the dashboard.
+
+Monitoring
+==========
+To observe background activity or troubleshoot technical issues, you can follow the logs of all running services::
+
+   docker compose logs -f
+
+Shutdown
+========
+To stop all containers and services safely::
+
+   docker compose down
+
+Notes
+=====
+- The Web UI encapsulates all backend functionality — users never interact with the individual services directly.  
+- For development and debugging, internal microservices reside under the ``services/`` directory, but they remain transparent to end users.

docs/source/_getting_started/what_is_scanhub.rst

@@ -0,0 +1,46 @@
+.. Copyright (C) 2023, BRAIN-LINK UG (haftungsbeschränkt). All Rights Reserved.
+   SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-ScanHub-Commercial
+
+====================
+What is ScanHub?
+====================
+
+**ScanHub** is an open-source, cloud-oriented **multimodal acquisition platform** for medical imaging workflows (currently focused on **MRI**). It integrates device management, exam planning, sequence management, workflow execution, and cloud-based reconstruction/processing into one coherent platform and UI.
+
+Repository layout
+=================
+
+- **Microservices** (backend): ``services/*``  
+  - ``services/device-manager`` — register/select devices and handle device comms  
+  - ``services/exam-manager`` — plan, schedule, track, and review exams  
+  - ``services/mri/sequence-manager`` — manage MRI sequences (inspect, configure)  
+  - ``services/patient-manager`` — patient and study metadata  
+  - ``services/user-login-manager`` — authentication and session handling  
+  - ``services/workflow-manager`` — orchestration of reconstruction/processing jobs
+- **Web UI** (frontend): ``scanhub-ui`` — single entry point for operators/researchers
+
+Why it exists
+=============
+
+Traditional MRI console workflows are costly to scale, hard to extend, and siloed. ScanHub shifts reconstruction and processing tasks into a cloud-ready, modular architecture, enabling:
+
+- **Scalability & flexibility** – heavy workloads run in the cloud; services can be swapped or extended.
+- **Open innovation** – avoid vendor lock-in; build on transparent, community-driven components.
+- **Collaboration & sharing** – central data handling and standard formats support teamwork.
+- **Interoperability** – open interfaces across device, exam, and sequence managers.
+
+Key building blocks
+===================
+
+- **Device Manager** (``services/device-manager``)  
+- **Exam Manager** (``services/exam-manager``)  
+- **MRI Sequence Manager** (``services/mri/sequence-manager``)  
+- **Patient Manager** (``services/patient-manager``)  
+- **User Login Manager** (``services/user-login-manager``)  
+- **Workflow Manager** (``services/workflow-manager``)  
+- **Web UI** (``scanhub-ui``)
+
+Licensing
+=========
+
+ScanHub is **dual-licensed**: GPLv3 **or** a commercial license from BRAIN-LINK UG. Choose GPLv3 for open-source use; choose commercial to embed without copyleft obligations and to obtain premium services.