Merge pull request kubernetes#6 from lucperkins/lperkins/getting-star…

…ted-guide [WIP] Add download/build doc
philips · Jan 9, 2019 · 4661905 · 4661905
2 parents f2b5f92 + a77d4f0
commit 4661905
Show file tree

Hide file tree

Showing 23 changed files with 284 additions and 87 deletions.
diff --git a/assets/js/app.js b/assets/js/app.js
@@ -0,0 +1,7 @@
+document.addEventListener("DOMContentLoaded", function(e) {
+  anchors.options = {
+    icon: '#'
+  }
+
+  anchors.add('.docs-content h2, .docs-content h3');
+});
diff --git a/assets/sass/style.sass b/assets/sass/style.sass
@@ -30,6 +30,7 @@ $toc-item-font-size: 1.5rem
 $dashboard-panel-padding: 2rem 1.25rem 5rem 1.25rem
 $dashboard-panel-header-bottom-margin: 1.5rem
 $dashboard-panel-footer-top-margin: 3rem
+$section-padding: 2rem
 
 @import "bulma/sass/utilities/derived-variables"
 @import "bulma/bulma"
@@ -49,6 +50,14 @@ $dashboard-panel-footer-top-margin: 3rem
   +desktop
     width: $desktop
 
+.toc-title
+  font-size: 1.5rem
+  font-weight: 400
+  line-height: 100%
+  margin-bottom: 1rem
+  color: $primary
+
+
 .is-hero-logo
   +logo(60%, 30%)
   margin-bottom: 1.75rem
@@ -96,12 +105,18 @@ $dashboard-panel-footer-top-margin: 3rem
 
   svg
     height: 7.5rem
-
-=x
-  border: 1px solid red
-
-.dashboard-panel
-  border-right: 1px solid $grey-lighter
+
+#TableOfContents
+  li
+    a
+      line-height: 100%
+
+      &:hover
+        code
+          color: $grey-lighter
+      code
+        padding: .25rem
+        background-color: $black
 
 .docs-panel
   line-height: 120%

