Expand install docs, formatting YAML examples

Author: mbabker

docs/authentication.md

@@ -19,24 +19,24 @@ To enable the session authenticator, you must add it to the `providers` list in
 
 ```yaml
 services:
-    session.handler.pdo:
-        class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
-        arguments:
-            - !service { class: PDO, factory: ['@database_connection', 'getWrappedConnection'] }
-            - { lock_mode: 0 }
+  session.handler.pdo:
+    class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
+    arguments:
+      - !service { class: PDO, factory: ['@database_connection', 'getWrappedConnection'] }
+      - { lock_mode: 0 }
 
 framework:
-    session:
-        handler_id: 'session.handler.pdo'
+  session:
+    handler_id: 'session.handler.pdo'
 
 babdev_websocket:
-    authentication:
-        providers:
-            session:
-                firewalls: ~
-    server:
-        session:
-            handler_service_id: 'session.handler.pdo'
+  authentication:
+    providers:
+      session:
+        firewalls: ~
+  server:
+    session:
+      handler_service_id: 'session.handler.pdo'
 ```
 
 Configuring the session handler will add the [`InitializeSession` middleware](/open-source/packages/websocket-server/docs/1.x/middleware/initialize-session) to the websocket server which will provide a read-only interface for the session data from your website.
@@ -45,10 +45,10 @@ By default, the session authentication provider will attempt to authenticate to
 
 ```yaml
 babdev_websocket:
-    authentication:
-        providers:
-            session:
-                firewalls: ['main'] # This can be an array to specify multiple firewalls or a string when specifying a single firewall 
+  authentication:
+    providers:
+      session:
+        firewalls: ['main'] # This can be an array to specify multiple firewalls or a string when specifying a single firewall 
 ```
 
 ### Registering New Authenticators

docs/installation.md

@@ -19,3 +19,52 @@ return [
     BabDev\WebSocketBundle\BabDevWebSocketBundle::class => ['all' => true],
 ];
 ```
+
+## Configure The Bundle
+
+Because a Flex recipe is not published for the bundle at this time, you will need to manually configure the bundle to fully enable its features. The below example can be written to `config/packages/babdev_websocket.yaml` in your application as a starting point:
+
+```yaml
+babdev_websocket:
+  authentication:
+    providers:
+      session:
+        firewalls: ~
+  server:
+    uri: '%env(BABDEV_WEBSOCKET_SERVER_URI)%'
+    router:
+      resource: '%kernel.project_dir%/config/websocket_router.yaml'
+    session:
+      handler_service_id: 'session.handler.pdo'
+```
+
+In this example, we:
+
+- Enable the [session authentication provider](/open-source/packages/websocketbundle/docs/1.x/authentication) and allow sessions for all firewalls
+- Configure the address the server will listen to connections on using the `BABDEV_WEBSOCKET_SERVER_URI` environment variable
+- Configure the router resource for the websocket server
+- Configure the session handler that is used to read session data for incoming connections (for our example, we are using a PDO session handler but this can be any shared resource such as the database or Redis)
+
+### Configuring the WebSocket Server Address
+
+The `babdev_websocket.server.uri` configuration node is used to define what address and port the websocket server process will listen for incoming connections on. The below snippet can be added to your application's `.env` file to define a sane default for local development, which will listen for connections on localhost at port 8080:
+
+```properties
+###> babdev/websocket-bundle ###
+BABDEV_WEBSOCKET_SERVER_URI=127.0.0.1:8080
+###< babdev/websocket-bundle ###
+```
+
+### Configuring the WebSocket Server Router
+
+The websocket server uses the Symfony Routing component to power its routing implementation, which requires a second router service to be configured in your application. Most of this is taken care of already in the bundle, however, you will need to add a file in your application to define the routes for the websocket server. The below example, which is based on the default `config/routes.yaml` added to applications, can be saved to your application at `config/websocket_router.yaml`:
+
+```yaml
+controllers:
+  resource:
+    path: ../src/WebSocket/
+    namespace: App\WebSocket
+  type: attribute
+```
+
+Similar to the default router configuration, this will scan for the `AsMessageHandler` attribute on classes in your `src/WebSocket` directory.

docs/managing-middleware.md

@@ -48,9 +48,9 @@ If you are not using autoconfiguration, the service should be tagged with the `b
 ```yaml
 # config/services.yaml
 services:
-    App\WebSocket\Middleware\EarlyMiddleware:
-        arguments:
-            - !abstract decorated middleware
-        tags:
-            - { name: babdev_websocket_server.server_middleware, priority: -75 }
+  App\WebSocket\Middleware\EarlyMiddleware:
+    arguments:
+      - !abstract decorated middleware
+    tags:
+      - { name: babdev_websocket_server.server_middleware, priority: -75 }
 ```

docs/periodic-manager.md

@@ -4,6 +4,8 @@ The `BabDev\WebSocketBundle\PeriodicManager\PeriodicManager` interface represent
 
 Periodic managers are initialized during the `BabDev\WebSocketBundle\Event\BeforeRunServer` event and the manager is responsible for registering its actions to the event loop.
 
+The bundle will autoconfigure periodic managers with the `babdev_websocket_server.periodic_manager` service tag, which is required to ensure managers are correctly registered.
+
 ## Required Methods
 
 ### `getName()`

docs/securing-connections.md

@@ -11,11 +11,11 @@ The bundle can be configured to only allow requests when traffic originates from
 ```yaml
 # config/packages/babdev_websocket.yaml
 babdev_websocket:
-    server:
-        # A list of origins allowed to connect to the websocket server, must match the value from the "Origin" header of the HTTP request.
-        allowed_origins:
-            - www.example.com
-            - example.com
+  server:
+    # A list of origins allowed to connect to the websocket server, must match the value from the "Origin" header of the HTTP request.
+    allowed_origins:
+      - www.example.com
+      - example.com
 ```
 
 With this configuration, only connections from `www.example.com` and `example.com` will be accepted, others will be rejected.
@@ -27,11 +27,11 @@ The bundle can be configured to block traffic from specified IP addresses. The c
 ```yaml
 # config/packages/babdev_websocket.yaml
 babdev_websocket:
-    server:
-      # A list of IP addresses which are not allowed to connect to the websocket server, each entry can be either a single address or a CIDR range.
-        blocked_ip_addresses:
-            - 8.8.8.8
-            - 192.168.1.0/24
+  server:
+    # A list of IP addresses which are not allowed to connect to the websocket server, each entry can be either a single address or a CIDR range.
+      blocked_ip_addresses:
+        - 8.8.8.8
+        - 192.168.1.0/24
 ```
 
 With this configuration, all connections from `8.8.8.8` and the `192.168.1.0/24` range will be rejected.