Skip to content
mxshellPublic

About

Status Monitoring for Linux Workstations

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

MXStatus

MXStatus is a comprehensive system for monitoring the system status of multiple Linux machines from a centralized server.

System Structure

MXStatus is composed of three main components: Client, Server, and Web Client.

System Structure

Client

The Client component is installed on each Linux machine that you want to monitor. It actively periodically posts the host machine's status to the central server.

Server

The Server is deployed on a publicly accessible cloud server with a fixed IP address. It runs API endpoints to receive status updates from all clients. It also handles requests from the Web Client.

Admin Web Panel

Open /admin/ on your server to manage clients, reporting keys, view groups, and monitoring settings. The panel is bundled with FastAPI and uses your admin token for access.

Deployment

Deploy Server

We use Docker for easy server deployment. Follow these steps to get your server up and running:

  1. Make sure you have Docker installed.

  2. Clone this repository; Navigate to the project root directory.

  3. Configure a private .env file as described in the server setup. Set MXSTATUS_ADMIN_TOKEN and optionally bootstrap report/view keys and machine IDs. The published development credentials are no longer accepted. Put public deployments behind an HTTPS reverse proxy.

  4. Run the following command to deploy the server:

    docker compose up --build -d
  5. To tear down the server and remove the Docker image, run:

    docker compose down --rmi all

Install Client

Please refer to the Client INSTALL.md.

Development

This section is for developers who want to contribute to the development of MXStatus.

Setup Environment

To set up the development environment:

Use Python 3.12 or newer. With uv, run uv sync to install the locked runtime and development dependencies. Alternatively:

  1. Create a virtual environment:

    python3.12 -m venv venv
    source venv/bin/activate
  2. Install the required dependencies:

    pip install -r requirements.txt

Run Development Server

Export the server configuration, then run from the project root directory:

uv run uvicorn server.main:app --reload --port 5000 --no-access-log

Once started, open http://localhost:5000/admin/ and sign in with your configured admin token. Create a reporting key and use Connect a client to download a config.

Run Client

For testing the Client component:

  1. Navigate to the 'client' directory:

    cd client
  2. Run the Client using:

    python3 main.py

Checks

uv run pytest
uv run ruff check server client tests
uv run ruff format --check server client tests
node --test tests/frontend.test.cjs

After changing dependencies, regenerate the Docker/pip requirements from the lockfile:

uv export --no-dev --no-emit-project --no-hashes --output-file requirements.txt

Management settings, keys, client registrations, and views are stored in SQLite. Telemetry is held in memory, so run one worker only. See server setup and storage.

About

Status Monitoring for Linux Workstations

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages