diff --git a/docs/source/getting_started_guide/creating_a_basic_network.rst b/docs/source/getting_started_guide/creating_a_basic_network.rst new file mode 100644 index 000000000..98358ac7a --- /dev/null +++ b/docs/source/getting_started_guide/creating_a_basic_network.rst @@ -0,0 +1,104 @@ + +.. _creating_a_basic_network: + +############################### +Creating a basic 3-node network +############################### + +In this section, we will create a three-node network. +The three nodes are: foo, bar, and mal. + +`foo -> bar <- mal` + +foo and mal are directly connected to bar with TCP connections. + +foo can reach mal by sending network packets through bar. + +*********************** +Receptor configurations +*********************** + +1. Create three configuration files, one for each node. + + **foo.yml** + +.. code-block:: yaml + + --- + - node: + id: foo + + - control-service: + service: control + filename: /tmp/foo.sock + + - tcp-peer: + address: localhost:2222 + redial: true + + - log-level: debug + ... + +**bar.yml** + +.. code-block:: yaml + + --- + - node: + id: bar + + - control-service: + service: control + filename: /tmp/bar.sock + + - tcp-listener: + port: 2222 + + - log-level: debug + ... + + **mal.yml** + +.. code-block:: yaml + + --- + - node: + id: mal + + - control-service: + service: control + filename: /tmp/mal.sock + + - tcp-peer: + address: localhost:2222 + redial: true + + - log-level: debug + + - work-command: + workType: echo + command: bash + params: "-c \"while read -r line; do echo $line; sleep 1; done\"" + allowruntimeparams: true + ... + +2. Run the services in separate terminals. + +.. code-block:: bash + + ./receptor --config foo.yml + +.. code-block:: bash + + ./receptor --config bar.yml + +.. code-block:: bash + + ./receptor --config mal.yml + +.. seealso:: + + :ref:`configuring_receptor_with_a_config_file` + Configuring Receptor with a configuration file + :ref:`connecting_nodes` + Detail on connecting receptor nodes diff --git a/docs/source/getting_started_guide/index.rst b/docs/source/getting_started_guide/index.rst new file mode 100644 index 000000000..30017aa72 --- /dev/null +++ b/docs/source/getting_started_guide/index.rst @@ -0,0 +1,28 @@ +############################# +Getting started with Receptor +############################# + +Receptor is an overlay network intended to ease the distribution of work across +a large and dispersed collection of workers. Receptor nodes establish peer-to- +peer connections with each other via existing networks. Once connected, the re- +ceptor mesh provides datagram (UDP-like) and stream (TCP-like) capabilities to +applications, as well as robust unit-of-work handling with resiliency against +transient network failures. + +.. image:: mesh.png + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + introduction + installing_receptor + creating_a_basic_network + trying_sample_commands + +.. seealso:: + + :ref:`interacting_with_nodes` + Further examples of working with nodes + :ref:`connecting_nodes` + Detail on connecting receptor nodes diff --git a/docs/source/getting_started_guide/installing_receptor.rst b/docs/source/getting_started_guide/installing_receptor.rst new file mode 100644 index 000000000..86b18bc39 --- /dev/null +++ b/docs/source/getting_started_guide/installing_receptor.rst @@ -0,0 +1,21 @@ + +.. _installing_receptor: + +################### +Installing Receptor +################### + +1. `Download receptor `_ +2. Install receptor (per installation guide below) +3. Install receptorctl + +.. code-block:: bash + + pip install receptorctl + +.. seealso:: + + :ref:`installing` + Detailed installation instructions + :ref:`using_receptor_containers` + Using receptor in containers diff --git a/docs/source/getting_started_guide/introduction.rst b/docs/source/getting_started_guide/introduction.rst new file mode 100644 index 000000000..3a4d5dd5f --- /dev/null +++ b/docs/source/getting_started_guide/introduction.rst @@ -0,0 +1,16 @@ +######################## +Introduction to receptor +######################## + +Receptor is an overlay network. +It eases the work distribution across a large and dispersed collection +of workers + +Receptor nodes establish peer-to-peer connections with each other through +existing networks + +Once connected, the receptor mesh provides: + +* Datagram (UDP-like) and stream (TCP-like) capabilities to applications +* Robust unit-of-work handling +* Resiliency against transient network failures diff --git a/docs/source/getting_started_guide/mesh.png b/docs/source/getting_started_guide/mesh.png new file mode 100644 index 000000000..9de9f0e3e Binary files /dev/null and b/docs/source/getting_started_guide/mesh.png differ diff --git a/docs/source/getting_started_guide/trying_sample_commands.rst b/docs/source/getting_started_guide/trying_sample_commands.rst new file mode 100644 index 000000000..620830c40 --- /dev/null +++ b/docs/source/getting_started_guide/trying_sample_commands.rst @@ -0,0 +1,53 @@ +################### +Try Sample Commands +################### + +N.B. The prior steps of network setup and receptor installation +need to be completed in order for these command to work + +1. Show network status + +.. code-block:: bash + + receptorctl --socket /tmp/foo.sock status + +2. Ping node mal from node foo + +.. code-block:: bash + + receptorctl --socket /tmp/foo.sock ping mal + +3. Submit work from foo to mal and stream results back to foo + +.. code-block:: bash + + seq 10 | receptorctl --socket /tmp/foo.sock work submit --node mal echo --payload - -f + +4. List work units + +.. code-block:: bash + + receptorctl --socket /tmp/foo.sock work list --node foo + +5. Get work unit id using jq + +.. code-block:: bash + + receptorctl --socket /tmp/foo.sock work list --node foo | jq --raw-output '.|keys|first' + +6. Re-stream the work results from work unit + +.. code-block:: bash + + receptorctl --socket /tmp/foo.sock work results work_unit_id + +Congratulations, you are now using Receptor! + +.. seealso:: + + :ref:`control_service_commands` + Control service commands + :ref:`creating_a_basic_network` + Creating a Basic Network + :ref:`installing_receptor` + Installing Receptor diff --git a/docs/source/index.rst b/docs/source/index.rst index b5da23a9d..a8519f4cf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,6 +13,7 @@ Receptor is an overlay network intended to ease the distribution of work across :maxdepth: 2 installation + getting_started_guide/index user_guide/index developer_guide contributing diff --git a/docs/source/user_guide/basic_usage.rst b/docs/source/user_guide/basic_usage.rst index 18f4a36b7..ea63727b0 100644 --- a/docs/source/user_guide/basic_usage.rst +++ b/docs/source/user_guide/basic_usage.rst @@ -21,6 +21,7 @@ Supported log levels, in increasing verbosity, are Error, Warning, Info and Debu Note: stop the receptor process with ``ctrl-c`` +.. _configuring_receptor_with_a_config_file: Configuring Receptor with a config file ---------------------------------------- @@ -45,6 +46,7 @@ Start receptor using the config file Changing the configuration file does take effect until the receptor process is restarted. +:: _using_receptor_containers: Use Receptor through a container image --------------------------------------- diff --git a/docs/source/user_guide/connecting_nodes.rst b/docs/source/user_guide/connecting_nodes.rst index 1c920a587..cd4d0fe6d 100644 --- a/docs/source/user_guide/connecting_nodes.rst +++ b/docs/source/user_guide/connecting_nodes.rst @@ -1,3 +1,4 @@ +.. _connecting_nodes: Connecting nodes ================ diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst index 29d14e3d3..2595f0810 100644 --- a/docs/source/user_guide/index.rst +++ b/docs/source/user_guide/index.rst @@ -8,20 +8,14 @@ This guide describes how to use receptor in multiple environments and uses the f .. glossary:: - receptor - The receptor application taken as a whole, which typically runs as a daemon. - - receptorctl - A user-facing command line used to interact with receptor, typically over a Unix domain socket. - - node - A single running instance of receptor. + Backend + A type of connection that receptor nodes can pass traffic over. Current backends include TCP, UDP and websockets. - node ID - An arbitrary string identifying a single node, analogous to an IP address. + backend peers + A node connected to another through receptor backends. - backend - A type of connection that receptor nodes can pass traffic over. Current backends include TCP, UDP and websockets. + control node + A node running the receptor control service. control service A built-in service that usually runs under the name `control`. Used to report status and to launch and monitor work. @@ -29,6 +23,21 @@ This guide describes how to use receptor in multiple environments and uses the f netceptor The component of receptor that handles all networking functionality. + netceptor peers + A receptor node directly connected to another receptor node. + + node + A single running instance of receptor. + + node ID + An arbitrary string identifying a single node, analogous to an IP address. + + receptor + The receptor application taken as a whole, which typically runs as a daemon. + + receptorctl + A user-facing command line used to interact with receptor, typically over a Unix domain socket. + workceptor The component of receptor that handles work units. diff --git a/docs/source/user_guide/interacting_with_nodes.rst b/docs/source/user_guide/interacting_with_nodes.rst index 13ead5ad9..be3c2e238 100644 --- a/docs/source/user_guide/interacting_with_nodes.rst +++ b/docs/source/user_guide/interacting_with_nodes.rst @@ -1,5 +1,6 @@ +.. _interacting_with_nodes: Interacting with nodes ====================== @@ -109,6 +110,7 @@ Once connected to a control service, one can issue commands like "status" or "wo Keep in mind that a "work submit" command will require a payload. Type out the payload contents and press ctrl-D to send the EOF signal. The socket will then close and work will begin. See :ref:`workceptor` for more on submitting work via receptor. +.. _control_service_commands: Control service commands --------------------------