install: Fresh install and smoke-test coverage tracker

[alteixeira20]

Prerequisites

• I searched open issues and this has not already been proposed.
• I searched discussions and this is not already being debated there.
• This is a concrete, actionable proposal, not a vague "it would be nice if..." request.

Area

Testing / CI

Problem or Motivation

Odysseus needs a clear fresh-install smoke-test contract.

The roadmap calls for fresh-install smoke coverage across Docker, native Linux, macOS, Windows, and WSL, but there is no single tracker that defines what "fresh install works" means for each supported environment.

Current state is fragmented:

• Windows has a focused smoke-test issue: Add Windows fresh-install smoke test for launch-windows.ps1 #2789.
• Default Docker has at least one confirmed clean-install degradation: FastEmbed fails in Docker: empty FASTEMBED_CACHE_PATH → os.makedirs('') → vector features degrade #3433.
• Some older install-related reports contain useful evidence, but are too broad, stale, duplicated, or mixed with provider-specific setup problems.
• Current CI has syntax checks and advisory pytest, but does not prove that clean installs can start and reach a usable baseline state across supported environments.

Without a shared smoke contract, contributors can keep fixing individual startup issues without knowing what baseline behavior the project expects.

This makes fresh-install reliability hard to review, hard to reproduce, and hard to improve safely.

Proposed Solution

Use this issue as the parent tracker for fresh-install and smoke-test coverage.

The goal is to define small, repeatable smoke contracts for each supported environment, then add focused child issues and PRs for each slice.

Initial target environments:

Environment	Goal	Status
Docker Compose	Clean clone can start, UI/API become reachable, optional services degrade clearly	Needs child issue / validation
Native Linux	Clean clone can install dependencies and start a usable server	Needs child issue
macOS	Clean clone can install dependencies and start a usable server	Needs child issue
Windows native	Launcher/smoke checks verify prerequisites and app availability	Existing issue: #2789
WSL / Git Bash	Launcher/path behavior is validated separately from native Windows	Needs child issue

Minimum smoke contract:

• start from a clean clone or clearly documented clean environment;
• install or verify required dependencies for that environment;
• start the application or verify an already-running server only when the smoke mode explicitly says so;
• confirm a baseline HTTP endpoint is reachable, such as /api/version or another agreed health endpoint;
• confirm the UI can become available when applicable;
• confirm optional services do not block baseline startup;
• confirm degraded optional services are reported clearly instead of failing silently;
• record exact commands and expected output.

Initial child / linked issues:

• Add Windows fresh-install smoke test for launch-windows.ps1 #2789 - Windows-native smoke-test slice.
• FastEmbed fails in Docker: empty FASTEMBED_CACHE_PATH → os.makedirs('') → vector features degrade #3433 - Default Docker FastEmbed cache-path issue that silently degrades vector functionality.

Prior-art / evidence, not direct children yet:

• Docker startup can block UI while initializing local embeddings/RAG #2140 - contains useful Docker UI-readiness evidence, but currently mixes startup blocking with an unrelated SearXNG port configurability request.
• PR 🍎 [macOS] clean install smoke test — bug fixes, PWA icons, Ollama guide + UX fixes #137 - contains useful macOS clean-install observations, but was closed without merge and bundled unrelated documentation, UI, icon, calendar, and provider changes.

Potential future child issues:

• Define the canonical smoke contract and accepted smoke modes.
• Add Docker Compose clean-clone smoke validation.
• Add native Linux clean-clone smoke validation.
• Add macOS clean-clone smoke validation.
• Refine the Windows smoke script so its scope is explicit.
• Add WSL / Git Bash launcher validation.
• Add optional-service degraded-startup validation.

Working rules:

• One platform or smoke contract per child issue.
• One behavior slice per PR.
• No broad launcher rewrites.
• No provider-specific setup requirements in the baseline smoke contract.
• No GPU benchmarking or GPU-specific provider tuning.
• No full browser E2E framework until the basic smoke contract is agreed.
• No claim of "fresh-install coverage" unless the test actually starts from a clean or clearly documented state.

Success criteria:

• Each supported environment has a documented smoke command or manual validation procedure.
• Each smoke check states whether it installs, launches, probes, or only validates prerequisites.
• Docker clean-start behavior is validated separately from optional provider configuration.
• Windows native behavior is validated separately from WSL / Git Bash.
• Optional services can fail or be unavailable without blocking the baseline app startup, unless they are explicitly required by that environment.
• Future install bugs can be routed under a clear parent instead of becoming scattered one-off reports.

Alternatives Considered

Adding each install-related issue directly to the Stabilization milestone was rejected because it would make the milestone noisy and harder to reason about.

Using #2789 as the parent was rejected because it only covers Windows native smoke checks.

Using #3433 as the parent was rejected because it is a specific Docker/FastEmbed defect, not a cross-platform smoke contract.

Using older Docker/Ollama threads as the parent was rejected because those discussions mix baseline install behavior with optional provider setup, host Ollama behavior, GPU runtime issues, and user-support details.

Prior Art / Related Issues

Directly related:

• Add Windows fresh-install smoke test for launch-windows.ps1 #2789 - Windows-native smoke-test slice.
• FastEmbed fails in Docker: empty FASTEMBED_CACHE_PATH → os.makedirs('') → vector features degrade #3433 - Default Docker FastEmbed cache-path issue affecting vector functionality.

Prior art / evidence:

• Docker startup can block UI while initializing local embeddings/RAG #2140 - Docker UI-readiness concern, but mixed with unrelated SearXNG configurability.
• PR 🍎 [macOS] clean install smoke test — bug fixes, PWA icons, Ollama guide + UX fixes #137 - macOS clean-install observations, but closed, stale, and too broad.

Explicitly not treated as direct children at this time:

• Docker installs ship with broken embeddings: empty FASTEMBED_CACHE_PATH defeats the code default #3817 - duplicate of FastEmbed fails in Docker: empty FASTEMBED_CACHE_PATH → os.makedirs('') → vector features degrade #3433.
• ChromaDB Embedded Mode Unsupported Despite README Guidance (Windows, No Docker) #3218 - ChromaDB architecture / support-mode expectation, not a baseline smoke contract.
• host.docker.internal shows "Ollama ready to test" when endpoint is unreachable (false positive) #3648 - provider probing / host Ollama feedback.
• Docker on Windows: entrypoint re-chowns multi-GB caches every boot #3846 - repeated-start performance and ownership behavior.
• Fresh docker Install: local Ollama problem #1292 - drifted Docker/Ollama/provider-support thread.
• Windows: scripts call python3 but Windows only installs python #2341 - duplicate Windows python/python3 issue.
• docs: Windows Docker + Ollama connection guide missing #3564 - optional Ollama setup documentation.

Are you willing to implement this?

Yes. I can help organize the tracker, validate existing candidate issues, and contribute small smoke-test slices where appropriate.

Current Next Step

Agree on the minimum smoke contract first.

After that, the first practical slices should be:

1. refine/validate the Windows smoke-test work in Add Windows fresh-install smoke test for launch-windows.ps1 #2789 / PR tests: add Windows smoke test for launch-windows.ps1 #2719;
2. validate the canonical Docker FastEmbed issue FastEmbed fails in Docker: empty FASTEMBED_CACHE_PATH → os.makedirs('') → vector features degrade #3433 and its competing fixes;
3. open focused child issues for Docker Compose, native Linux, macOS, and WSL once the smoke contract is clear.

[alteixeira20]

Proposed smoke contract v0:

A fresh-install smoke check should prove only the minimum baseline needed to say that Odysseus can start and is reachable in that environment. It should not prove every optional integration, provider, or feature.

Baseline success

A smoke check should document:

• the environment being tested;
• the clean-start assumption, for example clean clone, clean container volume, fresh venv, or documented existing runtime;
• exact commands used;
• expected successful output;
• expected failure/degraded output for optional services.

Minimum required result:

• dependencies are installed or verified;
• the app can start, or the smoke mode explicitly states it only checks prerequisites;
• a baseline endpoint is reachable;
• the UI/API does not remain blocked by optional service initialization;
• optional unavailable services degrade clearly instead of silently breaking startup.

Suggested readiness endpoint

Initial candidate:

• /api/version

Reason:

• simple;
• already used by existing Windows smoke work;
• does not require login;
• good enough for first-level process/API reachability.

Open question:

• Should the canonical smoke endpoint eventually become a dedicated health/readiness endpoint instead?

Required distinction between smoke modes

Each smoke check should clearly state which mode it implements:

1. prerequisite smoke

   • checks tools, paths, Python, Docker, scripts, repo structure;
   • does not claim the app starts.

2. launch smoke

   • starts the app from the target environment;
   • verifies the app becomes reachable.

3. degraded-startup smoke

   • starts with optional services missing or unreachable;
   • verifies baseline app startup still succeeds.

