diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..e19ff6d --- /dev/null +++ b/README.en.md @@ -0,0 +1,77 @@ +# Broadcast + +Control the execution of a program via web interface. + +## Description + +`broadcast` is a simple web application to control another executable program. There are +3 methods to do so: + + 1. directly, specifying the binary absolute path and all command line options + 2. via a systemd unit, specifying the `-systemd` flag (and optionally the + `-systemd-as-user` flag, to signal that the unit is a user one) + 3. controlling an already existing docker container (note: it has to be already + exinsting -although it can be paused- and have a name with the `--name` option) + +The program exposes a web interface, defaulting on `0.0.0.0:8080`, that can be specified +using the `-addr` parameter. + +## Examples + +For the sake of testing, this repository includes a simple program that prints a string +every second: [echo](./cmd/echo/). We will use it in the following examples. + +### 1. directly + +``` +broadcast /path/to/echo +``` + +### 2. systemd unit + +Assuming an already existing unit named `echo.service` + +``` +broadcast -systemd -systemd-as-user echo.service +``` + +### 3. docker container + +Assuming there already exists a docker container, started for example with + +``` +docker run --name echo --rm -ti echo +``` + +``` +broadcast -docker echo +``` + +## Develop + +The project includes a [`Makefile`](./Makefile) to ease some tasks. It is possible to +begin a developing session, first building the needed images with + +``` +make dev-build +``` + +It is then possible to launch a docker compose stack with + +``` +make dev +``` + +In order to build the artifacts (output to [bin/](./bin/)) (note that `libsystemd-dev` +is a prerequisite) + +``` +make build +``` + +## License + +GPL-v3 or following. + + + diff --git a/README.md b/README.md new file mode 100644 index 0000000..1b2f1b3 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# Broadcast + +[English version](./README.en.md) + +Per controllare l'esecuzione di un programma via web. + +## Descrizione + +`broadcast` è una semplice applicazione web per controllare un altro programma in +esecuzione. Ci sono 3 modi in cui questo può avvenire: + + 1. direttamente, specificando percorso assoluto del binario e tutte le opzioni + 2. attraverso una unit systemd, specificando l'opzione `-systemd` (e opzionalmente + `-systemd-as-user` per indicare che la unit è di tipo *user*) + 3. controllando un docker container già in esecuzione (n.b.: il container deve avere + un nome, specificato con `--name` e deve già esistere (può essere in pausa)) + +Il programma espone un'interfaccia web, di default su `0.0.0.0:8080`, controllabile con +il parametro `-addr` a riga di comando. + +## Esempi + +Per scopi di test, questa repository include un programma go che stampa una stringa ogni +secondo: [echo](./cmd/echo/). Lo useremo negli esempi successivi. + +### 1. direttamente + +``` +broadcast /path/to/echo +``` + +### 2. unit systemd + +Assumendo che esista una unit `echo.service` + +``` +broadcast -systemd -systemd-as-user echo.service +``` + +### 3. container docker + +Assumendo che già esista un container docker, lanciato ad esempio con + +``` +docker run --name echo --rm -ti echo +``` + +``` +broadcast -docker echo +``` + +## Sviluppo + +Il progetto include un [`Makefile`](./Makefile) per facilitare alcuni compiti. Si può +iniziare una sessione di sviluppo, innanzitutto facendo il build delle immagini +necessarie + +``` +make dev-build +``` + +Si può quindi lanciare uno stack docker compose così + +``` +make dev +``` + +Per fare la build degli artefatti (verranno creati in [bin/](./bin/)) (`libsystemd-dev` +è un prerequisito) + +``` +make build +``` + +## Licenza + +GPL-v3 o successive. + + +