Merge pull request #14 from krzko/docs-update-external-network

docs: refactor docs

README.md

@@ -49,12 +49,14 @@ Download the latest version from the [Releases](https://github.com/krzko/run-o11
     * Jaeger: http://localhost:14268
     * Zipkin: http://localhost:9411
 * Logs are procedd via two means:
-  * Tailed from `/var/log/*.log` and `$(PWD)/*.log` on your local machine.
+  * Tailed from `/var/log/*.log` and `./*.log` on your local machine.
   * A Syslog RFC 3164 header format, `syslog` receiver operates on `localhost:8094`
 * To exit gracefully, press `CTRL+C`.
 
 ## Commands
 
+`run-o11y-run` is a powerful command-line tool that provides seamless management of your local observability stack. It offers three simple commands: `start`, `stop`, and `clean`.
+
 ```sh
 $ run-o11y-run start
 
@@ -68,16 +70,37 @@ $ run-o11y-run start
  ✔ loki 9 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulled                                                                                                         81.8s
 ```
 
-`run-o11y-run` is a command-line tool with three simple commands: `start`, `stop`, and `clean`.
+### Start Command
+
+The `start` command allows you to launch run-o11y-run containers and start your observability stack effortlessly. You can customise the behaviour using various flags.
+
+One such flag is the `--registry` flag, which enables you to specify a Docker Registry from which to pull the required images. By default, run-o11y-run uses Docker Hub as the registry. Here's an example of using the `--registry flag`:
+
+```sh
+run-o11y-run start --registry <registry-url>
+```
+
+Replace `<registry-url>` with the URL of your desired Docker Registry.
+
+To further enhance your setup, you can also utilise the `--external-network` flag, which enables integration of your own docker-compose configurations with run-o11y-run. This allows you to combine the services of run-o11y-run with your existing infrastructure seamlessly.
 
-- `start`: Starts run-o11y-run containers. You can use the `--registry` flag to specify a Docker Registry. By default, it uses Docker Hub, but if you wish to specifcy your own, use this example
-  Example: `run-o11y-run start --registry <registry-url>`
+For more details on using the `--external-network` flag, refer to the [External Network Guide](docs/external-network.md).
 
-- `stop`: Stops run-o11y-run containers.
-  Example: `run-o11y-run stop`
+### Stop Command
 
-- `clean`: Stops and removes run-o11y-run containers, files, and networks.
-  Example: `run-o11y-run clean`
+The `stop` command is used to gracefully stop the run-o11y-run containers. It ensures a clean shutdown of your observability stack. Here's an example of using the `stop` command:
+
+```sh
+run-o11y-run stop
+```
+
+### Clean Command
+
+The `clean` command is used to stop and remove run-o11y-run containers, files, and networks. It helps you clean up your environment after using run-o11y-run. Here's an example of using the `clean` command:
+
+```sh
+run-o11y-run clean
+```
 
 ## Local Service Links
 

docs/docker-compose.yaml

@@ -0,0 +1,15 @@
+version: '2'
+
+networks:
+  o11y:
+    name: o11y
+    driver: bridge
+    external: true
+
+services:
+  curl:
+    image: curlimages/curl:latest
+    networks:
+      - o11y
+    # Generates, HTTP/1.1 405 Method Not Allowed
+    command: "-v otel-collector:4318/v1/traces"

docs/external-network.md

@@ -0,0 +1,78 @@
+# External Network
+
+In certain scenarios, users may need to integrate their own `docker-compose` configurations with `run-o11y-run`. To facilitate this, we provide support for a multi docker-compose setup.
+
+To utilise this feature, simply run `run-o11y-run` with the `--external-network` flag. This allows you to seamlessly integrate your existing `docker-compose` configurations with `run-o11y-run`, enabling you to leverage the power of both environments in a unified manner.
+
+Here's an example of how you can set up your `docker-compose` configurations to work with `run-o11y-run`:
+
+1. To start `run-o11y-run` with an external bridged `o11y` network, simply run the following command:
+
+```sh
+run-o11y-run start --external-network
+```
+
+This command initiates `run-o11y-run` and enables seamless integration with your existing infrastructure through the `o11y` network. By using the `--external-network` flag, you establish a bridge between `run-o11y-run` and your custom `docker-compose` configurations.
+
+2. Modify your `docker-compose.yaml` file to include a network definition for the o11y network:
+
+```yaml
+networks:
+  o11y:
+    name: o11y
+    driver: bridge
+    external: true
+```
+
+3. Update the services in your `docker-compose.yaml` file to use the `o11y` network:
+
+```yaml
+services:
+  foo:
+    image: ...
+    networks:
+      - o11y
+    environments:
+    - OTEL_EXPORTER_OTLP_ENDPOINT: otel-collector:431...
+
+  bar:
+    image: ...
+    networks:
+      - o11y
+    environemnts:
+    - OTEL_EXPORTER_OTLP_ENDPOINT: otel-collector:431...
+```
+
+By connecting your customer-managed `docker-compose` setup with `run-o11y-run` assets through the `o11y` network, you establish communication between your applications and the observability components provided by `run-o11y-run`.
+
+## Network flow
+
+Here's a visual representation of the network flow:
+
+```mermaid
+flowchart TD
+
+    subgraph run-o11y-run["run-o11y-run docker-compose"]
+      direction LR
+
+      collector
+      minio --- loki
+      collector --- loki
+      collector --- prometheus
+      collector --- zipkin
+    end
+
+    subgraph application["application docker-compose"]
+      direction LR
+
+      app1[app 1]
+      app2[app 2]
+      app1 --"default network"---app2
+    end
+
+    application---collector
+```
+
+This diagram illustrates how your application services (`app1` and `app2`) can communicate with the observability components provided by `run-o11y-run` through the `o11y` network.
+
+You can refer to the example file provided [here](docker-compose.yaml).