Merge branch 'release/v1' into refactor

Signed-off-by: Carolyn Van Slyck <[email protected]>

CONTRIBUTING.md

@@ -290,6 +290,8 @@ example.
   * **TestIntegration** runs our integration tests, which run the bundles
     against a test KIND cluster.
 * **Install** installs porter _and_ the mixins from source into **$(HOME)/.porter/**.
+* **DocsPreview** hosts the docs site. See [Preview Documentation](#preview-documentation).
+* **DocsGen** generates the CLI documentation for the website. This is run automatically by build.
 
 [golden files]: https://ieftimov.com/post/testing-in-go-golden-files/
 
@@ -298,8 +300,6 @@ example.
 Below are the most common developer tasks. Run a target with `make TARGET`, e.g.
 `make setup-dco`.
 
-* `docs-preview` hosts the docs site. See [Preview
-  Documentation](#preview-documentation).
 * `setup-dco` installs a git commit hook that automatically signsoff your commit
   messages per the DCO requirement.
 
@@ -391,7 +391,7 @@ We use [Hugo](gohugo.io) to build our documentation site, and it is hosted on
 [Netlify](netlify.com). You don't have to install Hugo locally because the
 preview happens inside a docker container.
 
-1. Run `make docs-preview` to start serving the docs. It will watch the file
+1. Run `mage DocsPreview` to start serving the docs. It will watch the file
 system for changes.
 1. Our make rule should open <http://localhost:1313/docs> to preview the
 site/docs.

Makefile

@@ -10,7 +10,6 @@ CLIENT_ARCH = $(shell go env GOARCH)
 CLIENT_GOPATH = $(shell go env GOPATH)
 RUNTIME_PLATFORM = linux
 RUNTIME_ARCH = amd64
-BASEURL_FLAG ?=
 PORTER_UPDATE_TEST_FILES ?=
 
 GO = go
@@ -50,17 +49,7 @@ test-smoke:
 
 .PHONY: docs
 docs:
-	hugo --source docs/ $(BASEURL_FLAG)
-
-docs-preview: docs-stop-preview
-	@docker run -d -v $$PWD:/src -p 1313:1313 --name porter-docs -w /src/docs \
-	klakegg/hugo:0.78.1-ext-alpine server -D -F --noHTTPCache --watch --bind=0.0.0.0
-	# Wait for the documentation web server to finish rendering
-	@until docker logs porter-docs | grep -m 1  "Web Server is available"; do : ; done
-	@open "http://localhost:1313/docs/"
-
-docs-stop-preview:
-	@docker rm -f porter-docs &> /dev/null || true
+	go run mage.go -v docs
 
 publish: publish-bin publish-mixins publish-images
 

docs/content/author-bundles.md

@@ -15,6 +15,7 @@ The manifest is made up of multiple components:
 * [Outputs](#outputs)
 * [Parameter and Output Schema](#parameter-and-output-schema)
 * [Credentials](#credentials)
+* [State](#state)
 * [Bundle Actions](#bundle-actions)
 * [Dependencies](#dependencies)
 * [Images](#images)
@@ -319,6 +320,33 @@ credentials:
 * [How Credentials Work](/how-credentials-work/)
 * [Wiring Credentials](/wiring/)
 
+## State
+
+Porter provides a state bag that allows you to persist state associated with the bundle.
+If the specified file is present when the bundle completes, Porter saves the
+file and then injects that file back into the bundle when it is run again.
+
+For example, when the terraform mixin is run by default it saves its state to two files:
+terraform/terraform.tfstate and terraform/terraform.tfvars.json. While you may configure
+a remote Terraform backend, you can also take advantage of Porter's state bag to persist
+these files. This simplifies the setup and infrastructure required of the end-user when
+they run your bundle.
+
+```yaml
+state:
+  - name: tfstate
+    path: terraform/terraform.tfstate
+  - name: tfvars
+    path: terraform/terraform.tfvars.json
+```
+
+| Field       | Usage    | Description |
+| ----------  | -------- | ----------- |
+| name        | Required | The name of the state variable. |
+| path        | Required | The path of the file containing the state value. Relative paths are assumed to be relative to the bundle directory (/cnab/app). |
+| description | Optional | A description of the variable and how it is used in the bundle. |
+| mixin       | Optional<br/>Reserved for future use | The name of the mixin that manages this state variable. |
+
 ## Bundle Actions
 
 Porter and its mixins supports the three CNAB actions: install, upgrade, and

mage/tests/kind.go

@@ -211,7 +211,7 @@ func StartDockerRegistry() error {
 		return nil
 	}
 
-	err := removeContainer(getRegistryName())
+	err := RemoveContainer(getRegistryName())
 	if err != nil {
 		return err
 	}
@@ -224,13 +224,13 @@ func StartDockerRegistry() error {
 func StopDockerRegistry() error {
 	if containerExists(getRegistryName()) {
 		fmt.Println("Stopping local docker registry")
-		return removeContainer(getRegistryName())
+		return RemoveContainer(getRegistryName())
 	}
 	return nil
 }
 
 func RestartDockerRegistry() error {
-	if err := StopDockerRegistry(); err!=nil{
+	if err := StopDockerRegistry(); err != nil {
 		return err
 	}
 	return StartDockerRegistry()
@@ -247,7 +247,8 @@ func containerExists(name string) bool {
 	return err == nil
 }
 
-func removeContainer(name string) error {
+// Remove the specified container, if it is present.
+func RemoveContainer(name string) error {
 	stderr := bytes.Buffer{}
 	_, _, err := shx.Command("docker", "rm", "-f", name).Stderr(&stderr).Stdout(nil).Exec()
 	// Gracefully handle the container already being gone

magefile.go

@@ -14,6 +14,7 @@ import (
 	"runtime"
 	"strconv"
 	"strings"
+	"time"
 
 	// mage:import
 	"get.porter.sh/porter/mage/tests"
@@ -36,7 +37,7 @@ import (
 // var Default = Build
 
 const (
-	PKG = "get.porter.sh/porter"
+	PKG       = "get.porter.sh/porter"
 	GoVersion = ">=1.16"
 	mixinsURL = "https://cdn.porter.sh/mixins/"
 )
@@ -435,3 +436,35 @@ func getPorterHome() string {
 	}
 	return porterHome
 }
+
+// Generate Porter's static website
+func Docs() {
+	cmd := must.Command("hugo", "--source", "docs/")
+	baseURL := os.Getenv("BASEURL")
+	if baseURL != "" {
+		cmd.Args("-b", baseURL)
+	}
+	cmd.RunV()
+}
+
+// Preview the website documentation
+func DocsPreview() {
+	const container = "porter-docs"
+	tests.RemoveContainer(container)
+
+	pwd, _ := os.Getwd()
+	must.Run("docker", "run", "-d", "-v", pwd+":/src",
+		"-p", "1313:1313", "--name", "porter-docs", "-w", "/src/docs",
+		"klakegg/hugo:0.78.1-ext-alpine", "server", "-D", "-F", "--noHTTPCache",
+		"--watch", "--bind=0.0.0.0")
+
+	for {
+		output, _ := must.OutputS("docker", "logs", "porter-docs")
+		if strings.Contains(output, "Web Server is available") {
+			break
+		}
+		time.Sleep(time.Second)
+	}
+
+	must.Run("open", "http://localhost:1313/docs/")
+}

netlify.toml

@@ -9,7 +9,7 @@
   HUGO_VERSION = "0.78.1"
 
 [context.branch-deploy]
-  command = "make docs BASEURL_FLAG=\"-b $DEPLOY_PRIME_URL\"/"
+  command = "make docs BASEURL=$DEPLOY_PRIME_URL/"
 
 [context.deploy-preview]
-  command = "make docs BASEURL_FLAG=\"-b $DEPLOY_PRIME_URL\"/"
+  command = "make docs BASEURL=$DEPLOY_PRIME_URL/"