HTTP Process Wrapper

A simple microservice to wrap command line processes and expose them over HTTP using FastAPI, maybe one day it can be like supervisord but as a web service.

Installation

Make sure you have Poetry installed, then run:

poetry install

Running the Server

To start the server, use the following command:

poetry run uvicorn app.main:app

Note: when running on Windows you can't use reload because uvicorn will then use an asyncio loop implementation that does not support subprocesses.

Building with PEX

To build the project as a standalone executable (for musl and glibc) using PEX, run:

docker build . -f builder.dockerfile --target exporter --output ./dist

You can then copy the built executable into any docker image (even if it doesn't have python) and it will give you the ability to control its processes via HTTP ✨ (eg: Minecraft server management? 👀)

To make cross-platform PEX builds that don't include the python runtime/interpreter, run:

pex . -o ./dist/http-process-wrapper.pex -e app:serve

API Docs

Once the server is running, you can access the interactive API documentation at http://127.0.0.1:8000/docs

Init Processes

You can define initial processes to be started when the server launches by creating an init_procs.yaml file in the project root. The format is as follows:

- name: ping-test
  command:
    - ping
    - 8.8.8.8
- name: echo-test
  command:
    - bash
    - -c
    - echo "$var"
  env:
    var: value
- name: ls-test
  command:
    - ls
    - -ahl
  cwd: /home

Features

• Start/Stop/Restart command line processes via HTTP
• List all managed processes with their exit codes and pids
• Polling stdout and stderr of running processes
• Websocket support for realtime process output
• Send input to stdin of running processes
• Optional authentication (Bearer JWT or API Key), when it comes to JWT:
  • The server accepts any valid token signed with the configured secret and algorithm
  • You can optionally add the sub claim which sets the process owner
  • Token generation is out of scope for this project
• Gather and expose resource usage statistics (CPU, memory, etc) for all managed processes
• Define initial processes to be started on server launch via init_procs.yaml

Future Plans

• JWT scopes to restrict access to specific processes
• Kafka-like in-memory stream for multiple websocket consumers instead of fan-out approach (check in-memory-stream tag)
• Some kind of persistence