Skip to content

Commit 44036f3

Browse files
LightheartdevsLightheartdevs
authored
Merge pull request #772 from fullstackdev0110/feat/linux-preflight-structured-diagnostics
Feat: linux preflight structured diagnostics
2 parents 0af1b79 + f627d79 commit 44036f3

14 files changed

+823
-15
lines changed

‎.github/workflows/test-linux.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,9 @@ jobs:
7474
bash tests/contracts/test-installer-contracts.sh
7575
bash tests/contracts/test-preflight-fixtures.sh
7676
77+
- name: Linux install preflight tests
78+
run: bash tests/test-linux-install-preflight.sh
79+
7780
- name: Installer Simulation Harness
7881
run: |
7982
bash scripts/simulate-installers.sh

‎dream-server/Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@ test: ## Run unit and contract tests
2424
@bash tests/contracts/test-installer-contracts.sh
2525
@bash tests/contracts/test-preflight-fixtures.sh
2626
@echo ""
27+
@echo "=== Linux install preflight ==="
28+
@bash tests/test-linux-install-preflight.sh
29+
@echo ""
2730
@echo "=== AMD/Lemonade contracts ==="
2831
@bash tests/contracts/test-amd-lemonade-contracts.sh
2932

‎dream-server/docs/EXTENSION-PR-BRANCHING.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Extension changes: branch targets (main vs resources/dev)
2+
3+
Dream Server splits **core runtime** (installer, `dream-server/` compose, CLI, shipped extensions under `dream-server/extensions/`) from the larger **extensions library** under `resources/dev/extensions-library/` (catalog of optional services, workflows, and templates).
4+
5+
Use this guide when coordinating PRs that touch extensions or integrations.
6+
7+
## Quick rules
8+
9+
| Change | Target branch | Notes |
10+
|--------|---------------|--------|
11+
| Installer, `dream-cli`, compose base files, dashboard, dashboard-api, **shipped** `dream-server/extensions/services/*` used by default installs | **main** (via normal PR flow) | Follow [EXTENSIONS.md](EXTENSIONS.md) for manifest/schema. |
12+
| Catalog-only updates: new or updated entries under **`resources/dev/extensions-library/`** (extra services, workflows, templates) | Often **`resources/dev`** or team policy for catalog branches | Does not change core install until wired by installer/catalog pipeline; coordinate with maintainers. |
13+
| Docs-only (troubleshooting, field reports) | **main** | Unless your team batches docs on a doc branch. |
14+
| **Both** core behavior and catalog | Split PRs or one PR with explicit maintainer agreement | Easier review when core and catalog are separate. |
15+
16+
## Linux / Windows parity
17+
18+
Platform-specific installer scripts (`installers/`, `dream-server/installers/windows/`) usually land on **main** with tests. Cross-platform doc additions (e.g. [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md)) should stay aligned with the same check IDs and behavior as the scripts they reference.
19+
20+
## Questions?
21+
22+
- Default extensions and schema: [EXTENSIONS.md](EXTENSIONS.md)
23+
- Installer layout: [INSTALLER-ARCHITECTURE.md](INSTALLER-ARCHITECTURE.md)

