dcosnet
/
SysDeck
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
SysDeck/docs/INSTALL.md

6.3 KiB
Executable File
Raw Blame History

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.

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:

sudo make uninstall
sudo systemctl restart cockpit.socket

Option B — RPM (Fedora / RHEL / CentOS)

Best for production deployments that want package-manager lifecycle.

# 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:

sudo dnf remove sysdeck

Option C — pip

Best for Python-shop environments that prefer pip over RPM.

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:

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.

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:

# 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 for its setup. The Next.js variant uses mock data; the cockpit plugin uses real backend calls.