Server Runner

Server Runner is a little Rust programm to run multiple web servers, check until all servers are ready via a URL that returns HTTP 200 und runs a command when all servers are ready.

Installation

Currently Server Runner is only available via Cargo. It will be also available via NPM in the near future, since NPM is available on almost any OS out there and it's much easier to publish than to many other package managers.

Installation via Cargo

cargo install server-runner

Usage

server-runner [OPTIONS]

Options

• -c, --config <FILE> - Path to configuration file (default: servers.yaml)
• -v, --verbose - Enable verbose logging
• -a, --attempts <NUMBER> - Maximum number of connection attempts per server (default: 10)
• --tui - Run the interactive control panel with live status, logs, and server controls
• -h, --help - Print help information
• -V, --version - Print version information

Example

server-runner -c config.yaml -v -a 15

Configuration File

The configuration file is written in YAML format and defines the servers to start and the command to run when all servers are ready.

Security Model

Treat configuration files as trusted executable input. Server Runner starts each servers[].command and the final command on the local machine with the same privileges as the current user. Do not run configuration files from untrusted pull requests, downloaded archives, or user submissions unless they have been reviewed.

Readiness URLs are intended for local test services. Server Runner accepts only http and https readiness URLs and does not follow redirects during readiness checks.

Server Runner captures and forwards child-process output defensively. Captured log lines are bounded in length and have control characters stripped. When output is echoed to your terminal, ANSI colour and style codes are preserved while window-title, clipboard, cursor-movement, and screen-clearing escape sequences are removed, so untrusted data flowing through a server's logs cannot manipulate your terminal.

Example Configuration

servers:
  - name: "My web server"
    url: "http://localhost:8080"
    command: "node webserver.js"
    timeout: 5  # Optional: HTTP request timeout in seconds (default: 5)
  
  - name: "API server"
    url: "http://localhost:3000/health"
    command: "python api_server.py"
    timeout: 10

command: "npm test"

Configuration Fields

servers (required): List of servers to start and monitor

Each server requires:

• name: Display name for the server
• url: HTTP or HTTPS endpoint to check for availability; redirects are not followed, and the endpoint must return a 2xx response when ready
• command: Shell command to start the server
• timeout: (optional) HTTP request timeout in seconds, from 1 to 300 (default: 5)

command (required): Command to execute when all servers are ready

How It Works

Server Runner will:

1. Start all configured servers simultaneously
2. Poll each server's URL every second until it returns HTTP 200
3. Retry up to the maximum number of attempts (default: 10, configurable with -a)
4. Execute the specified command once all servers are ready
5. Shut down all servers when the command completes or if any error occurs

If any server fails to respond with HTTP 200 after the maximum attempts, Server Runner will shut down all servers and exit with an error.