Browse Source

the beginnings of docs intended for Github Pages

sungo 1 year ago
parent
commit
b72596055e
8 changed files with 327 additions and 58 deletions
  1. 4 58
      README.md
  2. 4 0
      docs/.gitignore
  3. 4 0
      docs/Gemfile
  4. 11 0
      docs/Makefile
  5. 145 0
      docs/auth.md
  6. 95 0
      docs/index.md
  7. BIN
      docs/joyent.png
  8. 64 0
      docs/tokens.md

+ 4 - 58
README.md

@@ -2,24 +2,12 @@
 
 `conch` is a CLI for accessing the [Conch](https://github.com/joyent/conch) API.
 
-[![Go Report Card](https://goreportcard.com/badge/joyent/conch-shell)](https://goreportcard.com/report/joyent/conch-shell)
+# Documentation
 
-# Getting The App
+Documentation, including the build process, can be found
+[here](https://joyent.github.io/conch-shell)
 
-## Binaries
-
-Releases are available over at https://github.com/joyent/conch-shell/releases
-for a handful of platforms, including macOS, Linux, and Solaris/SmartOS.
-
-## Docker
-
-Images are available on Docker Hub ( https://hub.docker.com/r/joyentbuildops/conch-shell/ ).
-To sucessfully run the app, the app needs a persistent `.conch.json` file
-mounted in `/root`. An example run line is:
-
-```
-docker run --rm -it -v /home/user/.conch.json:/root/.conch.json joyent/conch-shell:latest profile ls
-```
+# Notes
 
 ## Joyent Employees
 
@@ -31,8 +19,6 @@ The most recent release is *not* certified for production yet (thus the
 'pre-release' tag) and probably works best against the staging instance. Grab
 it at https://github.com/joyent/conch-shell/releases
 
-# Notes
-
 ## SSL Certs
 
 Go makes a lot of assumptions about a user's runtime environment. One assumption
@@ -46,7 +32,6 @@ To set a custom location for SSL certs, one can specify `SSL_CERT_DIR` or
 
 For instance: `SSL_CERT_FILE=/opt/certs.pem conch login`
 
-
 # Copyright / License
 
 Copyright Joyent Inc
@@ -55,42 +40,3 @@ This Source Code Form is subject to the terms of the Mozilla Public
 License, v. 2.0. If a copy of the MPL was not distributed with this
 file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-# Building
-
-## Manual
-
-* `go get github.com/joyent/conch-shell`. This installs the code at
-  `$GOPATH/src/github.com/joyent/conch-shell`
-* In the `conch-shell` checkout:
-	* `make tools` - Install the necessary build tools
-	* `make` - Build the application
-
-*Always* use the Makefile to build the app, rather than `go build`. The
-Makefile passes necessary build vars into the app.
-
-## Docker
-
-Joyent's test and release process uses Docker. If you'd like to use that
-process as well, use the following Makefile targets:
-
-* `make docker_test` - Copies the local source code into the container, builds
-  the app, runs the test suite, and then runs `conch version` to verify basic
-  functionality
-
-* `make docker_release` - Checks the provided version from git and
-  executes `make release`, dropping the results in the local
-  `release` directory.
-
-## Reproducible Builds
-
-As of 1841c57, our build process no longer inserts local values that break
-reproducible builds. Using docker and our `make docker_release` process, one
-should be able to reproduce our builds and validate via checksum.
-
-However, at time of writing, go itself does not support reproducible builds
-when `GOPATH` changes, since it embeds that path in the binary for "debugging"
-purposes. It is not possible to reproduce our builds outside the docker build
-environment. 
-
-This issue is being tracked at https://github.com/golang/go/issues/16860
-

+ 4 - 0
docs/.gitignore

@@ -0,0 +1,4 @@
+.bundle
+vendor
+Gemfile.lock
+_site

+ 4 - 0
docs/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+gem "jekyll"
+gem "github-pages", group: :jekyll_plugins
+

+ 11 - 0
docs/Makefile

@@ -0,0 +1,11 @@
+default: vendor serve
+
+build:
+	bundle exec jekyll build
+
+serve:
+	bundle exec jekyll serve
+
+vendor:
+	bundle install --path vendor/bundle
+

+ 145 - 0
docs/auth.md

@@ -0,0 +1,145 @@
+# Authentication
+
+The first step is to get logged in. You will need an account on an instance of
+the Conch API. Please work with an admin and get all squared away. Make sure you
+can log into the web UI before continuing here.
+
+## Using Password Auth
+
+A new profile is be created via:
+```
+conch profile new --name <profile name> --user user@example.com
+```
+
+You can provide your password via the `--password` argument.  Otherwise, you
+will be prompted for your password. 
+
+For Joyent employees, this will attempt to log you into the production instance.
+If you'd like to use staging, provide the `--environment=staging` argument. For
+development or non-Joyent users, provide `--environment=development
+--url=https://joyent.example.com`, adjusting the URL as appropriate for your
+environment.
+
+For instance:
+```
+conch profile new --name <profile name> --user user@example.com --environment=staging
+```
+or 
+
+```
+conch profile new --name <profile name> --user user@example.com --environment=development --url http://localhost:5000
+```
+
+### Expiration
+
+Password authentication credentials expire rather rapidly, on the order of 30
+days. If you do not use the shell for 30 days, you may receive an "unauthorized"
+error message. To log back in, simply execute
+
+```
+conch profile relogin
+```
+
+You will be prompted for your password.
+
+### Forced Password Change
+
+Sometimes, you might be forced to change your password, usually because you
+requested a password reset or an admin reset your password. Typically, you will
+receive an "unauthorized" message. You should try to `relogin` and will then be
+prompted to change your password.
+
+
+## Using API Tokens
+
+### What Are API Tokens?
+
+An API token is a special piece of information that allows automation or other
+tools to use your Conch account without needing your actual user name or
+password.
+
+### Why Should I Use Them?
+
+Probably the best reason to use API tokens is that in the future, tokens will be
+the only way to use the shell. At some point, password authentication will go
+away. So why not get ahead of the curve?
+
+Tokens also provide a really nice way to control access to your account. For
+instance, you could create a token for each device you have. If that device is
+lost, you can revoke only that token, cutting off access for the lost device but
+not impacting any others.  
+
+Further, API tokens generally don't expire for a long time. They're designed for
+use by automation and it'd be very silly to make someone log back in manually
+every now and then on every server. Once you've got an API token, you can
+mostly put authentication out of your mind. 
+
+Also, as we'll see shortly, it's possible to use conch with no on-disk
+configuration. That option is only available when using tokens.
+
+For now, we'll stick to the basics of API tokens. A lot more documentation can
+be found over [here](tokens)
+
+*Just as a note, tokens are obfuscated inside the config file. It is not
+possible to use the value recorded there in any other tool.*
+
+### Upgrading An Existing Profile
+
+Once you've created a profile using a password, you can easily upgrade that
+profile to token auth.
+
+```
+conch profile upgrade
+```
+
+This command generates a new token specifically for your local device and
+switches the profile to use it. No further action is required on your part. 
+
+
+### Configure A New Profile
+
+If you already have a token (either from the web UI or `conch user tokens new`,
+you can create a profile from scratch using:
+
+```
+conch profile new --name <profile name> --token <token>
+```
+
+Other modifiers like `--environment` are accepted as well.
+
+### Working Without A Profile
+
+If you have a token, it is possible to use the shell without ever creating a
+profile. There are two ways to work without a profile.
+
+First, provide the token via the environment.
+
+```
+export CONCH_TOKEN='1234....'
+conch profile ls
+```
+
+Second, provide the token on the command line.
+
+```
+conch --token='1234....' profile ls
+```
+
+## Multiple Profiles
+
+It is possible to have as many profiles as you want. Developers typically have
+one for production, one for staging, and one for their local development
+environment. Each profile must have a unique name but they are created just as
+above. 
+
+You can switch between profiles by running:
+
+```
+conch profile set active <profile name>
+```
+
+or you can override the active profile by using:
+
+```
+conch -p <profile name>
+```

+ 95 - 0
docs/index.md

@@ -0,0 +1,95 @@
+# Introduction
+
+The Conch ecosystem is designed to make the deployment of new server hardware
+easier, specifically targetting equipment to be used in the Joyent
+SmartDatacenter product line. Conch has two major backend systems. First, edge
+software boots new hardware, upgrades firmware, performs burn-in testing, and
+gathers the general state of the hardware. (This software is currently closed
+source.) Second, this edge data is fed into the open source [Conch API
+server](https://github.com/joyent/conch) where the data is processed, validated,
+stored, and reported upon.
+
+The Conch Shell is a CLI designed to interact with the Conch API, allowing
+operators to prepare datacenter builds, monitor those builds, and perform
+validation actions. While Conch has a [web
+UI](https://github.com/joyent/conch-ui), the shell's intention is to allow
+operators to do their work entirely in the CLI environment. Further, the conch
+shell specifically targets scriptability, allowing operators to automate all
+aspects of the Conch API.
+
+```
+$ conch wss
+
+| ROLE  |                  ID                  | NAME        | DESCRIPTION      |
+|-------|--------------------------------------|-------------|------------------|
+| admin | 67409695-3ee3-4d45-8366-8213090b158a | GLOBAL      | Global workspace |
+| admin | 8c86ff85-1c0a-413c-a544-88e46d65a370 | conch-dev   | Conch Dev        |
+| admin | 6e5aacae-fc39-4fca-8245-b62c7b231ca1 | us-east-1   |                  |
+| admin | 8267bc59-307d-428b-a336-e381fe512aa3 | us-west-1   |                  |
+```
+
+# User Documentation
+
+* [How To Login](auth)
+  * [Deeper Dive on API Tokens, including commands](tokens)
+
+*The main focus for the Conch Shell is Joyent's production environments. While
+the shell should operate against any instance of the Conch API, some bits of the
+documentation are Joyent specific.*
+
+*Further, this site and all its documentation is targetted towards the `master`
+branch. If you need documentation for a specific release, see the `docs`
+directory in the git tag of your choice.*
+
+# Obtaining The App
+
+## Binaries
+
+Joyent provides pre-compiled binaries for various platforms via [Github
+Releases](https://github.com/joyent/conch-shell/releases). These binaries
+are built in Joyent's CI infrastructure using Docker to ensure a consistent
+build environment. If you'd like us to consider adding support for your favorite
+platform, file a Github issue.
+
+For the SmartOS/Illumos users in the crowd, the solaris binary works fine in
+those environments.
+
+Support is offered via [Github
+Issues](https://github.com/joyent/conch-shell/issues) for the current release
+only. 
+
+
+## Building The App
+
+### Requirements
+
+* [Go](https://golang.org/) - At the time of writing, you need Go 1.12 or higher.
+  See the Dockerfile for the exact version that we're using.
+* GNU Make - Our Makefile is a bit fancy and only works under GNU make
+
+### The Build
+
+* `make tools` will install the linters and infrastructure bits
+* `make` will install dependencies, run the tests, and build the binaries. The
+  new binaries will be deposited in `bin/`
+
+Always use the Makefile. The build process, via the Makefile, adds important
+information to the code base that is required for its successful operation.
+
+Several configuration options are available only during the build process and
+can be specified in the environment. See the first few lines of the Makefile.
+
+### Building A Release
+
+* You'll need [docker](https://www.docker.com/).
+* `make release` will execute our build process via Docker, depositing the
+  results in `release/`
+
+# Copyright / License
+
+Copyright Joyent Inc
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, you can obtain one at <http://mozilla.org/MPL/2.0/>
+

BIN
docs/joyent.png


+ 64 - 0
docs/tokens.md

@@ -0,0 +1,64 @@
+# API Tokens
+
+## Environment Variables
+
+* `CONCH_TOKEN` 
+  : specify the API token
+* `CONCH_ENV`
+  : `production`, `staging`, or `development` (defaults to `production`)
+* `CONCH_URL` 
+  : if `CONCH_ENV=development`, specifies the API's URL
+
+## User Commands
+
+* `profile create --name :name --token :token`
+  : create a profile using a token. user names and other parameters are ignored
+* `profile set token :token`
+  : converts a profile to token auth, using the provided token
+* `profile upgrade`
+  : converts a profile to token auth by auto-generating a token which is never
+  shared to the user
+* `profile revoke-tokens --tokens-only`
+  : when revoking one's access abilities, one can revoke only API tokens instead
+  of both API tokens and logins
+* `profile change-password --purge-tokens`
+  : when changing one's paswords, one can also purge all API tokens at the same
+  time
+* `user tokens` 
+  : list all API tokens
+* `user token create :name` 
+  : create a token with the given name, displaying the token value
+* `user token get :name` 
+  : get basic data (including last used time) about a token. Does *not* show the
+  token value
+* `user token rm :name`
+  : remove a token by name
+
+
+## Admin Commands
+* `admin user :id tokens`
+  : List a user's API tokens
+* `admin user :id token get :name`
+  : Get a user's API token by name. Does *not* show the token value
+* `admin user :id token rm :name`
+  : Remove a user's token by name
+* `admin user :id revoke --tokens-only`
+  : when revoking a user's access, an admin can revoke just their API tokens
+* `admin user :id reset --revoke-tokens`
+  : when reseting a user's passwords, an admin can also revoke their API tokens
+
+## Notes
+
+* The API token is obfuscated in the config file. It is not possible to copy
+  that value out of the config and use it in another tool.
+
+## Build / Compilation Flags
+
+* `DISABLE_API_TOKEN_CRUD`
+  : removes all commands for creating or modifying API tokens
+* `TOKEN_OBFUSCATION_KEY` 
+  : used in the obfuscation of tokens in the config file. While a default is
+  provided, it is *strongly* recommended that this be customized in the build
+  environment. *NOTE*: If this value is ever changed, it will render the tokens
+  in user configs completely unusable.
+