‎dream-server/docs/FIELD-INSTALL-REPORT-LINUX.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Field install report (Linux)
2+
3+
Use this template when reporting Linux install problems so maintainers can reproduce and classify issues quickly. **Do not paste secrets** (API keys, passwords, full `.env`).
4+
5+
## Environment
6+
7+
| Field | Your value |
8+
|-------|------------|
9+
| Dream Server version / git SHA | |
10+
| Install command used | e.g. `./install.sh`, `./install.sh --dry-run` |
11+
| Distribution | Paste **PRETTY_NAME** and **VERSION_ID** from `/etc/os-release` |
12+
| Kernel | Output of `uname -a` |
13+
| Architecture | e.g. `x86_64`, `aarch64` |
14+
| Install type | Bare metal / VM / cloud / WSL2 (if applicable) |
15+
16+
## Hardware
17+
18+
| Field | Your value |
19+
|-------|------------|
20+
| GPU | `lspci` line or “CPU only” |
21+
| NVIDIA | Output of `nvidia-smi` (if any) or “N/A” |
22+
| RAM | Approximate GB |
23+
24+
## Docker
25+
26+
| Field | Your value |
27+
|-------|------------|
28+
| Docker version | `docker --version` |
29+
| Compose | `docker compose version` or `docker-compose version` |
30+
| Docker info | Does `docker info` work without sudo? (yes/no) |
31+
| User in `docker` group? | (yes/no / unknown) |
32+
33+
## Structured preflight (required)
34+
35+
From the `dream-server` directory, run:
36+
37+
```bash
38+
./scripts/linux-install-preflight.sh --json
39+
```
40+
41+
Paste the **JSON output** (redact paths if needed). If the command fails, paste the **human** output:
42+
43+
```bash
44+
./scripts/linux-install-preflight.sh
45+
```
46+
47+
## Service preflight (after install)
48+
49+
If services are installed, also run:
50+
51+
```bash
52+
./dream-preflight.sh
53+
```
54+
55+
Paste the last 40 lines of output (or attach the log path printed at the end).
56+
57+
## Logs to attach (pick what applies)
58+
59+
- Installer log if referenced by the installer.
60+
- `docker compose` error from the failing command (not the entire daemon log unless asked).
61+
- For GPU issues: output of `docker info | grep -i nvidia` and relevant `nvidia-smi`.
62+
63+
## Privacy checklist
64+
65+
- [ ] Removed API keys and passwords from pasted content.
66+
- [ ] Redacted internal hostnames if required by your employer.
67+
- [ ] Confirmed no private URLs or tokens in compose overrides.
68+
69+
## Related docs
70+
71+
- [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md) — maps check IDs to fixes.
72+
- [INSTALL-TROUBLESHOOTING.md](INSTALL-TROUBLESHOOTING.md)
73+
- [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md)

‎dream-server/docs/INSTALL-TROUBLESHOOTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
This guide provides solutions for common issues encountered during the installation of Dream Server.
44

5+
For **Linux**, run `./scripts/linux-install-preflight.sh` (or `./dream-preflight.sh --install-env`) for a structured report with stable check IDs; see [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md) for ID-by-ID fixes.
6+
57
## Docker Issues
68

79
### Problem: Docker Not Installed

‎dream-server/docs/LINUX-PORTABILITY.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ Services are declared under `extensions/services/<name>/manifest.yaml` for dashb
1616

1717
1. Docker and Compose v2 work; your user can run containers (e.g. member of the `docker` group).
1818
2. `./install.sh --dry-run` finishes without errors.
19-
3. After a real install, run `./dream-preflight.sh` and `scripts/dream-doctor.sh` if you use them.
19+
3. Before or after install, run **`./scripts/linux-install-preflight.sh`** (or `./dream-preflight.sh --install-env`) for a structured environment report with stable check IDs and optional `--json` output.
20+
4. After a real install, run `./dream-preflight.sh` (service health) and `scripts/dream-doctor.sh` if you use them.
2021

