New collaboration reconfig and enhancements

.env.example

@@ -2,9 +2,15 @@ POSTGRES_DB=omero
 POSTGRES_USER=omero
 POSTGRES_PASSWORD=omero-change-me
 OMERO_ROOT_PASSWORD=omero-root-change-me
+OMERO_USER_HABOMERO_PASSWORD=habomero-change-me
+OMERO_USER_TEST_PASSWORD=test-change-me
+OMERO_USER_WAY_MCKINSEY_PASSWORD=way-mckinsey-change-me
 OMERO_SERVER_TAG=latest
 OMERO_WEB_TAG=latest
 OMERO_WEB_PORT=4080
+# Optional LAN hostname printed by `uv run poe show-url`.
+# For mDNS on Linux, use habomero.local after configuring the host with Avahi.
+OMERO_PUBLIC_HOSTNAME=habomero.local
 # OMERO server session timing (milliseconds)
 # Default 1 hour inactivity timeout; allow up to 24h idle requests.
 OMERO_SESSIONS_TIMEOUT_MS=3600000

.gitignore

@@ -217,3 +217,6 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Local habomero configuration with credentials
+config/omero/users.yml

README.md

@@ -20,7 +20,7 @@ flowchart TD
     D --> E[Quick health check]
     E --> F[Open OMERO.web]
 
-    G[scan_dirs.yml + users.yml] --> D
+    G[scan_dirs.yml + local users.yml] --> D
     H[Source image directories] --> D
     I[Browser at /webclient] --> F
 ```
@@ -36,41 +36,55 @@ flowchart TD
 uv sync --group dev
 ```
 
-3. Create environment file:
+3. Create local configuration files from templates:
 
 ```bash
 cp .env.example .env
+cp config/omero/users.example.yml config/omero/users.yml
 ```
 
-4. Configure scan directories (project-relative only):
+4. Set local secrets and user access:
+
+```bash
+vim .env
+vim config/omero/users.yml
+```
+
+`config/omero/users.yml` is ignored by Git. Keep real OMERO user passwords in
+`.env` and reference them from `users.yml` with `password_env`.
+
+5. Configure and mount scan directories:
 
 ```bash
 vim config/omero/scan_dirs.yml
 uv run poe scan-dirs
 ```
 
-5. Prepare local directories:
+Every path in `scan_directories` must exist locally before `scan-dirs` or
+startup tasks run. For SMB shares, mount them at the local paths configured in
+`config/omero/scan_dirs.yml`.
+
+6. Prepare local directories:
 
 ```bash
 uv run poe provision
 ```
 
-6. Start stack:
+7. Start stack:
 
 ```bash
 uv run poe up
 ```
 
 `poe up` prints both localhost and local-network URLs for copy/paste sharing.
 
-7. Configure user access allowlist:
+8. Sync the configured OMERO users and groups:
 
 ```bash
-vim config/omero/users.yml
 uv run poe sync-users
 ```
 
-8. Validate and inspect:
+9. Validate and inspect:
 
 ```bash
 uv run poe validate
@@ -79,9 +93,53 @@ uv run poe logs
 ```
 
 OMERO.web is exposed at `http://localhost:${OMERO_WEB_PORT:-4080}`.
