DOCSEARCHbyAlgolia
Submit Docs

Komari Server Monitoring and Control

repository·main·Indexed 26 days ago

https://github.com/komari-monitor/komari

A lightweight, self-hosted server monitoring and control tool featuring a web-based dashboard and a lightweight agent for data collection. It includes a JSON-RPC 2.0 internal architecture for frontend services, a declarative ACL system for permission management, and a CLI for administrative tasks such as password resets and 2FA management. Supports deployment via Docker, binary, source, or one-click methods like Rainyun and 1Panel.

Tokens
3.6K
Snippets
7
Records
32
Agent score
91%

What's inside Komari

  1. Overview of Komari monitoring tool

    main

    Komari is a lightweight, self-hosted server monitoring tool designed for efficient server performance monitoring. It provides a web interface for viewing server status and utilizes a lightweight agent to collect data.

    Note on Security and Usage: Komari is intended only for systems you own or are authorized to administer. On Windows, when remote control is enabled, the client displays a notification at each user login to remind the user that Komari is remote control software.

  2. Overview of Komari

    main

    Komari is a lightweight, self-hosted server monitoring tool designed for simple and efficient performance monitoring. It allows users to view server status through a Web interface and collects data using a lightweight Agent.

    Key Features:

    • Lightweight & Efficient: Low resource consumption suitable for various server scales.
    • Self-hosted: Provides full control over data privacy with simple deployment.
    • Web Interface: Features an intuitive monitoring dashboard.

  3. Understand the RPC2 Internal Architecture

    main
    Komari uses a JSON-RPC 2.0 implementation for its frontend services. All external interfaces (REST, WebSocket, or internal calls) are unified into a single pipeline that flows through a Dispatch layer for site verification and namespace permission validation before reaching the registered RPC handlers.

  4. Build and integrate the Komari frontend

    main

    To use a custom or updated frontend with the Komari backend, you must build the static files from the dedicated frontend repository and copy them into the backend's public directory.

    Steps:

    1. Clone the frontend repository: https://github.com/komari-monitor/komari-web.
    2. Build the static files using npm install and npm run build.
    3. Copy the generated dist directory contents to web/public/defaultTheme/dist in the backend repository.
    4. (Optional) Copy komari-theme.json to web/public/defaultTheme to enable default theme metadata and managed configuration.
    5. Crucial: Verify that web/public/defaultTheme/dist/index.html exists before proceeding to build the backend.
    # Clone frontend repository
git clone https://github.com/komari-monitor/komari-web
cd komari-web

# Install dependencies and build
npm install
npm run build

# Copy frontend assets into the backend embed directory
# Replace /path/to/komari/ with your actual backend repository path
mkdir -p /path/to/komari/web/public/defaultTheme/dist
cp -r dist/* /path/to/komari/web/public/defaultTheme/dist/
cp komari-theme.json /path/to/komari/web/public/defaultTheme/

  5. Deploy Komari via Container Cloud or 1Panel

    main

    Komari can be deployed quickly using one-click cloud services or application stores:

    • Rainyun Cloud Apps: Available for approximately CNY 4.5/month.
    • 1Panel App Store: Navigate to App Store -> Utility Tools -> Komari to install.

    For manual installation methods including Docker, binary files, source builds, and update instructions, refer to the official Installation Guide.

  7. Deploy Komari via One-click methods

    main

    You can deploy Komari using the following one-click methods:

    • Rainyun: Available via the Rainyun app store.
    • 1Panel App Store: Navigate to App Store > Utilities > Komari within the 1Panel interface to install.

  8. Security and Usage Warning

    main

    ⚠️ WARNING

    Komari is a self-hosted monitoring/control program and should only be deployed on systems you own or have authorized management over.

    • Unauthorized Use: Do not weaponize Komari or engage in unauthorized deployment, access, persistence, command execution, or other abusive behaviors.
    • Windows Remote Control: When remote control is enabled on Windows, the client will trigger a Windows notification every time a user logs in to inform them that Komari is a remote control software.
    • Responsibility: Users assume all responsibility for deployment and use. Developers are not liable for unauthorized or abusive actions.

  9. Call RPC methods from a Gin REST handler

    main

    If you are migrating a traditional REST endpoint to use the RPC layer, use jsonrpc.CallFromGin. This ensures the request reuses the same permission and audit context as standard RPC calls.

    func GetClient(c *gin.Context) {
    resp := jsonRpc.CallFromGin(c, "admin:getClient", map[string]any{"uuid": c.Param("uuid")})
    if resp.Error != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"status": "error", "message": resp.Error.Message})
        return
    }
    c.JSON(http.StatusOK, resp.Result)
}

  10. Register an RPC Method

    main

    To add a new RPC method, use jsonrpc.RegisterWithGroupAndMeta. This allows you to attach metadata like summaries and parameter definitions for documentation or discovery purposes.

    Handler Signature: An RPC handler must return (any, *rpc.JsonRpcError).

    • Success: (result, nil)
    • Failure: (nil, *rpc.JsonRpcError)

    Parameter Binding: Use req.BindParams(&struct) within the handler to bind incoming JSON parameters to a local struct. This supports both named objects and positional arrays.

    func init() {
    jsonrpc.RegisterWithGroupAndMeta("addClient", rpc.RoleAdmin, adminAddClient,
        &rpc.MethodMeta{
            Name:    "admin:addClient",
            Summary: "Create a new client",
            Params:  []rpc.ParamMeta{{Name: "name", Type: "string"}},
            Returns: "{ uuid, token }",
        })
}

func adminAddClient(ctx context.Context, req *rpc.JsonRpcRequest) (any, *rpc.JsonRpcError) {
    var params struct{ Name string `json:"name"` }
    req.BindParams(&params)
    // ... business logic
    return result, nil
}

  11. Extend Komari via RPC Plugins

    main

    The pkg/rpc package provides several interfaces for plugin developers to extend the system:

    • rpc.Register(method, handler) / rpc.MustRegister: Register a new method. Note: You cannot use the rpc. prefix for custom methods.
    • rpc.Unregister(method) bool: Dynamically unregister a method and clean up metadata (useful for plugin unloading).
    • rpc.Allow(pattern, minRole): Declare declarative ACL rules.
    • rpc.RegisterNamespace(namespace, requiredRole): Set a required role for an entire namespace.
    • rpc.Invoke: Call existing methods from within your plugin.

  12. Use Declarative Route Bridges with `Bind`

    main

    The jsonrpc.Bind function in web/rpc/jsonrpc/bridge.go allows you to map RESTful GET/POST routes directly to RPC methods. This eliminates the need for manual Gin handlers for every resource.

    Parameter Assembly: Bind can combine parameters from the JSON body, URL path parameters (WithPath), and query parameters (WithQuery) into a single RPC argument set.

    Response Renderers:

    • renderStandard (Default): Returns {status:"success", message, data}.
    • WithFlat(): Flattens the result map to the top level and adds {status:"success"}.
    • WithRaw(): Outputs the result directly (useful for raw JSON agents).
    • WithMessage(msg): Returns a successful response with a specific fixed message.