21-
More context: [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
22+
More context: [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md) (ID-indexed fixes), [FIELD-INSTALL-REPORT-LINUX.md](FIELD-INSTALL-REPORT-LINUX.md) (bug report template), [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
23+
24+
Extension PRs that touch catalog vs core: [EXTENSION-PR-BRANCHING.md](EXTENSION-PR-BRANCHING.md).

‎dream-server/docs/LINUX-TROUBLESHOOTING-GUIDE.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Linux troubleshooting guide
2+
3+
Structured reference for **Linux install and runtime** issues. When you run `./scripts/linux-install-preflight.sh` or `./dream-preflight.sh --install-env`, each line uses a **check ID**. Use this document to jump from an ID to likely causes and fixes.
4+
5+
**Related:** [INSTALL-TROUBLESHOOTING.md](INSTALL-TROUBLESHOOTING.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md), [LINUX-PORTABILITY.md](LINUX-PORTABILITY.md), [FIELD-INSTALL-REPORT-LINUX.md](FIELD-INSTALL-REPORT-LINUX.md).
6+
7+
---
8+
9+
## Using the install preflight
10+
11+
From the `dream-server` directory:
12+
13+
```bash
14+
./scripts/linux-install-preflight.sh
15+
./scripts/linux-install-preflight.sh --json
16+
./scripts/linux-install-preflight.sh --json-file /tmp/preflight.json
17+
./dream-preflight.sh --install-env --json # same as linux-install-preflight.sh
18+
```
19+
20+
- **`--strict`** — exit with failure if any check is **warn** or **fail** (useful in automation).
21+
- **`--dream-root PATH`** — directory used for the disk-space probe (default: dream-server root).
22+
- **`--min-disk-gb N`** — minimum free space in GB to treat as OK (default: 15).
23+
24+
JSON output includes `schema_version`, `kind: linux-install-preflight`, `distro`, `kernel`, `checks[]`, and `summary`.
25+
26+
---
27+
28+
## Check IDs (alphabetical)
29+
30+
### CGROUP_V2
31+
32+
**Symptoms:** Warning that cgroup v2 was not detected.
33+
34+
**Typical causes:** Older kernels, unusual container hosts, or mis-mounted `/sys/fs/cgroup`.
35+
36+
**Fixes:**
37+
38+
- On normal desktop/server distros from the last several years, cgroup v2 is standard; if Docker works, you can ignore this warning.
39+
- If Docker fails with cgroup-related errors, ensure you are not mixing rootless Docker with a broken delegated cgroup setup. See your distro’s Docker documentation.
40+
41+
---
42+
43+
### COMPOSE_CLI
44+
45+
**Symptoms:** **Fail** — neither `docker compose` nor `docker-compose` works.
46+
47+
**Typical causes:** Docker Engine installed without the Compose v2 plugin; very old Docker packages; PATH issues.
48+
49+
**Fixes:**
50+
51+
- Install **Docker Compose v2** (plugin): often package `docker-compose-plugin` (Debian/Ubuntu) or equivalent.
52+
- Legacy: install standalone `docker-compose` v1 if you must (less ideal).
53+
54+
Verify:
55+
56+
```bash
57+
docker compose version
58+
# or
59+
docker-compose version
60+
```
61+
62+
---
63+
64+
### COMPOSE_FILES
65+
66+
**Symptoms:** Warning — `docker-compose.base.yml` / `docker-compose.yml` missing under the dream-server tree.
67+
68+
**Typical causes:** Running the script from the wrong directory; incomplete checkout.
69+
70+
**Fixes:**
71+
72+
- `cd` into the extracted **dream-server** directory that contains the compose files from the release or git clone.
73+
- Re-download or re-clone the repository if files are missing.
74+
75+
---
76+
77+
### CURL_INSTALLED
78+
79+
**Symptoms:** **Warn** — `curl` not in PATH.
80+
81+
**Typical causes:** Minimal container or netinst image without `curl`.
82+
83+
**Fixes:**
84+
85+
```bash
86+
# Debian/Ubuntu
87+
sudo apt update && sudo apt install -y curl
88+
89+
# Fedora
90+
sudo dnf install -y curl
91+
92+
# Arch
93+
sudo pacman -S curl
94+
```
95+
96+
The installer and many health checks expect `curl`.
97+
98+
---
99+
100+
### DISK_SPACE
101+
102+
**Symptoms:** **Warn** — low free space on `--dream-root` (or default dream-server root).
103+
104+
**Typical causes:** Small root partition; large existing Docker data; wrong path passed to `--dream-root`.
105+
106+
**Fixes:**
107+
108+
- Free space or move the Dream Server data directory to a larger volume (see installer docs for `data/` layout).
109+
- Point `--dream-root` at the filesystem you intend to use for the install.
110+
111+
---
112+
113+
### DISTRO_INFO
114+
115+
**Symptoms:** **Fail** — `/etc/os-release` missing.
116+
117+
**Typical causes:** Non-Linux environment; severely broken chroot.
118+
119+
**Fixes:**
120+
121+
- Run on a supported Linux distribution. For Windows, use the Windows installer + WSL2; for macOS, use the macOS path.
122+
123+
---
124+
125+
### DOCKER_DAEMON
126+
127+
**Symptoms:** **Fail** — `docker info` does not succeed.
128+
129+
**Typical causes:** Docker service stopped; user lacks permission to the Docker socket; rootless Docker socket not in environment.
130+
131+
**Fixes:**
132+
133+
```bash
134+
# systemd
135+
sudo systemctl start docker
136+
sudo systemctl enable docker
137+
138+
# Permission denied on /var/run/docker.sock
139+
sudo usermod -aG docker "$USER"
140+
# then log out and back in (or newgrp docker)
141+
```
142+
143+
Confirm:
144+
145+
```bash
146+
docker info
147+
docker run --rm hello-world
148+
```
149+
150+
---
151+
152+
### DOCKER_INSTALLED
153+
154+
**Symptoms:** **Fail** — `docker` command not found.
155+
156+
**Typical causes:** Docker Engine never installed; PATH not including Docker binaries.
157+
158+
**Fixes:**
159+
160+
- Install [Docker Engine](https://docs.docker.com/engine/install/) for your distro.
161+
- Ensure `/usr/bin` (or wherever `docker` lives) is on your `PATH`.
162+
163+
---
164+
165+
### KERNEL_INFO
166+
167+
**Symptoms:** Always **pass** — prints `uname -r` (informational).
168+
169+
**Note:** Use this value when comparing against [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md) or when filing bugs.
170+
171+
---
172+
173+
### JQ_INSTALLED
174+
175+
**Symptoms:** **Warn** — `jq` not installed.
176+
177+
**Typical causes:** Minimal system; skipped optional packages.
178+
179+
**Fixes:**
180+
181+
- The Dream Server installer often installs `jq` automatically when possible. You can install manually:
182+
183+
```bash
184+
sudo apt install -y jq # Debian/Ubuntu
185+
sudo dnf install -y jq # Fedora
186+
```
187+
188+
---
189+
190+
### KERNEL_INFO
191+
192+
**Symptoms:** Always **pass** with kernel version (informational).
193+
194+
**Note:** Very old kernels may be incompatible with modern Docker or NVIDIA drivers; if you hit exotic bugs, compare with [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md).
195+
196+
---
197+
198+
### NVIDIA_CONTAINER_RUNTIME
199+
200+
**Symptoms:** **Warn** — `nvidia-smi` works but Docker does not show an NVIDIA runtime.
201+
202+
**Typical causes:** NVIDIA drivers installed but [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) not configured for Docker.
203+
204+
**Fixes:**
205+
206+
- Install and configure `nvidia-container-toolkit`, then restart Docker:
207+
208+
```bash
209+
sudo nvidia-ctk runtime configure --runtime=docker
210+
sudo systemctl restart docker
211+
```
212+
213+
- Verify: `docker info | grep -i nvidia`
214+
215+
If you are intentionally **CPU-only**, you can ignore this after setting `GPU_BACKEND=cpu` in your capability/install profile.
216+
217+
---
218+
219+
## Common cross-cutting issues
220+
221+
### Firewall blocking local ports
222+
223+
If the dashboard or WebUI is unreachable from another machine, check `ufw` / `firewalld` / `iptables` for the ports in `config/ports.json` (or your `.env` overrides).
224+
225+
### SELinux / AppArmor
226+
227+
Rare compose failures can be policy-related. Check audit logs; temporarily testing with permissive profiles is diagnostic only — prefer documented volume labels and permissions.
228+
229+
### Docker BuildKit / proxy
230+
231+
Corporate proxies may require `HTTP_PROXY` / `HTTPS_PROXY` in Docker’s systemd drop-in or `~/.docker/config.json` for image pulls.
232+
233+
---
234+
235+
## Getting help
236+
237+
When opening an issue, attach a **field install report** (see [FIELD-INSTALL-REPORT-LINUX.md](FIELD-INSTALL-REPORT-LINUX.md)) and the JSON from:
238+
239+
```bash
240+
./scripts/linux-install-preflight.sh --json
241+
```
242+
243+
Redact secrets, internal hostnames, and paths you do not want to share.

0 commit comments

Comments
 (0)