MXStatus is a comprehensive system for monitoring the system status of multiple Linux machines from a centralized server.
MXStatus is composed of three main components: Client, Server, and Web 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.
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.
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.
We use Docker for easy server deployment. Follow these steps to get your server up and running:
-
Make sure you have Docker installed.
-
Clone this repository; Navigate to the project root directory.
-
Configure a private
.envfile as described in the server setup. SetMXSTATUS_ADMIN_TOKENand optionally bootstrap report/view keys and machine IDs. The published development credentials are no longer accepted. Put public deployments behind an HTTPS reverse proxy. -
Run the following command to deploy the server:
docker compose up --build -d
-
To tear down the server and remove the Docker image, run:
docker compose down --rmi all
Please refer to the Client INSTALL.md.
This section is for developers who want to contribute to the development of MXStatus.
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:
-
Create a virtual environment:
python3.12 -m venv venv source venv/bin/activate -
Install the required dependencies:
pip install -r requirements.txt
Export the server configuration, then run from the project root directory:
uv run uvicorn server.main:app --reload --port 5000 --no-access-logOnce 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.
For testing the Client component:
-
Navigate to the 'client' directory:
cd client -
Run the Client using:
python3 main.py
uv run pytest
uv run ruff check server client tests
uv run ruff format --check server client tests
node --test tests/frontend.test.cjsAfter changing dependencies, regenerate the Docker/pip requirements from the lockfile:
uv export --no-dev --no-emit-project --no-hashes --output-file requirements.txtManagement 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.
