ODS
Deploy ODS Safely: Docker, GPU Paths, Ports, and Recovery
A source-backed ODS deployment guide for Linux, Windows/WSL2, macOS Apple Silicon, cloud mode, and production checks.
What you will learn
- Choose the correct ODS platform path
- Verify GPU, ports, and cloud trade-offs
- Design recovery and operations checks
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- ODS has distinct Linux, Windows/WSL2, and Apple Silicon deployment paths.
- Ports, GPU passthrough, and cloud mode change the operational contract.
- Pin releases, inspect installers, test recovery, and protect the dashboard.
Choose the platform path
ODS documents Linux/macOS shell installation, a Windows PowerShell installer that runs through Docker Desktop and WSL2, and a native Metal path for Apple Silicon. Docker must be installed and running. Pin v2.6.0 or an audited commit for a stable appliance; main is for active development and validation candidates.
Inspect the bootstrap source before running it, especially when using the hosted Linux/macOS endpoint that proxies repository main. Keep a local copy of the release receipt, installer hash, and support matrix so an upgrade can be explained or rolled back.
GPU, ports, and cloud fallback
The README separates NVIDIA/AMD/Intel paths on Linux, Docker GPU passthrough on Windows, and native Metal inference on macOS. Open WebUI is available on localhost:3000; inference endpoints vary by platform and can be overridden in `.env.example`. Test the effective ports from the host and from containers rather than assuming localhost means the same thing everywhere.
Machines without suitable hardware can use `./install.sh --cloud` with OpenAI, Anthropic, or Together APIs. Cloud mode changes the privacy and cost model, so keep it explicit in deployment metadata and add provider quotas and spend alerts.
Operate and recover
After install, run a small chat, model download, RAG query, and one optional voice or image flow. Then restart Docker, inspect service health, and verify that configuration and model manifests survive. Record logs, effective environment, GPU driver, model revision, and the exact ODS command when diagnosing a failure.
Test the documented uninstall path in a disposable environment and keep backups of configuration and user data. Port conflicts should be handled with environment overrides such as `WEBUI_PORT=9090`, not by editing generated compose files without a rollback plan.
Production gate
Treat ODS as an integrated appliance: restrict dashboard access to a trusted network, rotate secrets, pin release channels, monitor disk/GPU/container health, and rehearse recovery before storing sensitive prompts or documents. A green installation is not the same as a production SLA.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Choose a platform path and pin a release.
- 2
Verify Docker, GPU drivers, storage, and effective ports.
- 3
Run chat/RAG/media smoke tests and restart recovery.
- 4
Apply network, secret, monitoring, backup, and rollback controls.
Copy-ready example
# Linux/macOS after reviewing the pinned installer
curl -fsSL https://install.osmantic.com/ods.sh | bash
# Cloud fallback from a checked-out release
./install.sh --cloud
# Port override
WEBUI_PORT=9090 ./install.shFrequently asked questions
Can I run ODS on Windows without WSL2?
The README documents Docker Desktop with the WSL2 backend as the supported Windows path.
Where is the web UI?
Open WebUI is documented on localhost:3000; verify the release's environment file for inference ports and overrides.
Sources
- ODS README (captured 2026-08-31)Source checked 2026-08-31
- ODS repositorySource checked 2026-08-31