From a32ca3d90a85e12b8176d419ce0531f07d1d9f0a Mon Sep 17 00:00:00 2001 From: Benji Visser Date: Wed, 9 Nov 2016 12:39:53 -0500 Subject: [PATCH] docs: moving documentation around to be more clear and easier to browse (#236) * moving documentation around to be more clear and easier to browse - moved assets into their own directory and updated links to them - moved operating docs into their own directory - consolidated kubernetes docs - added docker-swarm folder for docs - updated docs layout in docs/README.md to reflect the changes and make it easier to read * docs: s/Operating Functions/Operating IronFunctions/ * docs: removing duplicate database link * docs: moving databases into general docs * docs: moving databases/mqs back * docs: removing memory.md (duplicate of operating/routes.md) * docs: converting to markdown bullets --- README.md | 2 +- docs/README.md | 18 +++++++++++------- docs/{ => assets}/architecture.png | Bin docs/{ => assets}/architecture.svg | 0 docs/{ => assets}/async-log-full.png | Bin docs/{ => assets}/async-log.png | Bin docs/{ => docker-swarm}/swarm.md | 8 +++++--- .../functions-config.yaml | 0 .../functions-deployment.yaml | 0 .../functions-service.yaml | 0 .../postgresql-deployment.yaml | 0 .../postgresql-service.yaml | 0 .../redis-deployment.yaml | 0 .../kubernetes-production/redis-service.yaml | 0 .../kubernetes-quick/deployment.yaml | 0 .../kubernetes-quick/service.yaml | 0 docs/{ => kubernetes}/kubernetes.md | 0 docs/mqs/README.md | 2 +- docs/{ => operating}/docker.md | 6 +++--- docs/{ => operating}/extending.md | 0 docs/{ => operating}/logging.md | 16 ++++++++-------- docs/{ => operating}/metrics.md | 10 +++++----- docs/{ => operating}/production.md | 11 +++++------ docs/{ => operating}/routes.md | 0 docs/{ => operating}/scaling.md | 0 docs/{ => operating}/triggers.md | 4 ++-- docs/{ => operating}/windows.md | 0 docs/options.md | 2 +- 28 files changed, 42 insertions(+), 37 deletions(-) rename docs/{ => assets}/architecture.png (100%) rename docs/{ => assets}/architecture.svg (100%) rename docs/{ => assets}/async-log-full.png (100%) rename docs/{ => assets}/async-log.png (100%) rename docs/{ => docker-swarm}/swarm.md (96%) rename docs/{ => kubernetes}/kubernetes-production/functions-config.yaml (100%) rename docs/{ => kubernetes}/kubernetes-production/functions-deployment.yaml (100%) rename docs/{ => kubernetes}/kubernetes-production/functions-service.yaml (100%) rename docs/{ => kubernetes}/kubernetes-production/postgresql-deployment.yaml (100%) rename docs/{ => kubernetes}/kubernetes-production/postgresql-service.yaml (100%) rename docs/{ => kubernetes}/kubernetes-production/redis-deployment.yaml (100%) rename docs/{ => kubernetes}/kubernetes-production/redis-service.yaml (100%) rename docs/{ => kubernetes}/kubernetes-quick/deployment.yaml (100%) rename docs/{ => kubernetes}/kubernetes-quick/service.yaml (100%) rename docs/{ => kubernetes}/kubernetes.md (100%) rename docs/{ => operating}/docker.md (78%) rename docs/{ => operating}/extending.md (100%) rename docs/{ => operating}/logging.md (54%) rename docs/{ => operating}/metrics.md (68%) rename docs/{ => operating}/production.md (90%) rename docs/{ => operating}/routes.md (100%) rename docs/{ => operating}/scaling.md (100%) rename docs/{ => operating}/triggers.md (63%) rename docs/{ => operating}/windows.md (100%) diff --git a/README.md b/README.md index 6495385e2..3b2b4b402 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,7 @@ You will get a `call_id` in the response: If you watch the logs, you will see the function actually runs in the background: -![async log](docs/async-log.png) +![async log](docs/assets/async-log.png) Read more on [logging](docs/logging.md). diff --git a/docs/README.md b/docs/README.md index 368fb746b..13d924221 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,13 @@ # IronFunctions Documentation +* [FAQ](faq.md) + ## For Developers If you are a developer using IronFunctions through the API, this section is for you. * [Quickstart](https://github.com/iron-io/functions#quickstart) -* [CLI tool - fnctl](../fnctl/README.md) +* [fnctl (CLI Tool)](/fnctl/README.md) * [Writing functions](writing.md) * [Writing Lambda functions](docs/lambda/create.md) * [Packaging functions](packaging.md) @@ -16,11 +18,13 @@ If you are a developer using IronFunctions through the API, this section is for If you are operating IronFunctions, this section is for you. -* [Running in Production](production.md) +* [Running in Production](operating/production.md) * [Databases](databases/README.md) * [Message Queues](mqs/README.md) -* [Logging](logging.md) -* [Metrics](metrics.md) -* [Triggers](triggers.md) -* [Extending IronFunctions](extending.md) -* [Docker Configuration](docker.md) +* [Logging](operating/logging.md) +* [Metrics](operating/metrics.md) +* [Triggers](operating/triggers.md) +* [Extending IronFunctions](operating/extending.md) +* [Docker Configuration](operating/docker.md) +* [Operating On Windows](operating/windows.md) + diff --git a/docs/architecture.png b/docs/assets/architecture.png similarity index 100% rename from docs/architecture.png rename to docs/assets/architecture.png diff --git a/docs/architecture.svg b/docs/assets/architecture.svg similarity index 100% rename from docs/architecture.svg rename to docs/assets/architecture.svg diff --git a/docs/async-log-full.png b/docs/assets/async-log-full.png similarity index 100% rename from docs/async-log-full.png rename to docs/assets/async-log-full.png diff --git a/docs/async-log.png b/docs/assets/async-log.png similarity index 100% rename from docs/async-log.png rename to docs/assets/async-log.png diff --git a/docs/swarm.md b/docs/docker-swarm/swarm.md similarity index 96% rename from docs/swarm.md rename to docs/docker-swarm/swarm.md index 74d3f3d53..e65b22dd1 100644 --- a/docs/swarm.md +++ b/docs/docker-swarm/swarm.md @@ -1,4 +1,6 @@ -# HOWTO run IronFunction as a scheduler on top of Docker Standalone Swarm cluster +# Docker Swarm and IronFunctions + +How to run IronFunction as a scheduler on top of Docker Standalone Swarm cluster. ## Quick installation @@ -106,8 +108,8 @@ $ docker run -d --name functions-00 \ --network=functions-network \ -p 8080:8080 \ -v /var/run/docker.sock:/var/run/docker.sock \ - -e 'MQ=redis://functions-redis' \ - -e 'DB=postgres://postgres:mysecretpassword@functions-postgres/?sslmode=disable' \ + -e 'MQ=redis://functions-redis' \ + -e 'DB=postgres://postgres:mysecretpassword@functions-postgres/?sslmode=disable' \ iron/functions ``` diff --git a/docs/kubernetes-production/functions-config.yaml b/docs/kubernetes/kubernetes-production/functions-config.yaml similarity index 100% rename from docs/kubernetes-production/functions-config.yaml rename to docs/kubernetes/kubernetes-production/functions-config.yaml diff --git a/docs/kubernetes-production/functions-deployment.yaml b/docs/kubernetes/kubernetes-production/functions-deployment.yaml similarity index 100% rename from docs/kubernetes-production/functions-deployment.yaml rename to docs/kubernetes/kubernetes-production/functions-deployment.yaml diff --git a/docs/kubernetes-production/functions-service.yaml b/docs/kubernetes/kubernetes-production/functions-service.yaml similarity index 100% rename from docs/kubernetes-production/functions-service.yaml rename to docs/kubernetes/kubernetes-production/functions-service.yaml diff --git a/docs/kubernetes-production/postgresql-deployment.yaml b/docs/kubernetes/kubernetes-production/postgresql-deployment.yaml similarity index 100% rename from docs/kubernetes-production/postgresql-deployment.yaml rename to docs/kubernetes/kubernetes-production/postgresql-deployment.yaml diff --git a/docs/kubernetes-production/postgresql-service.yaml b/docs/kubernetes/kubernetes-production/postgresql-service.yaml similarity index 100% rename from docs/kubernetes-production/postgresql-service.yaml rename to docs/kubernetes/kubernetes-production/postgresql-service.yaml diff --git a/docs/kubernetes-production/redis-deployment.yaml b/docs/kubernetes/kubernetes-production/redis-deployment.yaml similarity index 100% rename from docs/kubernetes-production/redis-deployment.yaml rename to docs/kubernetes/kubernetes-production/redis-deployment.yaml diff --git a/docs/kubernetes-production/redis-service.yaml b/docs/kubernetes/kubernetes-production/redis-service.yaml similarity index 100% rename from docs/kubernetes-production/redis-service.yaml rename to docs/kubernetes/kubernetes-production/redis-service.yaml diff --git a/docs/kubernetes-quick/deployment.yaml b/docs/kubernetes/kubernetes-quick/deployment.yaml similarity index 100% rename from docs/kubernetes-quick/deployment.yaml rename to docs/kubernetes/kubernetes-quick/deployment.yaml diff --git a/docs/kubernetes-quick/service.yaml b/docs/kubernetes/kubernetes-quick/service.yaml similarity index 100% rename from docs/kubernetes-quick/service.yaml rename to docs/kubernetes/kubernetes-quick/service.yaml diff --git a/docs/kubernetes.md b/docs/kubernetes/kubernetes.md similarity index 100% rename from docs/kubernetes.md rename to docs/kubernetes/kubernetes.md diff --git a/docs/mqs/README.md b/docs/mqs/README.md index 9f3f23c4b..01dbd44a9 100644 --- a/docs/mqs/README.md +++ b/docs/mqs/README.md @@ -32,5 +32,5 @@ The IronMQ connector uses HTTPS by default. To use HTTP set the scheme to ## What about message queue X? -We're happy to add more and we love pull requests, so feel free to add one! Copy one of the implementations above as a starting point. +We're happy to add more and we love pull requests, so feel free to add one! Copy one of the implementations above as a starting point. diff --git a/docs/docker.md b/docs/operating/docker.md similarity index 78% rename from docs/docker.md rename to docs/operating/docker.md index 49c0ad948..ea0197899 100644 --- a/docs/docker.md +++ b/docs/operating/docker.md @@ -2,9 +2,9 @@ To get the best performance, you'll want to ensure that Docker is configured properly. These are the environments known to produce the best results: -1) Linux 4.7 or newer with aufs or overlay2 module -2) Ubuntu 16.04 LTS or newer with aufs or overlay2 module -3) Docker 1.12 or newer to be available +1. Linux 4.7 or newer with aufs or overlay2 module. +2. Ubuntu 16.04 LTS or newer with aufs or overlay2 module. +3. Docker 1.12 or newer to be available. It is important to reconfigure host's Docker with this filesystem module. Thus, in your Docker start scripts you must do as following: diff --git a/docs/extending.md b/docs/operating/extending.md similarity index 100% rename from docs/extending.md rename to docs/operating/extending.md diff --git a/docs/logging.md b/docs/operating/logging.md similarity index 54% rename from docs/logging.md rename to docs/operating/logging.md index e3225872d..48383bccd 100644 --- a/docs/logging.md +++ b/docs/operating/logging.md @@ -1,24 +1,24 @@ # Logging -There are a few things to note about what IronFunctions logs. +There are a few things to note about what IronFunctions logs. ## Logspout -We recommend using [logspout](https://github.com/gliderlabs/logspout) to forward your logs to a log aggregator of your choice. +We recommend using [logspout](https://github.com/gliderlabs/logspout) to forward your logs to a log aggregator of your choice. ## Format -All logs are emitted in [logfmt](https://godoc.org/github.com/kr/logfmt) format for easy parsing. +All logs are emitted in [logfmt](https://godoc.org/github.com/kr/logfmt) format for easy parsing. ## Call ID -Every function call/request is assigned a `call_id`. If you search your logs, you can track all the activity +Every function call/request is assigned a `call_id`. If you search your logs, you can track all the activity for each function call and find errors on a call by call basis. For example, these are the log lines for an aynschronous function call: -![async logs](async-log-full.png) +![async logs](/docs/assets/async-log-full.png) -Note the easily searchable `call_id=x` format. +Note the easily searchable `call_id=x` format. ```sh call_id=477949e2-922c-5da9-8633-0b2887b79f6e @@ -26,7 +26,7 @@ call_id=477949e2-922c-5da9-8633-0b2887b79f6e ## Metrics -Metrics are emitted via the logs. +Metrics are emitted via the logs. -See [Metrics](metrics.md) doc for more information. +See [Metrics](metrics.md) doc for more information. diff --git a/docs/metrics.md b/docs/operating/metrics.md similarity index 68% rename from docs/metrics.md rename to docs/operating/metrics.md index c7ba408fa..80f6ae097 100644 --- a/docs/metrics.md +++ b/docs/operating/metrics.md @@ -2,9 +2,9 @@ Metrics are emitted via the logs for few couple of reasons: -1) Everything supports STDERR. -2) User can optionally use them, if not, they just end up in the logs. -3) No particular metrics system required, in other words, all metrics systems can be used via adapters (see below). +1. Everything supports STDERR. +2. User can optionally use them, if not, they just end up in the logs. +3. No particular metrics system required, in other words, all metrics systems can be used via adapters (see below). ## Metrics @@ -15,11 +15,11 @@ metric=someevent value=1 type=count metric=somegauge value=50 type=gauge ``` -It's a very simple format that can be easily parsed by any logfmt parser and passed on to another stats service. +It's a very simple format that can be easily parsed by any logfmt parser and passed on to another stats service. TODO: List all metrics we emit to logs. ## Statsd The [Logspout Statsd Adapter](https://github.com/iron-io/logspout-statsd) adapter can parse the log metrics and forward -them to any statsd server. \ No newline at end of file +them to any statsd server. diff --git a/docs/production.md b/docs/operating/production.md similarity index 90% rename from docs/production.md rename to docs/operating/production.md index af9eea725..0303524ca 100644 --- a/docs/production.md +++ b/docs/operating/production.md @@ -1,4 +1,3 @@ - # Running IronFunctions in Production The [QuickStart guide](/README.md) is intended to quickly get started and kick the tires. To run in production and be ready to scale, you need @@ -10,11 +9,11 @@ to use more production ready components. Here's a rough diagram of what a production deployment looks like: -![IronFunctions Architecture Diagram](architecture.svg) +![IronFunctions Architecture Diagram](/docs/assets/architecture.svg) ## Load Balancer -Any load balancer will work, put every instance of IronFunctions that you run behind the load balancer. +Any load balancer will work, put every instance of IronFunctions that you run behind the load balancer. **Note**: We will work on a smart load balancer that can direct traffic in a smarter way. See [#151](https://github.com/iron-io/functions/issues/151). @@ -34,13 +33,13 @@ The message queue is pluggable and we currently support a few options that can b ## Logging, Metrics and Monitoring Logging is a particularly important part of IronFunctions. It not only emits logs, but metrics are also emitted to the logs. Ops teams can then decide how they want -to use the logs and metrics without us prescribing a particular technology. For instance, you can [logspout-statsd](https://github.com/iron-io/logspout-statsd) to capture metrics +to use the logs and metrics without us prescribing a particular technology. For instance, you can [logspout-statsd](https://github.com/iron-io/logspout-statsd) to capture metrics from the logs and forward them to statsd. [More about Metrics](metrics.md) ## Scaling -There are metrics emitted to the logs that can be used to notify you when to scale. The most important being the `wait_time` metrics for both the -synchronous and asynchronous functions. If `wait_time` increases, you'll want to start more IronFunctions instances. +There are metrics emitted to the logs that can be used to notify you when to scale. The most important being the `wait_time` metrics for both the +synchronous and asynchronous functions. If `wait_time` increases, you'll want to start more IronFunctions instances. diff --git a/docs/routes.md b/docs/operating/routes.md similarity index 100% rename from docs/routes.md rename to docs/operating/routes.md diff --git a/docs/scaling.md b/docs/operating/scaling.md similarity index 100% rename from docs/scaling.md rename to docs/operating/scaling.md diff --git a/docs/triggers.md b/docs/operating/triggers.md similarity index 63% rename from docs/triggers.md rename to docs/operating/triggers.md index 5a155b9ec..674cf0e64 100644 --- a/docs/triggers.md +++ b/docs/operating/triggers.md @@ -1,5 +1,5 @@ # Triggers -Triggers are integrations that you can use in other systems to fire off functions in IronFunctions. +Triggers are integrations that you can use in other systems to fire off functions in IronFunctions. -TODO: +TODO: diff --git a/docs/windows.md b/docs/operating/windows.md similarity index 100% rename from docs/windows.md rename to docs/operating/windows.md diff --git a/docs/options.md b/docs/options.md index 4924b4902..8b5318e0e 100644 --- a/docs/options.md +++ b/docs/options.md @@ -2,7 +2,7 @@ ## Configuration -When starting IronFunctions, you can pass in the following configuration variables as environment variables. Use `-e VAR_NAME=VALUE` in +When starting IronFunctions, you can pass in the following configuration variables as environment variables. Use `-e VAR_NAME=VALUE` in docker run. For example: ```