Add diagrams / architecture

Architecture sections updated Deployment guides now point to workshop Images added for architecture Signed-off-by: Alex Ellis <alexellis2@gmail.com>
openfaas · Mar 26, 2018 · 5c3efea · 5c3efea
1 parent 86b4e10
commit 5c3efea
Show file tree

Hide file tree

Showing 9 changed files with 42 additions and 16 deletions.
diff --git a/diagrams/README.md b/diagrams/README.md
@@ -0,0 +1,5 @@
+## Source diagrams
+
+These diagrams are in the original vector or binary format such as Gliffy.
+
+gliffy is a Chrome extension for building technical diagrams.
diff --git a/diagrams/watchdog-modes.gliffy b/diagrams/watchdog-modes.gliffy
diff --git a/docs/architecture/watchdog-modes.png b/docs/architecture/watchdog-modes.png
diff --git a/docs/architecture/watchdog.md b/docs/architecture/watchdog.md
@@ -4,17 +4,24 @@ The OpenFaaS watchdog is responsible for starting and monitoring functions in Op
 
 ## Classic watchdog
 
+The classic watchdog is currently used in all the official OpenFaaS templates. You can view the templates in the [templates repository](https://github.com/openfaas/templates).
+
 <a href="https://camo.githubusercontent.com/61c169ab5cd01346bc3dc7a11edc1d218f0be3b4/68747470733a2f2f7062732e7477696d672e636f6d2f6d656469612f4447536344626c554941416f34482d2e6a70673a6c61726765"><img src="https://camo.githubusercontent.com/61c169ab5cd01346bc3dc7a11edc1d218f0be3b4/68747470733a2f2f7062732e7477696d672e636f6d2f6d656469612f4447536344626c554941416f34482d2e6a70673a6c61726765"></a>
 
 *Pictured: technical conceptual diagram of the OpenFaaS watchdog during an invocation*
 
-Technical documentation on the classic watchdog is available in the faas repo:
+Technical documentation on the classic watchdog is available belong along with a table with all configuration options.
 
 * [Watchdog README](https://github.com/openfaas/faas/tree/master/watchdog)
 
-## Alpha of-watchdog
+## of-watchdog
 
-We have next generation watchdog under incubation within our [openfaas-incubator organisation](https://github.com/openfaas-incubator). This brings new features for high-throughput systems.
+of-watchdog is our next-generation watchdog which is in incubation within our [openfaas-incubator organisation](https://github.com/openfaas-incubator).
 
-* [Read more on the of-watchdog](https://github.com/openfaas-incubator/of-watchdog)
+<a href="/architecture/watchdog-modes.png"><img src="/architecture/watchdog-modes.png"></a>
+
+*Pictured: various modes for the of-watchdog component*
 
+This brings version of the watchdog brings new features for high-throughput systems. The primary difference is the ability to keep a process warm between invocations. The classic watchdog forks one process per request and the new version enables a mode where that same process can be re-used repeatedly to reduce latency.
+
+* [Read more on the of-watchdog](https://github.com/openfaas-incubator/of-watchdog)
diff --git a/docs/conceptual.md b/docs/conceptual.md
@@ -15,7 +15,7 @@
 * Your API Gateway will scale functions according to demand by altering the service replica count in the Docker Swarm or Kubernetes API.
 * A UI is baked in allowing you to invoke functions in your browser and create new ones as needed.
 
-> The API Gateway is a RESTful micro-service and you can view the [Swagger docs here](https://github.com/openfaas/faas/tree/master/api-docs).
+> The API Gateway is a RESTful micro-service and you can view the [Swagger docs here](/architecture/gateway/#swagger).
 
 ### CLI
 

diff --git a/docs/deployment.md b/docs/deployment.md
@@ -1,7 +1,5 @@
 # Deployment
 
-> Note: The best place to get an overview of OpenFaaS is in the [Overview page](./).
-
 ### A foreword on security
 
 These instructions are for a development environment. If you plan to expose OpenFaaS on the public Internet you need to enable basic authentication with a proxy such as Kong or Traefik at a minimum. TLS is also highly recommended and freely available with LetsEncrypt.org. [Kong guide](https://github.com/openfaas/faas/blob/master/guide/kong_integration.md) [Traefik guide](https://github.com/openfaas/faas/blob/master/guide/traefik_integration.md).

diff --git a/docs/deployment/docker-swarm.md b/docs/deployment/docker-swarm.md
@@ -1,6 +1,6 @@
 # Deployment guide for Docker Swarm
 
-## Initialize Swarm Mode
+## 1.0 Initialize Swarm Mode
 
 You can create a single-host Docker Swarm on your laptop with a single command. You don't need any additional software to Docker 17.06 or greater. You can also run these commands on a Linux VM or cloud host.
 
@@ -14,41 +14,49 @@ If you have more than one IP address you may need to pass a string like `--adver
 
 Take a note of the join token
 
-* Join any workers you need
+## 1.1 Join any workers you need
 
 Log into your worker node and type in the output from `docker swarm init` on the master. If you've lost this info then type in `docker swarm join-token worker` and then enter that on the worker.
 
 It's also important to pass the `--advertise-addr` string to any hosts which have a public IP address.
 
 > Note: check whether you need to enable firewall rules for the [Docker Swarm ports listed here](https://docs.docker.com/engine/swarm/swarm-tutorial/).
 
-## Deploy the stack
+## 2.0 Deploy the stack
 
 Clone OpenFaaS and then checkout the latest stable release:
 
 ```
 $ git clone https://github.com/openfaas/faas && \
   cd faas && \
-  git checkout 0.7.1 && \
+  git checkout 0.7.7 && \
   ./deploy_stack.sh
 ```
 
 `./deploy_stack.sh` can be run at any time and includes a set of sample functions. You can read more about these in the [TestDrive document](https://github.com/openfaas/faas/blob/master/TestDrive.md)
 
-## Test out the UI
+> Note: if you want to try newer features you can checkout the `master` branch, but we do not recommend that for first-time users.
+
+## 2.1 Test out the UI
 
 Within a few seconds (or minutes if on a poor WiFi connection) the API gateway and sample functions will be pulled into your local Docker library and you will be able to access the UI at:
 
-http://localhost:8080
+http://127.0.0.1:8080
 
-If you're running on Linux you may find that `localhost` times out. In this case force an IPv4 address such as http://127.0.0.1:8080.
+> Note: If you're running on Linux you may find that accessing `localhost` times out. We recommend using an IPv4 address such as http://127.0.0.1:8080 to prevent any ambiguity.
 
-## Learn the CLI
+## 3.0 Learn the CLI
 
 You can now grab a coffee and start learning how to create your first function with the CLI:
 
 [Morning coffee with the OpenFaaS CLI](https://blog.alexellis.io/quickstart-openfaas-cli/)
 
+## 3.1 Start the hands-on labs
+
+Learn how to build serverless functions with OpenFaaS and Python in our half-day workshop. You can follow along online at your own pace.
+
+* [OpenFaaS workshop](/tutorials/workshop/)
+
 ## Troubleshooting
 
 If you are running into any issues please check out the troubleshooting guide and search the documentation / past issues before raising na issue.

diff --git a/docs/deployment/kubernetes.md b/docs/deployment/kubernetes.md
@@ -184,6 +184,13 @@ $ echo -n "" | faas-cli invoke --gateway http://kubernetes-ip:31112 nodeinfo
 $ echo -n "verbose" | faas-cli invoke --gateway http://kubernetes-ip:31112 nodeinfo
 ```
 
+
+## 3.1 Start the hands-on labs
+
+Learn how to build serverless functions with OpenFaaS and Python in our half-day workshop. You can follow along online at your own pace.
+
+* [OpenFaaS workshop](/tutorials/workshop/)
+
 ## Troubleshooting
 
 If you are running into any issues please check out the troubleshooting guide and search the documentation / past issues before raising an issue.

diff --git a/docs/tutorials/workshop.md b/docs/tutorials/workshop.md
@@ -4,4 +4,4 @@ The OpenFaaS community has built a set of hands-on labs which you can work throu
 
 It's a good place to start if you're new to the project and want to build a working knowledge of how to start shipping serverless functions.
 
-* [Start the workshop](https://github.com/openfaas/workshop)
+* [Start the workshop on GitHub](https://github.com/openfaas/workshop)