+For a Linux server on a local network, see [LAN hostname setup](#lan-hostname-setup)
+to make the service reachable as `habomero.local` or `habomero`.
 
 All `poe` operations are restricted to project-root execution and fail if run from another directory.
 
+## LAN hostname setup
+
+The repo can print a hostname URL via `OMERO_PUBLIC_HOSTNAME`, but the hostname
+itself has to be provided by the Linux host or your network.
+
+For mDNS on a Linux server, which gives most macOS/Linux clients
+`http://habomero.local:${OMERO_WEB_PORT:-4080}/webclient/`:
+
+```bash
+sudo hostnamectl set-hostname habomero
+sudo apt-get update
+sudo apt-get install -y avahi-daemon
+sudo systemctl enable --now avahi-daemon
+```
+
+Allow OMERO.web and mDNS through the host firewall if one is enabled:
+
+```bash
+sudo ufw allow 4080/tcp
+sudo ufw allow 5353/udp
+```
+
+Then set this in the server's local `.env`:
+
+```bash
+OMERO_PUBLIC_HOSTNAME=habomero.local
+```
+
+For the shorter `http://habomero:${OMERO_WEB_PORT:-4080}/webclient/`, configure
+your router/DHCP DNS to resolve `habomero` to the server's LAN IP, or add a
+hosts-file entry on each client:
+
+```text
+192.168.1.50 habomero
+```
+
+After DNS or mDNS is configured, run:
+
+```bash
+uv run poe show-url
+```
+
 ## Operations
 
 - One-command local run:
@@ -95,10 +153,19 @@ scan directory (`OMERO_SCAN_DIR` -> `/scan/inbox`) using the first user in
 `config/omero/users.yml`.
 Imports mirror directory hierarchy in OMERO Folders (folders map to folders,
 images map to images). If `shared_group` is set in `config/omero/scan_dirs.yml`,
-all configured users are joined to that group and imported content is visible
-to all group members. Set `import_mode: inplace` in
+configured users are joined to that group by default and imported content is
+visible to all group members. Set `join_shared_group: false` on restricted
+users that should not see shared content. Set `import_mode: inplace` in
 `config/omero/scan_dirs.yml` to avoid duplicate storage by importing file
 references instead of copying pixel data.
+`config/omero/users.yml` is local-only and ignored by Git; commit changes to
+`config/omero/users.example.yml` instead, and use `password_env` entries with
+real password values in `.env`.
+Scan roots may also be configured as mappings with `path` and `group`; imports
+for that root run in the configured OMERO group instead of the global shared
+group. Set `delete_omero_missing_files: true` to delete tracked OMERO Images
+when their source files are no longer present after a successful source-root
+scan. This only deletes OMERO records, not source files.
 
 - Production-style full-dataset parallel ingest with periodic rescan:
 

config/omero/scan_dirs.yml

@@ -2,6 +2,8 @@ allow_external_paths: true
 scan_directories:
   - ~/mnt/bandicoot/RxRx19a
   - ~/mnt/bandicoot/CFReT_subtyping_data
+  - path: ~/mnt/Way_McKinsey_Cardiac_Fibrosis
+    group: way_mckinsey_cardiac_fibrosis
 
 # Optional shared OMERO group for imports. All configured users are joined
 # to this group by sync-users, and imports use this group context.
@@ -18,6 +20,11 @@ omero_folder_root: scan-root
 # - inplace: keep data at source path and import by reference (no duplication)
 import_mode: inplace
 
+# When true, imported OMERO Images are deleted if their source files are no
+# longer found during a successful scan of the configured source root. Source
+# files are never deleted by this cleanup.
+delete_omero_missing_files: true
+
 # Safety controls for high-latency/remote sources:
 # Maximum number of files to attempt in a single import-scan run.
 # Set to 0 for no cap.

config/omero/users.example.yml

@@ -0,0 +1,25 @@
+users:
+  - username: habomero
+    first_name: Habomero
+    last_name: Service
+    group: lab
+    extra_groups:
+      - way_mckinsey_cardiac_fibrosis
+    email: habomero@example.org
+    institution: Local Lab
+    password_env: OMERO_USER_HABOMERO_PASSWORD
+  - username: test
+    first_name: Test
+    last_name: User
+    group: lab
+    email: test@example.org
+    institution: Local Lab
+    password_env: OMERO_USER_TEST_PASSWORD
+  - username: way_mckinsey
+    first_name: Way McKinsey
+    last_name: Cardiac Fibrosis
+    group: way_mckinsey_cardiac_fibrosis
+    join_shared_group: false
+    email: way_mckinsey@example.org
+    institution: Local Lab
+    password_env: OMERO_USER_WAY_MCKINSEY_PASSWORD

docs/src/operations.md

@@ -4,13 +4,22 @@
 
 ```bash
 cp .env.example .env
+cp config/omero/users.example.yml config/omero/users.yml
+vim .env
+vim config/omero/users.yml
+vim config/omero/scan_dirs.yml
 uv run poe preflight
 uv run poe scan-dirs
 uv run poe provision
 uv run poe up
 uv run poe sync-users
 ```
 
+`config/omero/users.yml` is local-only and ignored by Git. Store real OMERO
+user passwords in `.env` and reference them with `password_env` entries. Every
+configured scan directory must exist locally before `scan-dirs` runs; mount SMB
+shares at the paths listed in `config/omero/scan_dirs.yml`.
+
 ## Configure scan directories
 
 Edit `config/omero/scan_dirs.yml` and keep entries project-relative (for example: `data/inbox`).
@@ -30,6 +39,43 @@ uv run poe logs
 All `poe` tasks must be run from the project root directory.
 `up` and the main `remote-run*` tasks also run `preflight` automatically.
 
+## LAN hostname setup
+
+The Docker stack exposes OMERO.web on the Linux host port configured by
+`OMERO_WEB_PORT`. To make a LAN URL such as `habomero.local` work, configure
+hostname resolution on the host or network.
+
+For mDNS on a Linux server:
+
+```bash
+sudo hostnamectl set-hostname habomero
+sudo apt-get update
+sudo apt-get install -y avahi-daemon
+sudo systemctl enable --now avahi-daemon
+sudo ufw allow 4080/tcp
+sudo ufw allow 5353/udp
+```
+
+Set the hostname printed by habomero in `.env`:
+
+```bash
+OMERO_PUBLIC_HOSTNAME=habomero.local
+```
+
+Most macOS/Linux clients can then use
+`http://habomero.local:${OMERO_WEB_PORT:-4080}/webclient/`. For bare
+`habomero`, configure router/DHCP DNS or add a hosts-file entry on each client:
+
+```text
+192.168.1.50 habomero
+```
+
+Confirm the URLs:
+
+```bash
+uv run poe show-url
+```
+
 ## Safe restart without deleting data
 
 Use this when recovering an existing OMERO stack after an unclean shutdown or
@@ -77,13 +123,20 @@ IMPORT_WORKERS=4 uv run poe import-remote-safe-continuous-parallel-full
 
 ## Configure user access allowlist
 
-Edit `config/omero/users.yml` and define approved user accounts.
+Edit the local-only `config/omero/users.yml` and define approved user accounts.
+Use `password_env` entries and set the real password values in `.env`.
 Then synchronize those users into OMERO:
 
 ```bash
 uv run poe sync-users
 ```
 
+Users are joined to `shared_group` by default when it is configured in
+`config/omero/scan_dirs.yml`. Set `join_shared_group: false` for a restricted
+account, and use `extra_groups` for service/import users that need access to
+per-root import groups. A scan directory entry may be a mapping with `path` and
+`group` to import that root into a separate OMERO group.
+
 ## Backup
 
 ```bash