191 lines
6.3 KiB
Markdown
Executable File
191 lines
6.3 KiB
Markdown
Executable File
# Installation Guide
|
|
|
|
SysDeck can be installed four ways. Pick the one that matches your distribution and operational model.
|
|
|
|
Author: **Jeremy Anderson** · <https://dcos.net>
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
All install paths require:
|
|
|
|
- **Cockpit** ≥ 239 (`cockpit-bridge --version` to verify)
|
|
- **Python** ≥ 3.9 (`python3 --version`)
|
|
- Root or sudo access for system-wide install
|
|
|
|
Recommended backend tools (the plugin fails closed when any are absent, but the dashboard is more useful with all present):
|
|
|
|
| Tool | Module(s) | Install (Fedora/RHEL) |
|
|
|------|-----------|------------------------|
|
|
| `podman` | Containers | `dnf install podman` |
|
|
| `nftables` | Firewall | `dnf install nftables` |
|
|
| `lynis` | Integrity | `dnf install lynis` (EPEL) |
|
|
| `iproute2` | Netsec | `dnf install iproute` |
|
|
| `kubectl` | Mesh | See Kubernetes docs |
|
|
| `util-linux` | Vault | `dnf install util-linux` |
|
|
| `kata-runtime` | Kata | `dnf install kata-runtime` |
|
|
| `fwupd` | Firmware | `dnf install fwupd` |
|
|
| `tpm2-tools` | Firmware | `dnf install tpm2-tools` |
|
|
| `mkosi` (Arch) / `vmdb2` (Debian) | Builder | Arch: `pacman -S mkosi` · Debian: `apt install vmdb2` · Fedora: `dnf install mkosi` |
|
|
| `opensc` | Auth | `dnf install opensc` |
|
|
| `pcsc-lite` | Auth | `dnf install pcsc-lite` |
|
|
| `prometheus` | Prometheus | `dnf install prometheus` |
|
|
| `grafana` | Grafana | See Grafana docs |
|
|
| `jellyfin` | Jellyfin | `dnf install jellyfin` · Arch: `pacman -S jellyfin` · Debian: `apt install jellyfin` |
|
|
| `photoprism` (or `piwigo` / `lychee` / `librephotos`) | Photos | `yay -S photoprism` · Debian: see PhotoPrism docs |
|
|
| `ceph` (or `glusterfs` / `moosefs` / `beegfs` / `orangefs`) | Remote FS | `dnf install ceph` · Arch: `pacman -S ceph` · Debian: `apt install ceph` |
|
|
|
|
---
|
|
|
|
## Option A — Make (manual install)
|
|
|
|
Best for operators who want a single-command install from source.
|
|
|
|
```bash
|
|
tar xjf sysdeck-0.0.35.tar.bz2
|
|
cd sysdeck-0.0.35
|
|
sudo make install
|
|
sudo systemctl restart cockpit.socket
|
|
```
|
|
|
|
**What it does:**
|
|
- Copies `manifest.json`, `index.html`, `suite.js`, `suite.css`, `logo.svg` to `/usr/share/cockpit/sysdeck/`.
|
|
- Copies `src/*.js` and `src/modules/*.js` to `/usr/share/cockpit/sysdeck/src/` (runtime dynamic imports).
|
|
- Copies `bridge/*.py` and `bridge/modules/*.py` to `/usr/lib/sysdeck/bridge/`.
|
|
- Copies `README.md` and `LICENSE` to the plugin root.
|
|
|
|
**Uninstall:**
|
|
```bash
|
|
sudo make uninstall
|
|
sudo systemctl restart cockpit.socket
|
|
```
|
|
|
|
---
|
|
|
|
## Option B — RPM (Fedora / RHEL / CentOS)
|
|
|
|
Best for production deployments that want package-manager lifecycle.
|
|
|
|
```bash
|
|
# Build the RPM from the tarball
|
|
rpmbuild -bb packaging/sysdeck.spec \
|
|
-D "_sourcedir $PWD"
|
|
|
|
# Install
|
|
sudo dnf install ~/rpmbuild/RPMS/noarch/sysdeck-0.0.35-1.*.noarch.rpm
|
|
sudo systemctl restart cockpit.socket
|
|
```
|
|
|
|
**What the RPM does:**
|
|
- Installs the plugin under `/usr/share/cockpit/sysdeck/`.
|
|
- Installs the Python bridge under `/usr/lib/sysdeck/bridge/`.
|
|
- `Recommends:` the backend tools so dnf suggests them on install.
|
|
- `%post` and `%postun` scriptlets restart `cockpit.socket` automatically.
|
|
|
|
**Uninstall:**
|
|
```bash
|
|
sudo dnf remove sysdeck
|
|
```
|
|
|
|
---
|
|
|
|
## Option C — pip
|
|
|
|
Best for Python-shop environments that prefer pip over RPM.
|
|
|
|
```bash
|
|
tar xjf sysdeck-0.0.35.tar.bz2
|
|
cd sysdeck-0.0.35
|
|
sudo pip3 install packaging/
|
|
sudo systemctl restart cockpit.socket
|
|
```
|
|
|
|
**What it does:**
|
|
- `setup.py` declares `data_files` for the cockpit plugin root and the Python bridge location.
|
|
- Pip lays them out under the system paths (`/usr/share/cockpit/...` and `/usr/lib/...`).
|
|
|
|
**Uninstall:**
|
|
```bash
|
|
sudo pip3 uninstall sysdeck
|
|
sudo rm -rf /usr/share/cockpit/sysdeck
|
|
sudo systemctl restart cockpit.socket
|
|
```
|
|
|
|
Note: pip's `data_files` are not tracked for uninstall on all platforms. The `rm -rf` above is the safe path.
|
|
|
|
---
|
|
|
|
## Option D — staged overlay (for image builds)
|
|
|
|
Best for building container images or kickstart-installed systems where you want to stage files into a directory and then copy them into the image.
|
|
|
|
```bash
|
|
tar xjf sysdeck-0.0.35.tar.bz2
|
|
cd sysdeck-0.0.35
|
|
make install DESTDIR=/tmp/overlay
|
|
# /tmp/overlay now contains:
|
|
# /tmp/overlay/usr/share/cockpit/sysdeck/
|
|
# /tmp/overlay/usr/lib/sysdeck/bridge/
|
|
```
|
|
|
|
Copy `/tmp/overlay/usr/*` into your image's `/usr/` and the plugin is ready.
|
|
|
|
---
|
|
|
|
## Verifying the install
|
|
|
|
After any install path, verify:
|
|
|
|
```bash
|
|
# 1. Manifest is in place
|
|
ls /usr/share/cockpit/sysdeck/manifest.json
|
|
|
|
# 2. Manifest is valid JSON
|
|
python3 -m json.tool /usr/share/cockpit/sysdeck/manifest.json
|
|
|
|
# 3. Entry HTML is in place
|
|
ls /usr/share/cockpit/sysdeck/index.html
|
|
|
|
# 4. Bridge helpers are in place
|
|
ls /usr/lib/sysdeck/bridge/
|
|
|
|
# 5. Cockpit socket is running
|
|
systemctl status cockpit.socket
|
|
```
|
|
|
|
Then open `https://<host>:9090` and look for the **SysDeck** menu entry.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Menu entry does not appear
|
|
|
|
1. Confirm `manifest.json` is valid JSON.
|
|
2. Confirm the `content` key has a `suite` entry pointing to `/index.html`.
|
|
3. Restart `cockpit.socket`: `sudo systemctl restart cockpit.socket`.
|
|
4. Check the journal: `journalctl -u cockpit -f --since "5 min ago"`.
|
|
|
|
### Panel shows "X unavailable"
|
|
|
|
Each panel calls a backend tool via `cockpit.spawn`. If the tool is absent, the panel shows an install hint. Install the missing tool (see the prerequisites table above) and click **Refresh** in the header.
|
|
|
|
### Python bridge helpers not found
|
|
|
|
The JS bridge client calls `python3 -m sysdeck.bridge.<module>`. Confirm:
|
|
|
|
1. `python3` is in the cockpit service's PATH (usually `/usr/bin/python3`).
|
|
2. The bridge package is installed at `/usr/lib/sysdeck/bridge/__init__.py`.
|
|
3. The `PYTHONPATH` includes `/usr/lib/sysdeck` (the RPM and Makefile set this; pip install does not — add a `/etc/cockpit/cockpit.conf` entry or symlink if needed).
|
|
|
|
### Content Security Policy violations
|
|
|
|
The manifest declares `content-security-policy: default-src 'self' 'unsafe-inline' 'unsafe-eval'`. If your cockpit deployment enforces a stricter policy, tighten the manifest to match. The plugin does not require `'unsafe-eval'` if you remove the dynamic `import()` calls and bundle all modules into `suite.js`.
|
|
|
|
---
|
|
|
|
## Optional: standalone Next.js dashboard
|
|
|
|
For hosts without cockpit, the Next.js dashboard variant is preserved under `nextjs-dashboard/`. See [`nextjs-dashboard/QUICKSTART.md`](../nextjs-dashboard/QUICKSTART.md) for its setup. The Next.js variant uses mock data; the cockpit plugin uses real backend calls.
|