move deployment configuration/writeup to synse server repo. (#125)

deploy/docker/Makefile

@@ -0,0 +1,17 @@
+#
+# Synse Emulator Plugin Deployments
+#
+
+.PHONY: tcp
+tcp:  ## Spin up the TCP based deployment
+	docker-compose -f deploy-tcp.yml up --abort-on-container-exit
+
+.PHONY: unix
+unix:  ## Spin up the unix socket based deployment
+	docker-compose -f deploy-unix.yml up --abort-on-container-exit
+
+.PHONY: help
+help:  ## Print usage information
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
+
+.DEFAULT_GOAL := help

deploy/docker/README.md

@@ -0,0 +1,88 @@
+# Deploying with Docker Compose
+This directory contains examples for [docker-compose][docker-compose] based deployments
+of Synse Server (v2.0+) with the containerized Emulator Plugin.
+
+## Deployments
+As a general note - the Emulator Plugin does not need to be containerized. In
+fact, it is built into non-slim Synse Server 2.0 images so that it can run
+alongside Synse Server, providing an easy way to get started/demo/play with it.
+
+In this case, we use a containerized version of the same emulator in order to
+give us a plugin that is not dependent on any platform or hardware. This makes 
+the examples here a good place to get started. Additionally, we use a slim version
+of Synse Server as to prove that the data is coming from the external emulator only.
+
+There are two docker-compose based deployments here. The only difference between
+the two is how Synse Server and the Plugin are configured to communicate. Currently,
+the [plugin SDK][synse-sdk] (via the [internal gRPC API][synse-grpc]) supports 
+communication via:
+- TCP
+- UNIX socket
+
+The two deployments here serve as an example on how to configure plugin and Synse
+Server for both of those cases.
+
+> **Note**: The difference is entirely in the configuration, not in the version of
+> the plugin or Synse Server. See the compose files and the corresponding config
+> files in the `config/` subdirectory to see how the two deployments differ.
+
+
+## Setup
+
+You will need the Synse Server image and the emulator plugin image. These can
+either be built locally, or can be pulled from DockerHub.
+```shell
+# synse server
+docker pull vaporio/synse-server
+
+# emulator plugin
+docker pull vaporio/emulator-plugin
+```
+
+If these images do not exist locally, `docker-compose` will pull them when the
+example compose files are run.
+
+## Usage
+Running either of the examples is pretty straightforward; there are Makefile
+targets for each deployment. To run the deployment that uses TCP-based communication
+between Synse Server and the plugin:
+```
+make tcp
+```
+
+To run the deployment that uses UNIX socket-based communication between 
+Synse Server and the plugin:
+```
+make unix
+```
+
+Once up and running, Synse Server should behave the same in both cases. That is to
+say, the data that Synse Server surfaces should be the same (it comes from the same
+emulator image). See the compose files and their related config files  (in the `config/`
+subdirectory) to see the differences between deployments.
+
+Once one of the deployments is running, you can test out that Synse Server is reachable.
+```
+curl localhost:5000/synse/test
+```
+
+If successful, you are ready to go. Next, perform a scan to see everything that is available
+via the plugin:
+```
+curl localhost:5000/synse/2.0/scan
+```
+
+This should give back a set of devices - in particular:
+- 1 fan device
+- 2 LED devices
+- 1 airflow device
+- 1 humidity device
+- 2 pressure devices
+- 5 temperature devices
+
+If you look at the log output of the Emulator Plugin , you should see that these results
+match up with what that plugin had registered on startup.
+
+[docker-compose]: https://docs.docker.com/compose/install/
+[synse-sdk]: https://github.com/vapor-ware/synse-sdk
+[synse-grpc]: https://github.com/vapor-ware/synse-server-grpc

deploy/docker/config/devices/devices.yaml

@@ -0,0 +1,71 @@
+version: 1.0
+locations:
+  r1vec:
+    rack: rack-1
+    board: vec
+devices:
+  # -- temperature devices --
+  - type: temperature
+    model: emul8-temp
+    instances:
+      - id: "1"
+        location: r1vec
+        info: Synse Temperature Sensor 1
+      - id: "2"
+        location: r1vec
+        info: Synse Temperature Sensor 2
+      - id: "3"
+        location: r1vec
+        info: Synse Temperature Sensor 3
+      - id: "4"
+        location: r1vec
+        info: Synse Temperature Sensor 4
+      - id: "5"
+        location: r1vec
+        info: Synse Temperature Sensor 5
+
+  # -- pressure devices --
+  - type: pressure
+    model: emul8-pressure
+    instances:
+      - id: "1"
+        location: r1vec
+        info: Synse Pressure Sensor 1
+      - id: "2"
+        location: r1vec
+        info: Synse Pressure Sensor 2
+
+  # -- led devices --
+  - type: led
+    model: emul8-led
+    instances:
+      - id: "1"
+        location: r1vec
+        info: Synse LED
+      - id: "2"
+        location: r1vec
+        info: Synse backup LED
+
+  # -- humidity devices --
+  - type: humidity
+    model: emul8-humidity
+    instances:
+      - id: "1"
+        location: r1vec
+        info: Synse Humidity Sensor
+
+  # -- fan devices --
+  - type: fan
+    model: emul8-fan
+    instances:
+      - id: "1"
+        location: r1vec
+        info: Synse Fan
+
+  # -- airflow devices --
+  - type: airflow
+    model: emul8-air
+    instances:
+      - id: "1"
+        location: r1vec
+        info: Synse Airflow Sensor

deploy/docker/config/tcp/config.yml

@@ -0,0 +1,6 @@
+version: 1.0
+name: emulator
+debug: true
+network:
+  type: tcp
+  address: ":5001"

deploy/docker/config/unix/config.yml

@@ -0,0 +1,6 @@
+version: 1.0
+name: emulator
+debug: true
+network:
+  type: unix
+  address: emulator.sock

deploy/docker/deploy-tcp.yml

@@ -0,0 +1,40 @@
+#
+# deploy-tcp.yml
+#
+# An example deployment of Synse Server and the Emulator Plugin
+# configured to communicate over TCP.
+#
+version: "3"
+services:
+
+  # Synse Server
+  synse-server:
+    container_name: synse-server
+    image: vaporio/synse-server:2.0.0
+    ports:
+      - 5000:5000
+    # TCP-based plugins can be registered with Synse Server via
+    # environment variables, so we specify the plugin here.
+    environment:
+      SYNSE_PLUGIN_TCP_EMULATOR: emulator-plugin:5001
+    links:
+      - emulator-plugin
+
+  # Emulator Plugin
+  emulator-plugin:
+    container_name: emulator-plugin
+    image: vaporio/emulator-plugin
+    ports:
+      - 5001:5001
+    volumes:
+      # mount in the plugin config (see the environment section on how to
+      # reference this non-default location)
+      - ./config/tcp:/tmp/config/
+      # mount in the device instance configuration (see the environment
+      # section on how to reference this non-default location)
+      - ./config/devices:/tmp/devices
+    environment:
+      # sets the override location for the plugin configuration
+      PLUGIN_CONFIG: /tmp/config
+      # sets the override location for the device instance configuration
+      PLUGIN_DEVICE_PATH: /tmp/devices

deploy/docker/deploy-unix.yml

@@ -0,0 +1,50 @@
+#
+# deploy-unix.yml
+#
+# An example deployment of Synse Server and the Emulator Plugin
+# configured to communicate over Unix socket.
+#
+version: "3.3"
+services:
+
+  # Synse Server
+  synse-server:
+    container_name: synse-server
+    image: vaporio/synse-server:2.0.0
+    ports:
+      - 5000:5000
+    # Unix-based plugins can be registered with Synse Server when Synse Server
+    # detects the socket file in a well-known path. Here, we mount a shared
+    # volume to that path (/tmp/synse/procs) so that Synse Server can access
+    # the plugin's socket.
+    volumes:
+      - type: volume
+        source: plugin_sockets
+        target: /tmp/synse/procs
+
+  # Emulator Plugin
+  emulator-plugin:
+    container_name: emulator-plugin
+    image: vaporio/emulator-plugin
+    environment:
+      # sets the override location for the plugin configuration (which is
+      # mounted in as a volume, below)
+      PLUGIN_CONFIG: /tmp/config
+      # sets the override location for the device instance configuration
+      PLUGIN_DEVICE_PATH: /tmp/devices
+    volumes:
+      # mount in the plugin config (see the environment section on how to
+      # reference this non-default location)
+      - ./config/unix:/tmp/config/
+      # mount in the device instance configuration (see the environment
+      # section on how to reference this non-default location)
+      - ./config/devices:/tmp/devices
+      # volume for the plugin socket, shared with synse-server
+      - type: volume
+        source: plugin_sockets
+        target: /tmp/synse/procs
+
+volumes:
+  # the shared volume between Synse Server and the Emulator Plugin
+  # which will contain the socket that they will communicate over
+  plugin_sockets:

docs/source/user/deployment.rst

@@ -10,7 +10,7 @@ with Synse Server and plugins.
 Deploying with Docker Compose
 -----------------------------
 For a complete set of examples for deploying with ``docker compose``, see the
-`emulator example deployment <https://github.com/vapor-ware/synse-emulator-plugin/tree/master/deploy/docker>`_.
+emulator example deployments in the ``deploy`` directory of the Synse Server source.
 This section goes into detail on how to deploy Synse Server with an externally
 running emulator plugin configured for TCP communication.
 
@@ -89,7 +89,8 @@ For our plugin config, we have the following ``config.yml``,
 
 Instance configurations can be much larger, as there may be many devices. For simplicity
 here, we will define a handful of temperature device instances in a file named ``devices.yml``.
-For a more complete example, see the `emulator example deployment <https://github.com/vapor-ware/synse-emulator-plugin/tree/master/deploy/docker>`_.
+For a more complete example, see the emulator example deployments in the ``deploy`` directory
+of the Synse Server source repo.
 
 .. code-block:: yaml