ogarcia/sysdweb

1. What this repo is

- sysdweb is a small Python application that exposes systemd service control through both a web UI and a REST API.

- It is intended to run locally or on a host where it can talk to the systemd daemon over its D-Bus interface.

2. Top-level runtime shape

- run.py is the likely command-line entrypoint, while sysdweb/main.py appears to hold the main startup flow.

- The app listens on a configurable host/port, defaulting to 127.0.0.1:10088, so it behaves like a self-contained local admin service rather than a distributed backend.

3. Configuration subsystem

- sysdweb/config.py is the boundary for reading runtime settings and the service registry.

- sysdweb.conf defines named service sections; each section maps a human-friendly title to a systemd unit name, and those section keys become the service IDs used in API paths.

4. HTTP server layer

- sysdweb/server.py is the request-routing layer that serves both HTML pages and API endpoints.

- The API follows a fixed pattern: /api/v1/<service>/<action> with optional journal line limits, and the server is responsible for translating requests into service operations and serializing responses.

5. systemd integration layer

- sysdweb/systemd.py is the core integration boundary to the host systemd environment.

- It is where start/stop/restart/reload/status/journal operations are executed, and the README indicates it relies on system D-Bus communication and systemd development libraries.

6. Data flow for control actions

- A request comes in through the HTTP server, the target service key is resolved from config, then the systemd layer executes the requested action.

- For control actions, the response is simple and machine-oriented: OK/Fail for mutating operations, and state strings such as active, inactive, failed, or not-found for status.

7. Journal retrieval path

- The journal action is a separate read path that returns tail lines from the service’s logs, with a default of 100 lines and optional override in the URL.

- This means the app is not only a service controller, but also a lightweight service-log viewer for systemd units.

8. Web UI layer

- sysdweb/templates/views/index.tpl and journal.tpl define the HTML views for the browser interface.

- The browser UI is complemented by sysdweb/templates/static/js/sysdweb.js and css/sysdweb.css, implying client-side interactions for triggering actions and refreshing service/journal views without manual API use.

9. Static asset boundary

- The templates/static tree contains the front-end assets only; the backend remains responsible for all actual systemd interaction.

- This keeps the presentation layer thin: it renders views and calls the same server endpoints that external clients use.

10. Deployment and operations

- systemd/sysdweb-system.service and systemd/sysdweb-user.service provide native systemd unit files for running sysdweb either as a system service or per-user service.

- This matches the app’s local-admin nature: it is itself typically launched and managed by systemd, and then manages other systemd units.

11. Packaging and distribution

- pyproject.toml plus .github/workflows/python-publish.yml indicate the project is packaged and published as a Python distribution.

- The repository is structured for installation from source or PyPI, with CI automation focused on release publication.

12. Architectural summary

- The key boundary is: HTTP/UI layer on one side, systemd D-Bus control on the other.

- The config file connects the two by defining which named services are exposed, and the server exposes those services consistently through both browser pages and a stable REST API.