Hugo website using docsy theme (cortexproject#1851)

* Adds the cortexmetrics.io hugo website. The website is built using hugo and google docsy theme. A special theme for open source content. The docs are copied over from the docs folder and massaged during the `web-pre` target to make them more Hugo friendly. All you have to do is keep writing docs in the `docs/` folder. The changelog and the governance document are also copied. New target have been added: - `web-build` rebuilds the website. - `web-pre` move docs to website/content/en/docs and apply some pre-processing for fixing md and links. - `web-deploy` deploy the website mainly used by CI. - `web-serve` serve the website locally, don't forget to `web-pre` first to get the doc moved. Signed-off-by: Tom Wilkie <[email protected]> Signed-off-by: Cyril Tovena <[email protected]> * Move dashboard to production/ & remove tag for website deploy Signed-off-by: Cyril Tovena <[email protected]> * Update image for migration ci target. Signed-off-by: Cyril Tovena <[email protected]>
eeldaly · Dec 11, 2019 · 1dd96fd · 1dd96fd
1 parent 7474b54
commit 1dd96fd
Show file tree

Hide file tree

Showing 103 changed files with 4,082 additions and 55 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -3,7 +3,7 @@ version: 2.1
 # https://circleci.com/blog/circleci-hacks-reuse-yaml-in-your-circleci-config-with-yaml/
 defaults: &defaults
   docker:
-    - image: cortexproject/build-image:master-94ba16ade
+    - image: cortexproject/build-image:master-d74af5958
   working_directory: /go/src/github.com/cortexproject/cortex
 
 workflows:
@@ -29,6 +29,13 @@ workflows:
         filters:
           tags:
             only: /^v[0-9]+(\.[0-9]+){2}(-.+|[^-.]*)$/
+    - deploy_website:
+        requires:
+        - test
+        - build
+        filters:
+          branches:
+            only: master
     - deploy:
         requires:
         - build
@@ -89,10 +96,10 @@ jobs:
         name: Integration Test
         command: |
           touch build-image/.uptodate
-          MIGRATIONS_DIR=$(pwd)/cmd/cortex/migrations make BUILD_IMAGE=cortexproject/build-image:master-94ba16ade configs-integration-test
+          MIGRATIONS_DIR=$(pwd)/cmd/cortex/migrations make BUILD_IMAGE=cortexproject/build-image:master-d74af5958 configs-integration-test
     - run:
         name: Load Images
-        command: ln -s /tmp/images ./images; make BUILD_IN_CONTAINER=false load-images
+        command: ln -s /tmp/images ./docker-images; make BUILD_IN_CONTAINER=false load-images
     - run:
         name: Ingester hand-over test
         command: ./integration-tests/test-handover.sh
@@ -114,6 +121,16 @@ jobs:
         command: |
           touch build-image/.uptodate
           make BUILD_IN_CONTAINER=false
+    - run:
+        name: Build Website
+        command: |
+          touch build-image/.uptodate
+          make BUILD_IN_CONTAINER=false web-build
+
+    - persist_to_workspace:
+        root: .
+        paths:
+          - website/public/
 
     - store_artifacts:
         path: pkg/querier/frontend/frontend.pb.go
@@ -130,14 +147,27 @@ jobs:
         name: Save Images
         command: |
           mkdir /tmp/images
-          ln -s /tmp/images ./images
+          ln -s /tmp/images ./docker-images
           make BUILD_IN_CONTAINER=false save-images
 
     - save_cache:
         key: v1-cortex-{{ .Branch }}-{{ .Revision }}
         paths:
         - /tmp/images/
 
+  deploy_website:
+    <<: *defaults
+    steps:
+    - add_ssh_keys:
+        fingerprints:
+        - "72:f2:e3:39:18:1f:95:17:90:b3:37:5e:49:ed:7e:a3"
+    - checkout
+    - attach_workspace:
+        at: .
+    - run:
+        name: deploy-website
+        command: make BUILD_IN_CONTAINER=false web-deploy
+
   deploy:
     <<: *defaults
     steps:
@@ -150,7 +180,7 @@ jobs:
 
     - run:
         name: Load Images
-        command: ln -s /tmp/images ./images; make BUILD_IN_CONTAINER=false load-images
+        command: ln -s /tmp/images ./docker-images; make BUILD_IN_CONTAINER=false load-images
 
     - run:
         name: Deploy

diff --git a/.gitignore b/.gitignore
@@ -3,4 +3,7 @@ cmd/cortex/cortex
 .uptodate
 .pkg
 .cache
-images/
+docker-images/
+website/public
+website/resources
+website/content/en/docs
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,4 @@
+
+[submodule "themes/docsy"]
+	path = website/themes/docsy
+	url = https://github.com/google/docsy
diff --git a/.lintignore b/.lintignore
@@ -3,3 +3,6 @@
 ./vendor*
 ./pkg/configs/legacy_promql*
 ./.pkg*
+./website/themes*
+./website/public*
+./website/resources*
diff --git a/Makefile b/Makefile
@@ -78,7 +78,7 @@ GO_FLAGS := -ldflags "-extldflags \"-static\" -s -w" -tags netgo
 
 ifeq ($(BUILD_IN_CONTAINER),true)
 
-exes $(EXES) protos $(PROTO_GOS) lint test shell mod-check check-protos: build-image/$(UPTODATE)
+exes $(EXES) protos $(PROTO_GOS) lint test shell mod-check check-protos web-build web-pre web-deploy: build-image/$(UPTODATE)
 	@mkdir -p $(shell pwd)/.pkg
 	@mkdir -p $(shell pwd)/.cache
 	@echo
@@ -146,6 +146,16 @@ mod-check:
 check-protos: clean-protos protos
 	@git diff --exit-code -- $(PROTO_GOS)
 
+web-pre:
+	cd website && git submodule update --init --recursive
+	./tools/website/web-pre.sh
+
+web-build: web-pre
+	cd website && HUGO_ENV=production hugo --config config.toml  --minify -v
+
+web-deploy:
+	./tools/website/web-deploy.sh
+
 endif
 
 clean:
@@ -157,17 +167,17 @@ clean-protos:
 	rm -rf $(PROTO_GOS)
 
 save-images:
-	@mkdir -p images
+	@mkdir -p docker-images
 	for image_name in $(IMAGE_NAMES); do \
 		if ! echo $$image_name | grep build; then \
-			docker save $$image_name:$(IMAGE_TAG) -o images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
+			docker save $$image_name:$(IMAGE_TAG) -o docker-images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
 		fi \
 	done
 
 load-images:
 	for image_name in $(IMAGE_NAMES); do \
 		if ! echo $$image_name | grep build; then \
-			docker load -i images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
+			docker load -i docker-images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
 		fi \
 	done
 
@@ -177,7 +187,10 @@ prime-minikube: save-images
 	eval $$(minikube docker-env) ; \
 	for image_name in $(IMAGE_NAMES); do \
 		if ! echo $$image_name | grep build; then \
-			docker load -i images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
+			docker load -i docker-images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
 			docker tag $$image_name:$(IMAGE_TAG) $$image_name:latest ; \
 		fi \
 	done
+
+web-serve:
+	cd website && hugo --config config.toml -v server
diff --git a/docs/_index.md b/docs/_index.md
@@ -0,0 +1,122 @@
+---
+title: "Documentation"
+linkTitle: "Documentation"
+weight: 1
+menu:
+  main:
+    weight: 1
+---
+<p align="center"><img width="200px" src="https://cncf-branding.netlify.com/img/projects/cortex/stacked/color/cortex-stacked-color.png" alt="Cortex Logo"></p>
+
+[![Circle CI](https://circleci.com/gh/cortexproject/cortex/tree/master.svg?style=shield)](https://circleci.com/gh/cortexproject/cortex/tree/master)
+[![GoDoc](https://godoc.org/github.com/cortexproject/cortex?status.svg)](https://godoc.org/github.com/cortexproject/cortex)
+<a href="https://goreportcard.com/report/github.com/cortexproject/cortex"><img src="https://goreportcard.com/badge/github.com/cortexproject/cortex" alt="Go Report Card" /></a>
+<a href="https://cloud-native.slack.com/messages/cortex/"><img src="https://img.shields.io/badge/join%20slack-%23cortex-brightgreen.svg" alt="Slack" /></a>
+
+
+Cortex provides horizontally scalable, highly available, multi-tenant, long term storage for
+[Prometheus](https://prometheus.io).
+
+- **Horizontally scalable:** Cortex can run across multiple machines in a cluster, exceeding the throughput and storage of a single machine. This enables you to send the metrics from multiple Prometheus servers to a single Cortex cluster and run "globally aggregated" queries across all data in a single place.
+- **Highly available:** When run in a cluster, Cortex can replicate data between machines. This allows you to survive machine failure without gaps in your graphs.
+- **Multi-tenant:** Cortex can isolate data and queries from multiple different independent
+Prometheus sources in a single cluster, allowing untrusted parties to share the same cluster.
+- **Long term storage:** Cortex supports Amazon DynamoDB, Google Bigtable, Cassandra, S3 and GCS for long term storage of metric data.  This allows you to durably store data for longer than the lifetime of any single machine, and use this data for long term capacity planning.
+
+Cortex is a [CNCF](https://cncf.io) sandbox project used in several production systems including [Weave Cloud](https://cloud.weave.works) and [Grafana Cloud](https://grafana.com/cloud).
+Cortex is primarily used used as a [remote write](https://prometheus.io/docs/operating/configuration/#remote_write) destination for Prometheus, exposing a Prometheus-compatible query API.
+
+## Documentation
+
+Read the [getting started guide](getting_started.md) if you're new to the
+project. Before deploying Cortex with a permanent storage backend you
+should read:
+
+1. [An overview of Cortex's architecture](architecture.md)
+1. [A general guide to running Cortex](running.md)
+1. [Information regarding configuring Cortex](arguments.md)
+
+For a guide to contributing to Cortex, see the [contributor guidelines](CONTRIBUTING.md).
+
+## Further reading
+
+To learn more about Cortex, consult the following documents & talks:
+
+- May 2019 KubeCon talks; "[Cortex: Intro][kubecon-cortex-intro]" ([video][kubecon-cortex-intro-video], [slides][kubecon-cortex-intro-slides], [blog post][kubecon-cortex-intro-blog]) and "[Cortex: Deep Dive][kubecon-cortex-deepdive]" ([video][kubecon-cortex-deepdive-video], [slides][kubecon-cortex-deepdive-slides])
+- Feb 2019 blog post & podcast; "[Prometheus Scalability with Bryan Boreham][prometheus-scalability]" ([podcast][prometheus-scalability-podcast])
+- Feb 2019 blog post; "[How Aspen Mesh Runs Cortex in Production][aspen-mesh-2019]"
+- Dec 2018 KubeCon talk; "[Cortex: Infinitely Scalable Prometheus][kubecon-2018-talk]" ([video][kubecon-2018-video], [slides][kubecon-2018-slides])
+- Dec 2018 CNCF blog post; "[Cortex: a multi-tenant, horizontally scalable Prometheus-as-a-Service][cncf-2018-blog]"
+- Nov 2018 CloudNative London meetup talk; "Cortex: Horizontally Scalable, Highly Available Prometheus" ([slides][cloudnative-london-2018-slides])
+- Nov 2018 CNCF TOC Presentation; "Horizontally Scalable, Multi-tenant Prometheus" ([slides][cncf-toc-presentation])
+- Sept 2018 blog post; "[What is Cortex?][what-is-cortex]"
+- Aug 2018 PromCon panel; "[Prometheus Long-Term Storage Approaches][promcon-2018-panel]" ([video][promcon-2018-video])
+- Jul 2018 design doc; "[Cortex Query Optimisations][cortex-query-optimisation-2018]"
+- Aug 2017 PromCon talk; "[Cortex: Prometheus as a Service, One Year On][promcon-2017-talk]" ([videos][promcon-2017-video], [slides][promcon-2017-slides], write up [part 1][promcon-2017-writeup-1], [part 2][promcon-2017-writeup-2], [part 3][promcon-2017-writeup-3])
+- Jun 2017 Prometheus London meetup talk; "Cortex: open-source, horizontally-scalable, distributed Prometheus" ([video][prometheus-london-2017-video])
+- Dec 2016 KubeCon talk; "Weave Cortex: Multi-tenant, horizontally scalable Prometheus as a Service" ([video][kubecon-2016-video], [slides][kubecon-2016-slides])
+- Aug 2016 PromCon talk; "Project Frankenstein: Multitenant, Scale-Out Prometheus": ([video][promcon-2016-video], [slides][promcon-2016-slides])
+- Jun 2016 design document; "[Project Frankenstein: A Multi Tenant, Scale Out Prometheus](http://goo.gl/prdUYV)"
+
+[kubecon-cortex-intro]: https://kccnceu19.sched.com/event/MPhX/intro-cortex-tom-wilkie-grafana-labs-bryan-boreham-weaveworks
+[kubecon-cortex-intro-video]: https://www.youtube.com/watch?v=_7Wnta-3-W0
+[kubecon-cortex-intro-slides]: https://static.sched.com/hosted_files/kccnceu19/af/Cortex%20Intro%20KubeCon%20EU%202019.pdf
+[kubecon-cortex-intro-blog]: https://grafana.com/blog/2019/05/21/grafana-labs-at-kubecon-the-latest-on-cortex/
+[kubecon-cortex-deepdive]: https://kccnceu19.sched.com/event/MPjK/deep-dive-cortex-tom-wilkie-grafana-labs-bryan-boreham-weaveworks
+[kubecon-cortex-deepdive-video]: https://www.youtube.com/watch?v=mYyFT4ChHio
+[kubecon-cortex-deepdive-slides]: https://static.sched.com/hosted_files/kccnceu19/52/Cortex%20Deep%20Dive%20KubeCon%20EU%202019.pdf
+[prometheus-scalability]: https://www.weave.works/blog/prometheus-scalability-with-bryan-boreham
+[prometheus-scalability-podcast]: https://softwareengineeringdaily.com/2019/01/21/prometheus-scalability-with-bryan-boreham/
+[aspen-mesh-2019]: https://www.weave.works/blog/how-aspen-mesh-runs-cortex-in-production
+[kubecon-2018-talk]: https://kccna18.sched.com/event/GrXL/cortex-infinitely-scalable-prometheus-bryan-boreham-weaveworks
+[kubecon-2018-video]: https://www.youtube.com/watch?v=iyN40FsRQEo
+[kubecon-2018-slides]: https://static.sched.com/hosted_files/kccna18/9b/Cortex%20CloudNativeCon%202018.pdf
+[cloudnative-london-2018-slides]: https://www.slideshare.net/grafana/cortex-horizontally-scalable-highly-available-prometheus
+[cncf-2018-blog]: https://www.cncf.io/blog/2018/12/18/cortex-a-multi-tenant-horizontally-scalable-prometheus-as-a-service/
+[cncf-toc-presentation]: https://docs.google.com/presentation/d/190oIFgujktVYxWZLhLYN4q8p9dtQYoe4sxHgn4deBSI/edit#slide=id.g3b8e2d6f7e_0_6
+[what-is-cortex]: https://medium.com/weaveworks/what-is-cortex-2c30bcbd247d
+[promcon-2018-panel]: https://promcon.io/2018-munich/talks/panel-discussion-prometheus-long-term-storage-approaches/
+[promcon-2018-video]: https://www.youtube.com/watch?v=3pTG_N8yGSU
+[prometheus-london-2017-video]: https://www.youtube.com/watch?v=Xi4jq2IUbLs
+[promcon-2017-talk]: https://promcon.io/2017-munich/talks/cortex-prometheus-as-a-service-one-year-on/
+[promcon-2017-video]: https://www.youtube.com/watch?v=_8DmPW4iQBQ
+[promcon-2017-slides]: https://promcon.io/2017-munich/slides/cortex-prometheus-as-a-service-one-year-on.pdf
+[promcon-2017-writeup-1]: https://kausal.co/blog/cortex-prometheus-aas-promcon-1/
+[promcon-2017-writeup-2]: https://kausal.co/blog/cortex-prometheus-aas-promcon-2/
+[promcon-2017-writeup-3]: https://kausal.co/blog/cortex-prometheus-aas-promcon-3/
+[cortex-query-optimisation-2018]: https://docs.google.com/document/d/1lsvSkv0tiAMPQv-V8vI2LZ8f4i9JuTRsuPI_i-XcAqY
+[kubecon-2016-video]: https://www.youtube.com/watch?v=9Uctgnazfwk
+[kubecon-2016-slides]: http://www.slideshare.net/weaveworks/weave-cortex-multitenant-horizontally-scalable-prometheus-as-a-service
+[promcon-2016-video]: https://youtu.be/3Tb4Wc0kfCM
+[promcon-2016-slides]: http://www.slideshare.net/weaveworks/project-frankenstein-a-multitenant-horizontally-scalable-prometheus-as-a-service
+
+## <a name="help"></a>Getting Help
+
+If you have any questions about Cortex:
+
+- Ask a question on the [Cortex Slack channel](https://cloud-native.slack.com/messages/cortex/). To invite yourself to the CNCF Slack, visit http://slack.cncf.io/.
+- <a href="https://github.com/cortexproject/cortex/issues/new">File an issue.</a>
+- Send an email to <a href="mailto:[email protected]">[email protected]</a>
+
+Your feedback is always welcome.
+
+## Hosted Cortex (Prometheus as a service)
+
+There are several commercial services where you can use Cortex
+on-demand:
+
+### Weave Cloud
+
+[Weave Cloud](https://cloud.weave.works) from
+[Weaveworks](https://weave.works) lets you deploy, manage, and monitor
+container-based applications. Sign up at https://cloud.weave.works
+and follow the instructions there. Additional help can also be found
+in the [Weave Cloud documentation](https://www.weave.works/docs/cloud/latest/overview/).
+
+[Instrumenting Your App: Best Practices](https://www.weave.works/docs/cloud/latest/tasks/monitor/best-instrumenting/)
+
+### Grafana Cloud
+
+To use Cortex as part of Grafana Cloud, sign up for [Grafana Cloud](https://grafana.com/cloud)
+by clicking "Log In" in the top right and then "Sign Up Now".  Cortex is included
+as part of the Starter and Basic Hosted Grafana plans.
diff --git a/docs/apis.md b/docs/apis.md
@@ -1,4 +1,9 @@
-# Cortex APIs
+---
+title: "Cortex APIs"
+linkTitle: "Cortex APIs"
+weight: 5
+slug: apis
+---
 
 [this is a work in progress]
 
@@ -33,7 +38,7 @@ The following schema is used both when retrieving the current configs from the A
     "rule_format_version": "2",
     "config": {
         "alertmanager_config": "<standard alertmanager.yaml config>",
-        "rules_files": { 
+        "rules_files": {
             "rules.yaml": "<standard rules.yaml config>",
             "rules2.yaml": "<standard rules.yaml config>"
          },
@@ -75,14 +80,14 @@ The following schema is used both when retrieving the current configs from the A
 
 Normal Response: OK(200)
 ```json
-{ 
+{
     "status": "success"
 }
 ```
 
 Error Response: BadRequest(400)
 ```json
-{ 
+{
     "status": "error",
     "error": "error message"
 }

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,8 +1,13 @@
-# Cortex Architecture
+---
+title: "Cortex Architecture"
+linkTitle: "Cortex Architecture"
+weight: 4
+slug: architecture
+---
 
 Cortex consists of multiple horizontally scalable microservices. Each microservice uses the most appropriate technique for horizontal scaling; most are stateless and can handle requests for any users while some (namely the [ingesters](#ingester)) are semi-stateful and depend on consistent hashing. This document provides a basic overview of Cortex's architecture.
 
-<p align="center"><img src="architecture.png" alt="Cortex Architecture"></p>
+<p align="center"><img src="../images/architecture.png" alt="Cortex Architecture"></p>
 
 ## The role of Prometheus
 

diff --git a/docs/configuration/_index.md b/docs/configuration/_index.md
@@ -0,0 +1,6 @@
+---
+title: "Configuration"
+linkTitle: "Configuration"
+weight: 7
+menu:
+---