Update README.md with docs (#17)

* feat(repo): Add usage example to README.md

* fix(repo): Improve docs

* fix(repo): Improve docs

* fix(repo): Improve docs

* fix(repo): Typos

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "thresh"
-version = "0.1.0"
-description = "Tiny local continuous integration based on Github webhooks"
+version = "0.0.1"
+description = "Tiny GitHub webhooks based CI/CD server for your VPS"
 authors = ["gillchristian <[email protected]>", "ndelvalle <[email protected]>"]
 edition = "2018"
 

README.md

@@ -1,30 +1,113 @@
-## Tresh
+# Tresh
 
-🛳 Tiny local continuous integration based on Github webhooks
+🛳 Tiny GitHub webhooks based CI/CD server for your VPS
 
-### Development
+## Install & setup
 
-#### Run
+Download the latest binary from the release and give exec permission:
+
+```
+$ wget -O thresh "https://github.com/Huemul/thresh/releases/download/v0.0.1/thresh_x86-64-linux
+"
+$ chmod +x thresh
+```
+
+**NOTE**: you probably want to change the version (`v0.0.1`) to the [latest available release](https://github.com/Huemul/thresh/releases).
+
+Now that Thresh is available:
+
+```
+$ ./thresh --help
+thresh 0.0.1
+gillchristian <[email protected]>:ndelvalle <[email protected]>
+Tiny GitHub webhooks based CI/CD server for your VPS
+
+USAGE:
+    thresh [OPTIONS]
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+OPTIONS:
+    -c, --config <config>        Path to the Threshfile [default: ./.threshfile]
+    -l, --logs-dir <logs-dir>    Sets a custom logs directory
+    -p, --port <port>            Sets a custom server port
+```
+
+Next create a `.threshfile` with the configuration to run for any project you want. For a example threshfile see [sample.threshfile](https://github.com/Huemul/thresh/blob/master/sample.threshfile).
+
+Create a systemd file (`/etc/systemd/system/thresh.service`) with the following contents.
+
+```
+[Unit]
+Description=Thresh
+
+[Service]
+ExecStart=/path/to/thresh -c /path/to/.threshfile -l /path/to/thresh-logs -p 8080
+```
+
+**NOTE**: Make sure to update it with the right options and path to the Thresh binary.
+
+Now enable and start thresh service:
 
 ```bash
-cargo run
+# might require sudo
+$ systemctl enable /etc/systemd/system/thresh.service
+$ systemctl start thresh
+```
 
-# Setting CLI options
-cargo run -- --port 9090 --logs-dir ./logs
+To see logs and status the following commands are useful:
+
+```bash
+$ systemctl status thresh
+$ journalctl -u thresh -b
+```
+
+Once Thresh is running and exposed to the internet on your VPS is time to [add the GitHub webhook to a repo](https://developer.github.com/webhooks/creating/).
+
+Create a webhook that sends `push` events to the webhook URL (`<domain-running-thresh>/webhook`).
+
+Thresh responds with a "job id" in case a webhook triggered a job. Which can be used to see the log file online:
+
+```
+GET <domain-running-thresh>/logs
+GET <domain-running-thresh>/logs/:{job_id}
 ```
 
+## Development
+
+#### Testing 
+
+#### Run
+
 ```bash
-# Using dev watch mode
+cargo run
+
+# Watch mode
 cargo watch -x run
+
+# Setting CLI options
+cargo run -- --port 9090 --logs-dir ./logs
 ```
 
 #### Test
 
 ```bash
 cargo test
+
+# Watch mode
+cargo watch -x test
 ```
 
+### Testing the webhook locally
+
 ```bash
-# Using dev watch mode
-cargo watch -x test
-```
+curl -d {
+  "ref": "refs/heads/master",
+  "repository": { "full_name": "username/repository" },
+  "sender": { "login": "username" }
+}' -H "Content-Type: application/json" -X POST http://localhost:8080/webhook
+```
+
+:point_up: That can also be used to trigger the webhook from other sources (eg. any CI/CD server). In that case, make sure the URL is passed by secrets.

sample.threshfile

@@ -0,0 +1,48 @@
+# Optional flag to run the job on the ping event
+# sent by GitHub when setting up the webhook
+run_job_on_ping = false
+
+# Optional config, can be set here or by the CLI options
+port = 8080
+logs_dir = "./logs"
+
+# a list of projects to run jobs for
+
+[[projects]]
+# the repository where the webhook is set up
+repository = "username/repository"
+
+# run only for this branch
+branch = "master"
+
+# path where the commands should run the tilde (~) is properly expanded
+#
+# NOTE: the path does not have to be a git repo
+#       it can be any directory
+path = "~/path/to/project/directory"
+
+# list of commands to run
+commands = [
+  "git pull --rebase",
+  "docker-compose down",
+  "docker-compose up -d",
+]
+
+[[projects]]
+repository = "username/other"
+branch = "development"
+path = "~/path/to/other"
+commands = [
+  "git pull",
+  "./reset.sh",
+]
+
+[[projects]]
+repository = "username/yet-another"
+branch = "master"
+path = "~/path/to/another"
+commands = [
+  "git pull",
+  "systemctl stop yet_another",
+  "systemctl start yet_another",
+]