4. provider smoke

   • tests optional providers;
   • out of scope for the baseline install contract unless explicitly split later.

Initial platform slices

Proposed first child issues:

1. Docker Compose clean-clone smoke

   • verify default compose starts;
   • verify UI/API reachability;
   • verify optional embeddings/RAG failures do not silently degrade without visibility.

2. Windows native smoke refinement

   • build on Add Windows fresh-install smoke test for launch-windows.ps1 #2789 / PR tests: add Windows smoke test for launch-windows.ps1 #2719;
   • clarify whether it is prerequisite-only or launch-capable;
   • avoid calling it full fresh-install coverage unless it actually launches from a clean state.

3. Linux native clean-clone smoke

   • define fresh venv behavior;
   • verify startup and /api/version.

4. WSL / Git Bash launcher smoke

   • separate path/shell behavior from native Windows.

5. macOS native clean-clone smoke

   • use PR 🍎 [macOS] clean install smoke test — bug fixes, PWA icons, Ollama guide + UX fixes #137 only as prior art;
   • avoid bundling docs, icons, providers, or UI changes into the smoke slice.

Collaboration rule

Before creating new issues or PRs under this tracker, we should check whether existing contributor work already covers the same slice.

Preferred order:

1. reuse an existing canonical issue if it exists;
2. ask for changes on an existing focused PR if it is close;
3. split or redirect broad/stale work when needed;
4. open new child issues only when no suitable canonical issue exists;
5. avoid competing PRs unless the existing implementation is abandoned, too broad, or technically unsound.

This tracker should coordinate contributor work, not replace it.

Explicit exclusions

Not part of the baseline smoke contract:

• GPU runtime validation;
• Ollama/provider configuration;
• provider endpoint probing;
• ChromaDB architecture decisions;
• restart-time cache ownership optimization;
• full browser E2E coverage;
• onboarding UX;
• broad launcher rewrites.

Those can become separate work only after the baseline contract is stable.

[TimHoogervorst]

If not already, i can do a smoke tests for both Windows (docker & uvicorn) and Linux. Will separate my findings and come back to you. This Sunday most likely have the time to perform these.

What I'll check (per platform):

Install & startup

• Clean clone / fresh pull, follow README instructions exactly
• docker compose up (or native uvicorn) starts without errors
• No missing .env keys or silently degraded services without warning

Core API

• /api/version returns valid JSON
• Health/readiness endpoints respond

UI surfaces (click-through, one interaction each)

• Models - Add model endpoint (will try Deepseek & OpenAI)
• Chat — send a message, get a response
• Settings panel — loads, toggle something, save sticks
• Calendar — renders without crash
• Notes — create, save, reopen
• Email — inbox renders
• Gallery / Documents / Library — pages load
• Deep Research will run no errors * Only errors in the log about SearXNG too many requests or denied requests (which is a bit expected)
• Cookbook / Model serving — page loads, no console errors
• Memory / Skills panel — renders
• Dark mode toggle — flips

Graceful degradation

• Optional services (SearXNG, ChromaDB, etc.) missing → clear warning, not a crash

I could dive into a bit more deeper functions, but will try to keep it in the scope of this issue

Ran latest Dev build
commit: 9d7a3d6

Ran a clean install both in Linux/Windows, and ran App with docker compose up -d --build

Every action above was performed without any error (expect for expected SearXNG search errors)

[alteixeira20]

Thanks, this is useful validation.

I would keep the tracker split into two layers so the scope stays clear:

1. Baseline smoke evidence

   • platform and install mode;
   • exact commit;
   • clean-start assumption;
   • exact commands used;
   • whether /api/version or another readiness endpoint responded;
   • whether the app/UI became reachable;
   • whether optional services degraded clearly instead of blocking startup.

2. Extra manual click-through evidence

   • chat, settings, notes, calendar, documents, model setup, memory/skills, etc.

The second layer is valuable, but I would not make it part of the minimum fresh-install contract yet. Otherwise the smoke contract becomes too broad and harder to automate or repeat.

For the evidence you already gathered, the most useful follow-up would be to split it by environment:

• Windows Docker
• Windows native / uvicorn
• Linux Docker
• Linux native / uvicorn, if tested separately

For each one, please include the exact OS/version, commands, whether volumes were clean, the endpoint response used for readiness, and any relevant logs around optional services like SearXNG or ChromaDB.

That would make the results reusable as baseline evidence and help us decide which child issue or PR should come first.