diff --git a/config.toml b/config.toml
@@ -27,6 +27,9 @@ etcd is written in [Go](https://golang.org), which has excellent cross-platform
 Latency from the etcd leader is the most important metric to track and the built-in dashboard has a view dedicated to this. In our testing, severe latency will introduce instability within the cluster because Raft is only as fast as the slowest machine in the majority. You can mitigate this issue by properly tuning the cluster. etcd has been pre-tuned on cloud providers with highly variable networks.
 """
 
+[params.versions]
+latest = "3.3.10"
+
 [params.logos]
 hero   = "https://raw.githubusercontent.com/cncf/artwork/master/etcd/horizontal/white/etcd-horizontal-white.png"
 cncf   = "https://raw.githubusercontent.com/cncf/artwork/master/cncf/horizontal/color/cncf-color.png"

diff --git a/content/docs/_index.md b/content/docs/_index.md
@@ -1,5 +1,6 @@
 ---
-title: The etcd documentation
+title: Overview
+description: "**etcd**: a distributed, reliable key-value store for the most critical data of a distributed system"
 ---
 
 [**etcd**](/) is a distributed key-value store designed to reliably and quickly preserve and provide access to critical data. It enables reliable distributed coordination through distributed locking, leader elections, and write barriers. An etcd cluster is intended for high availability and permanent data storage and retrieval.
@@ -10,18 +11,9 @@ This documentation is a work in progress. Please check back soon for more update
 
 These docs cover everything from setting up and running an etcd cluster to using etcd in your applications. Improvements to these docs are encouraged through PRs to the etcd project on GitHub. For more in-depth support, jump into #coreos on IRC, email the dev list, or file a bug.
 
-```go
-package main
-
-func main() {
-        println("Welcome to the etcd docs! This code sample is just a placeholder")
-        // And here's a comment
-}
-```
-
 ## Getting started
 
-New etcd users and developers can get started by [downloading and building etcd](getting-started)
+New etcd users and developers can get started by [downloading and building etcd](download-build),
 
 ## Support
 

diff --git a/content/docs/download-build.md b/content/docs/download-build.md
@@ -1,13 +1,150 @@
 ---
 title: Download and build etcd
+description: Run etcd locally on [Linux](#linux), [macOS](#macos), and [Docker](#docker) using [static binaries](#binary). Or build [from source](#source).
 ---
 
+There are two main ways to install etcd and etcdctl:
+
+* From [static binaries](#binary)
+* By building [from source](#source)
+
+{{< info >}}
+The instructions in this document are for the latest version of etcd, version **{{< latest >}}**.
+{{< /info >}}
+
 {{< requirement title="System requirements" >}}
 The etcd performance benchmarks run etcd on:
 
 * 8 vCPU
 * 16GB RAM
-* 50GB SSD [Google Compute Engine](https://cloud.google.com/compute/) (GCE)
+* 50GB SSD [Google Compute Engine](https://cloud.google.com/compute/) (GCE) instances
 
 Any relatively modern machine with low latency storage and a few gigabytes of memory, however, should suffice for most use cases. Applications with large v2 data stores will require more memory than a large v3 data store since data is kept in anonymous memory instead of memory mapped from a file. For running etcd on a cloud provider, we suggest at least a medium instance on AWS or a [standard-1](https://cloud.google.com/compute/docs/machine-types#standard_machine_types) instance on GCE.
 {{< /requirement >}}
+
+## Installing from a pre-built binary {#binary}
+
+The easiest way to install etcd is by fetching one of the binaries available for [Linux](#linux), [macOS](#macos), and [Docker](#docker). All binaries are available via both Google Cloud Storage and [GitHub Releases](https://github.com/etcd-io/etcd/releases/download).
+
+### Linux
+
+The following will install two executables, `etcd` and `etcdctl`, in a temporary directory at `/tmp/etcd-download-test`:
+
+```bash
+ETCD_VER=v{{< latest >}}
+
+# choose either URL
+GOOGLE_URL=https://storage.googleapis.com/etcd
+GITHUB_URL=https://github.com/etcd-io/etcd/releases/download
+ROOT_URL=${GOOGLE_URL} # or set to GITHUB_URL
+DOWNLOAD_URL=${ROOT_URL}/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz
+
+rm -f /tmp/etcd-${ETCD_VER}-linux-amd64.tar.gz
+rm -rf /tmp/etcd-download-test && mkdir -p /tmp/etcd-download-test
+
+curl -L ${DOWNLOAD_URL} -o /tmp/etcd-${ETCD_VER}-linux-amd64.tar.gz
+tar xzvf /tmp/etcd-${ETCD_VER}-linux-amd64.tar.gz -C /tmp/etcd-download-test --strip-components=1
+rm -f /tmp/etcd-${ETCD_VER}-linux-amd64.tar.gz
+
+# Add the temporary dir to your path
+PATH=/tmp/etcd-download-test:${PATH}
+
+etcd --version
+# should return "etcd Version: {{< latest >}}"
+
+ETCDCTL_API=3 etcdctl version
+# should return "etcd Version: {{< latest >}}"
+```
+
+### macOS
+
+The following will install two executables, `etcd` and `etcdctl`, in a temporary directory at `/tmp/etcd-download-test`:
+
+```bash
+ETCD_VER=v{{< latest >}}
+
+# choose either URL
+GOOGLE_URL=https://storage.googleapis.com/etcd
+GITHUB_URL=https://github.com/etcd-io/etcd/releases/download
+ROOT_URL=${GOOGLE_URL} # or set to GITHUB_URL
+DOWNLOAD_URL=${ROOT_URL}/${ETCD_VER}/etcd-${ETCD_VER}-darwin-amd64.zip
+
+rm -f /tmp/etcd-${ETCD_VER}-darwin-amd64.zip
+rm -rf /tmp/etcd-download-test && mkdir -p /tmp/etcd-download-test
+
+curl -L ${DOWNLOAD_URL} -o /tmp/etcd-${ETCD_VER}-darwin-amd64.zip
+unzip /tmp/etcd-${ETCD_VER}-darwin-amd64.zip -d /tmp && rm -f /tmp/etcd-${ETCD_VER}-darwin-amd64.zip
+mv /tmp/etcd-${ETCD_VER}-darwin-amd64/* /tmp/etcd-download-test && rm -rf mv /tmp/etcd-${ETCD_VER}-darwin-amd64
+
+# Add the temporary dir to your path
+PATH=/tmp/etcd-download-test:${PATH}
+
+etcd --version
+# should return "etcd Version: {{< latest >}}"
+
+ETCDCTL_API=3 etcdctl version
+# should return "etcd Version: {{< latest >}}"
+```
+
+### Docker
+
+[Docker](https://docker.com) images for etcd are hosted in [Google Container Registry](https://gcr.io), under the [etcd-development/etcd](https://gcr.io/etcd-development/etcd) project.
+
+The image for the latest version of etcd is `gcr.io/etcd-development/etcd:v{{< latest >}}`.
+
+To run the locally (applying the name `etcd` to the image):
+
+```bash
+docker run --name etcd \
+  gcr.io/etcd-development/etcd:{{< latest >}}
+```
+
+Here are some example commands to execute against the running container:
+
+```bash
+docker exec etcd /bin/sh -c "/usr/local/bin/etcd --version"
+docker exec etcd /bin/sh -c "ETCDCTL_API=3 /usr/local/bin/etcdctl version"
+docker exec etcd /bin/sh -c "ETCDCTL_API=3 /usr/local/bin/etcdctl endpoint health"
+docker exec etcd /bin/sh -c "ETCDCTL_API=3 /usr/local/bin/etcdctl put foo bar"
+docker exec etcd /bin/sh -c "ETCDCTL_API=3 /usr/local/bin/etcdctl get foo"
+```
+
+To kill the running container:
+
+```bash
+docker kill etcd
+```
+
+## Building etcd from source {#source}
+
+In addition to installing etcd from [static binaries](#binary), you can also build etcd from source using the [etcd-io/etcd](https://github.com/etcd-io/etcd) repository on [GitHub](https://github.com).
+
+{{< requirement title="Install Go first" >}}
+In order to install etcd from source, you'll need to install [Go](https://golang.org) version **1.8 or above**.
+{{< /requirement >}}
+
+### Outside of `GOPATH`
+
+```bash
+git clone https://github.com/etcd-io/etcd.git
+cd etcd
+./build
+
+# run the resulting executable
+./bin/etcd
+```
+
+### Using `go get`
+
+If you have `GOPATH` set:
+
+```bash
+echo $GOPATH
+
+go get github.com/etcd-io/etcd/cmd/etcd
+
+# run the resulting executable
+$GOPATH/bin/etcd
+```
+
+## 
diff --git a/layouts/_default/baseof.en.html b/layouts/_default/baseof.en.html
@@ -12,5 +12,7 @@
   <body class="page">
     {{ block "main" . }}
     {{ end }}
+
+    {{ partial "javascript.html" . }}
   </body>
 </html>
diff --git a/layouts/docs/section.en.html b/layouts/docs/section.en.html
@@ -9,51 +9,11 @@
   <div class="dashboard-main is-scrollable">
     {{ partial "docs/hero.html" . }}
 
-    <section class="section">
-      <div class="content">
-        {{ .Content }}
+    {{ partial "docs/article.html" . }}
 
-        {{ with .Pages }}
-        <h3>
-          Pages in this section
-        </h3>
-
-        <ul>
-          {{ range . }}
-          <li>
-            <a href="{{ .URL }}">
-              {{ .Title }}
-            </a>
-          </li>
-          {{ end }}
-        </ul>
-        {{ end }}
-      </div>
+    {{ partial "docs/listing.html" . }}
 
-      <div class="columns is-multiline">
-        {{ with .Sections }}
-        {{ range . }}
-        <div class="column is-3">
-          <a class="is-size-3 is-size-4-mobile has-text-weight-light" href="{{ .URL }}">
-            {{ .Title }}
-          </a>
-
-          <br />
-
-          <ul>
-            {{ range .Pages }}
-            <li>
-              <a href="{{ .URL }}">
-                {{ .Title }}
-              </a>
-            </li>
-            {{ end }}
-          </ul>
-        </div>
-        {{ end }}
-        {{ end }}
-      </div>
-    </section>
+    {{ partial "footer.html" . }}
   </div>
 
   {{ partial "docs/toc.html" . }}

diff --git a/layouts/docs/single.en.html b/layouts/docs/single.en.html
@@ -3,5 +3,19 @@
 {{ end }}
 
 {{ define "main" }}
-{{ partial "docs/dashboard.html" . }}
+<div class="dashboard">
+  {{ partial "docs/nav-panel.html" . }}
+
+  <div class="dashboard-main is-scrollable">
+    {{ partial "docs/hero.html" . }}
+
+    {{ partial "docs/article.html" . }}
+
+    {{ partial "docs/listing.html" . }}
+
+    {{ partial "footer.html" . }}
+  </div>
+
+  {{ partial "docs/toc.html" . }}
+</div>
 {{ end }}
diff --git a/layouts/index.en.html b/layouts/index.en.html
@@ -13,5 +13,5 @@
   {{ partial "home/coming-soon.html" . }}
 </div>
 
-{{ partial "home/footer.html" . }}
+{{ partial "footer.html" . }}
 {{ end }}
diff --git a/layouts/partials/docs/article.html b/layouts/partials/docs/article.html
@@ -1,5 +1,5 @@
 <section class="section">
-  <div class="content">
+  <div class="content docs-content">
     {{ .Content }}
   </div>
 </section>
diff --git a/layouts/partials/docs/hero.html b/layouts/partials/docs/hero.html
@@ -1,7 +1,12 @@
 <section class="hero is-primary">
   <div class="hero-body">
-    <p class="title is-size-1 is-size-2-mobile has-text-weight-light">
+    <p class="title is-size-1 is-size-2-mobile has-text-weight-light{{ if .Params.description }} is-spaced{{ end }}">
       {{ .Title }}
     </p>
+    {{ with .Params.description }}
+    <p class="subtitle is-size-4 is-size-5-mobile">
+      {{ . | markdownify }}
+    </p>
+    {{ end }}
   </div>
 </section>