Merge pull request #528 from smallstep/max/install

dopey · web-flow · commit 7d119c23fc36 · 2021-04-06T13:02:47.000-07:00
Updates to README
diff --git a/README.md b/README.md
@@ -22,8 +22,7 @@ Whatever your use case, `step-ca` is easy to use and hard to misuse, thanks to [
 
 [Website](https://smallstep.com/certificates) |
 [Documentation](https://smallstep.com/docs) |
-[Installation Guide](#installation-guide) |
-[Quickstart](#quickstart) |
+[Installation](https://smallstep.com/docs/step-ca/installation) |
 [Getting Started](https://smallstep.com/docs/step-ca/getting-started) |
 [Contributor's Guide](./docs/CONTRIBUTING.md)
 
@@ -103,270 +102,9 @@ ACME is the protocol used by Let's Encrypt to automate the issuance of HTTPS cer
 - [Install root certificates](https://smallstep.com/docs/step-cli/reference/certificate/install/) on your machine and browsers, so your CA is trusted
 - [Inspect](https://smallstep.com/docs/step-cli/reference/certificate/inspect/) and [lint](https://smallstep.com/docs/step-cli/reference/certificate/lint/) certificates
 
-## Installation Guide
+## Installation
 
-These instructions will install an OS specific version of the `step-ca` binary on
-your local machine.
-
-Want to build from source? See [our contributor's guide](./docs/CONTRIBUTING.md)
-
-### Mac OS
-
-Install `step`  and `step-ca` together, via [Homebrew](https://brew.sh/):
-
-```
-$ brew install step
-```
-
-### Linux
-
-> **Note:** The [`step` CLI tool](https://github.com/smallstep/cli) is the easiest way to initialize, configure, and control `step-ca`. While `step` is not technically required to run `step-ca`, it is very much recommended.
-
-#### Debian
-
-1. Install `step`.
-
-    Download the Debian package from the
-    [latest `step` release](https://github.com/smallstep/cli/releases/latest):
-
-    ```
-    $ wget https://github.com/smallstep/cli/releases/download/vX.Y.Z/step-cli_X.Y.Z_amd64.deb
-    ```
-
-    Install the Debian package:
-
-    ```
-    $ sudo dpkg -i step-cli_X.Y.Z_amd64.deb
-    ```
-
-2. Install `step-ca`.
-
-    Download the Debian package from the [latest `step-ca` release](https://github.com/smallstep/certificates/releases/latest):
-
-    ```
-    $ wget https://github.com/smallstep/certificates/releases/download/vX.Y.Z/step-ca_X.Y.Z_amd64.deb
-    ```
-
-    Install the Debian package:
-
-    ```
-    $ sudo dpkg -i step-ca_X.Y.Z_amd64.deb
-    ```
-
-#### Arch Linux
-
-We are using the [Arch User Repository](https://aur.archlinux.org) to distribute
-`step` binaries for Arch Linux.
-
-* The `step` binary tarball can be found [here](https://aur.archlinux.org/packages/step-cli-bin/).
-* The `step-ca` binary tarball can be found [here](https://aur.archlinux.org/packages/step-ca-bin/).
-
-You can use [pacman](https://www.archlinux.org/pacman/) to install the packages.
-
-#### RHEL/CentOS
-
-1. Install `step`.
-
-    Download the Linux tarball from the
-    [latest `step` release](https://github.com/smallstep/cli/releases/latest):
-
-    ```
-    $ wget -O step-cli.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz
-    ```
-
-    Install `step` by unzipping and copying the executable over to `/usr/bin`:
-
-    ```
-    $ tar -xf step-cli.tar.gz
-    $ sudo cp step_X.Y.Z/bin/step /usr/bin
-    ```
-
-2. Install `step-ca`.
-
-    Download the Linux package from the [latest `step-ca` release](https://github.com/smallstep/certificates/releases/latest):
-
-    ```
-    $ wget -O step-ca.tar.gz https://github.com/smallstep/certificates/releases/download/vX.Y.Z/step-ca_linux_X.Y.Z_amd64.tar.gz
-    ```
-
-    Install `step-ca` by unzipping and copying the executable over to `/usr/bin`:
-
-    ```
-    $ tar -xf step-ca.tar.gz
-    $ sudo cp step-ca_X.Y.Z/bin/step-ca /usr/bin
-    ```
-
-See the [`systemctl` setup section](https://smallstep.com/docs/step-ca/certificate-authority-server-production#running-step-ca-as-a-daemon) for a
-guide on configuring `step-ca` as a daemon.
-
-### Kubernetes
-
-We publish [helm charts](https://hub.helm.sh/charts/smallstep/step-certificates) for easy installation on kubernetes:
-
-```
-helm install step-certificates
-```
-
-> <a href="https://github.com/smallstep/autocert"><img width="25%" src="https://raw.githubusercontent.com/smallstep/autocert/master/autocert-logo.png"></a>
->
-> If you're using Kubernetes, make sure you [check out
-> autocert](https://github.com/smallstep/autocert): a kubernetes add-on that builds on `step
-> certificates` to automatically inject TLS/HTTPS certificates into your containers.
-
-### Docker
-
-See our [Docker getting started guide](https://smallstep.com/docs/tutorials/docker-tls-certificate-authority)
-
-### Test
-
-<pre><code><b>$ step version</b>
-Smallstep CLI/0.10.0 (darwin/amd64)
-Release Date: 2019-04-30 19:01 UTC
-
-<b>$ step-ca version</b>
-Smallstep CA/0.10.0 (darwin/amd64)
-Release Date: 2019-04-30 19:02 UTC</code></pre>
-
-## Quickstart
-
-In the following guide we'll run a simple `hello` server that requires clients
-to connect over an authorized and encrypted channel using HTTPS. `step-ca`
-will issue certificates to our server, allowing it to authenticate and encrypt
-communication.
-
-![Animated terminal showing step certificates in practice](https://github.com/smallstep/certificates/raw/master/docs/images/step-ca-2-legged.gif)
-
-Let's get started!
-
-### Prerequisites
-
-* [`step`](#installation-guide)
-* [golang](https://golang.org/doc/install)
-
-### Let's get started!
-
-#### 1. Run `step ca init` to create your CA's keys & certificates and configure `step-ca`:
-
-<pre><code><b>$ step ca init</b>
-✔ What would you like to name your new PKI? (e.g. Smallstep): <b>Example Inc.</b>
-✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): <b>localhost</b>
-✔ What address will your new CA listen at? (e.g. :443): <b>127.0.0.1:8080</b>
-✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): <b>bob@example.com</b>
-✔ What do you want your password to be? [leave empty and we'll generate one]: <b>abc123</b>
-
-Generating root certificate...
-all done!
-
-Generating intermediate certificate...
-all done!
-
-✔ Root certificate: /Users/bob/src/github.com/smallstep/step/.step/certs/root_ca.crt
-✔ Root private key: /Users/bob/src/github.com/smallstep/step/.step/secrets/root_ca_key
-✔ Root fingerprint: 702a094e239c9eec6f0dcd0a5f65e595bf7ed6614012825c5fe3d1ae1b2fd6ee
-✔ Intermediate certificate: /Users/bob/src/github.com/smallstep/step/.step/certs/intermediate_ca.crt
-✔ Intermediate private key: /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key
-✔ Default configuration: /Users/bob/src/github.com/smallstep/step/.step/config/defaults.json
-✔ Certificate Authority configuration: /Users/bob/src/github.com/smallstep/step/.step/config/ca.json
-
-Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.</code></pre>
-
-This command will:
-
-- Generate [password protected](https://github.com/smallstep/certificates/blob/master/docs/GETTING_STARTED.md#passwords)  private keys for your CA to sign certificates
-- Generate a root and [intermediate signing certificate](https://security.stackexchange.com/questions/128779/why-is-it-more-secure-to-use-intermediate-ca-certificates) for your CA
-- Create a JSON configuration file for `step-ca` (see [configuration docs](https://smallstep.com/docs/step-ca/configuration) for details)
-
-You can find these artifacts in `$STEPPATH` (or `~/.step` by default).
-
-#### 2. Start `step-ca`:
-
-You'll be prompted for your password from the previous step, to decrypt the CA's private signing key:
-
-<pre><code><b>$ step-ca $(step path)/config/ca.json</b>
-Please enter the password to decrypt /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key: <b>abc123</b>
-2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8080 ...</code></pre>
-
-#### 3. Copy our `hello world` golang server.
-
-```
-$ cat > srv.go <<EOF
-package main
-
-import (
-    "net/http"
-    "log"
-)
-
-func HiHandler(w http.ResponseWriter, req *http.Request) {
-    w.Header().Set("Content-Type", "text/plain")
-    w.Write([]byte("Hello, world!\n"))
-}
-
-func main() {
-    http.HandleFunc("/hi", HiHandler)
-    err := http.ListenAndServeTLS(":8443", "srv.crt", "srv.key", nil)
-    if err != nil {
-        log.Fatal(err)
-    }
-}
-EOF
-```
-
-#### 4. Get an identity for your server from the Step CA.
-
-<pre><code><b>$ step ca certificate localhost srv.crt srv.key</b>
-✔ Key ID: rQxROEr7Kx9TNjSQBTETtsu3GKmuW9zm02dMXZ8GUEk (bob@example.com)
-✔ Please enter the password to decrypt the provisioner key: abc123
-✔ CA: https://localhost:8080/1.0/sign
-✔ Certificate: srv.crt
-✔ Private Key: srv.key
-
-<b>$ step certificate inspect --bundle srv.crt</b>
-Certificate:
-    Data:
-        Version: 3 (0x2)
-        Serial Number: 140439335711218707689123407681832384336 (0x69a7a1d7f6f22f68059d2d9088307750)
-    Signature Algorithm: ECDSA-SHA256
-        Issuer: CN=Example Inc. Intermediate CA
-        Validity
-            Not Before: Feb 18 21:32:35 2019 UTC
-            Not After : Feb 19 21:32:35 2019 UTC
-        Subject: CN=localhost
-...
-Certificate:
-    Data:
-        Version: 3 (0x2)
-        Serial Number: 207035091234452090159026162349261226844 (0x9bc18217bd560cf07db23178ed90835c)
-    Signature Algorithm: ECDSA-SHA256
-        Issuer: CN=Example Inc. Root CA
-        Validity
-            Not Before: Feb 18 21:27:21 2019 UTC
-            Not After : Feb 15 21:27:21 2029 UTC
-        Subject: CN=Example Inc. Intermediate CA
-...</code></pre>
-
-Note that `step` and `step-ca` handle details like [certificate bundling](https://smallstep.com/blog/everything-pki.html#intermediates-chains-and-bundling) for you.
-
-#### 5. Run the simple server.
-
-<pre><code><b>$ go run srv.go &</b></code></pre>
-
-#### 6. Get the root certificate from the Step CA.
-
-In a new Terminal window:
-
-<pre><code><b>$ step ca root root.crt</b>
-The root certificate has been saved in root.crt.</code></pre>
-
-#### 7. Make an authenticated, encrypted curl request to your server using HTTP over TLS.
-
-<pre><code><b>$ curl --cacert root.crt https://localhost:8443/hi</b>
-Hello, world!</code></pre>
-
-*All Done!*
-
-Check out the [Getting Started](./docs/GETTING_STARTED.md) guide for more examples
-and best practices on running Step CA in production.
+See our installation docs [here](https://smallstep.com/docs/step-ca/installation).
 
 ## Documentation
 
