docs: refresh documentation and add a troubleshooting page (#410)

* chore: fix variable commands so docs are correct * docs: update configuration docs * docs: add troubleshooting docs * chore: add make docs/serve for local docs viewing
uselagoon · Dec 9, 2024 · a786312 · a786312
1 parent 7829bdf
commit a786312
Show file tree

Hide file tree

Showing 14 changed files with 325 additions and 145 deletions.
diff --git a/Makefile b/Makefile
@@ -98,3 +98,16 @@ install-linux:
 install-darwin:
 	cp builds/lagoon-cli-${VERSION}-darwin-amd64 ${ARTIFACT_DESTINATION}/lagoon
 
+# Settings for the MKDocs serving
+MKDOCS_IMAGE ?= ghcr.io/amazeeio/mkdocs-material
+MKDOCS_SERVE_PORT ?= 8000
+
+.PHONY: docs/serve
+docs/serve:
+	@echo "Starting container to serve documentation"
+	@docker pull $(MKDOCS_IMAGE)
+	@docker run --rm -it \
+		-p 127.0.0.1:$(MKDOCS_SERVE_PORT):$(MKDOCS_SERVE_PORT) \
+		-v ${PWD}:/docs \
+		--entrypoint sh $(MKDOCS_IMAGE) \
+		-c 'mkdocs serve -s --dev-addr=0.0.0.0:$(MKDOCS_SERVE_PORT) -f mkdocs.yml'
diff --git a/cmd/config.go b/cmd/config.go
@@ -354,10 +354,10 @@ func readLagoonConfig(lc *lagoon.Config, file string) error {
 		// configuration to point to the amazeeio lagoon instance
 		if yesNo(fmt.Sprintf("Config file '%s' does not exist, do you want to create it with defaults?", file)) {
 			l := lagoon.Context{
-				GraphQL:  "https://api.lagoon.amazeeio.cloud/graphql",
-				HostName: "ssh.lagoon.amazeeio.cloud",
+				GraphQL:  "https://api.amazeeio.cloud/graphql",
+				HostName: "token.amazeeio.cloud",
 				Token:    "",
-				Port:     "32222",
+				Port:     "22",
 				UI:       "https://dashboard.amazeeio.cloud",
 				Kibana:   "https://logs.amazeeio.cloud/",
 			}

diff --git a/cmd/config_test.go b/cmd/config_test.go
@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"fmt"
 	"reflect"
 	"testing"
 
@@ -23,11 +24,11 @@ func TestConfigRead(t *testing.T) {
 				Default: "amazeeio",
 				Lagoons: map[string]lagoon.Context{
 					"amazeeio": {
-						GraphQL:  "https://api.lagoon.amazeeio.cloud/graphql",
-						HostName: "ssh.lagoon.amazeeio.cloud",
-						Kibana:   "https://logs-db-ui-lagoon-master.ch.amazee.io/",
-						UI:       "https://ui-lagoon-master.ch.amazee.io",
-						Port:     "32222",
+						GraphQL:  "https://api.amazeeio.cloud/graphql",
+						HostName: "token.amazeeio.cloud",
+						Kibana:   "https://logs.amazeeio.cloud/",
+						UI:       "https://dashboard.amazeeio.cloud",
+						Port:     "22",
 					},
 				},
 				UpdateCheckDisable:       false,
@@ -49,8 +50,8 @@ func TestConfigRead(t *testing.T) {
 				Default: "amazeeio",
 				Lagoons: map[string]lagoon.Context{
 					"amazeeio": {
-						Kibana: "https://logs-db-ui-lagoon-master.ch.amazee.io/",
-						UI:     "https://ui-lagoon-master.ch.amazee.io",
+						Kibana: "https://logs.amazeeio.cloud/",
+						UI:     "https://dashboard.amazeeio.cloud",
 					},
 				},
 				UpdateCheckDisable:       false,
@@ -66,6 +67,7 @@ func TestConfigRead(t *testing.T) {
 					tt.Fatal(err)
 				}
 			}
+			fmt.Println(lc, tc.expect)
 			if !reflect.DeepEqual(lc, tc.expect) {
 				tt.Fatalf("Read config does not match expected config")
 			}

diff --git a/cmd/testdata/lagoon.yml b/cmd/testdata/lagoon.yml
@@ -2,10 +2,10 @@ current: amazeeio
 default: amazeeio
 lagoons:
   amazeeio:
-    graphql: https://api.lagoon.amazeeio.cloud/graphql
-    hostname: ssh.lagoon.amazeeio.cloud
-    kibana: https://logs-db-ui-lagoon-master.ch.amazee.io/
-    port: 32222
-    ui: https://ui-lagoon-master.ch.amazee.io
+    graphql: https://api.amazeeio.cloud/graphql
+    hostname: token.amazeeio.cloud
+    kibana: https://logs.amazeeio.cloud/
+    port: 22
+    ui: https://dashboard.amazeeio.cloud
 updatecheckdisable: false
 environmentfromdirectory: false
diff --git a/cmd/testdata/lagoon.yml.invalid b/cmd/testdata/lagoon.yml.invalid
@@ -2,8 +2,8 @@ current: amazeeio
 default: amazeeio
 lagoons:
   amazeeio:
-    graphql: https://api.lagoon.amazeeio.cloud/graphql
-        hostname: ssh.lagoon.amazeeio.cloud
-    kibana: https://logs-db-ui-lagoon-master.ch.amazee.io/
-    port: 32222
-    ui: https://ui-lagoon-master.ch.amazee.io
+    graphql: https://api.amazeeio.cloud/graphql
+        hostname: token.amazeeio.cloud
+    kibana: https://logs.amazeeio.cloud/
+    port: 22
+    ui: https://dashboard.amazeeio.cloud
diff --git a/cmd/testdata/lagoon.yml.missing b/cmd/testdata/lagoon.yml.missing
@@ -2,5 +2,5 @@ current: amazeeio
 default: amazeeio
 lagoons:
   amazeeio:
-    kibana: https://logs-db-ui-lagoon-master.ch.amazee.io/
-    ui: https://ui-lagoon-master.ch.amazee.io
+    kibana: https://logs.amazeeio.cloud/
+    ui: https://dashboard.amazeeio.cloud
diff --git a/cmd/update.go b/cmd/update.go
@@ -30,4 +30,5 @@ func init() {
 	updateCmd.AddCommand(updateDeployTargetConfigCmd)
 	updateCmd.AddCommand(updateDeployTargetCmd)
 	updateCmd.AddCommand(updateOrganizationCmd)
+	updateCmd.AddCommand(updateVariableCmd)
 }
diff --git a/cmd/variables.go b/cmd/variables.go
@@ -20,81 +20,93 @@ var addVariableCmd = &cobra.Command{
 	PreRunE: func(_ *cobra.Command, _ []string) error {
 		return validateTokenE(cmdLagoon)
 	},
-	RunE: func(cmd *cobra.Command, args []string) error {
-		debug, err := cmd.Flags().GetBool("debug")
-		if err != nil {
-			return err
-		}
-		varName, err := cmd.Flags().GetString("name")
-		if err != nil {
-			return err
-		}
-		varValue, err := cmd.Flags().GetString("value")
-		if err != nil {
-			return err
-		}
-		varScope, err := cmd.Flags().GetString("scope")
-		if err != nil {
-			return err
-		}
-		if err := requiredInputCheck("Project name", cmdProjectName, "Variable name", varName); err != nil {
-			return err
-		}
+	RunE: addOrUpdateVariable,
+}
 
-		current := lagoonCLIConfig.Current
-		token := lagoonCLIConfig.Lagoons[current].Token
-		lc := lclient.New(
-			lagoonCLIConfig.Lagoons[current].GraphQL,
-			lagoonCLIVersion,
-			lagoonCLIConfig.Lagoons[current].Version,
-			&token,
-			debug)
+var updateVariableCmd = &cobra.Command{
+	Use:     "variable",
+	Aliases: []string{"v"},
+	Short:   "Add or update a variable to an environment or project",
+	PreRunE: func(_ *cobra.Command, _ []string) error {
+		return validateTokenE(cmdLagoon)
+	},
+	RunE: addOrUpdateVariable,
+}
+
+func addOrUpdateVariable(cmd *cobra.Command, args []string) error {
+	debug, err := cmd.Flags().GetBool("debug")
+	if err != nil {
+		return err
+	}
+	varName, err := cmd.Flags().GetString("name")
+	if err != nil {
+		return err
+	}
+	varValue, err := cmd.Flags().GetString("value")
+	if err != nil {
+		return err
+	}
+	varScope, err := cmd.Flags().GetString("scope")
+	if err != nil {
+		return err
+	}
+	if err := requiredInputCheck("Project name", cmdProjectName, "Variable name", varName); err != nil {
+		return err
+	}
+
+	current := lagoonCLIConfig.Current
+	token := lagoonCLIConfig.Lagoons[current].Token
+	lc := lclient.New(
+		lagoonCLIConfig.Lagoons[current].GraphQL,
+		lagoonCLIVersion,
+		lagoonCLIConfig.Lagoons[current].Version,
+		&token,
+		debug)
 
-		in := &schema.EnvVariableByNameInput{
-			Project:     cmdProjectName,
-			Environment: cmdProjectEnvironment,
-			Scope:       schema.EnvVariableScope(strings.ToUpper(varScope)),
-			Name:        varName,
-			Value:       varValue,
+	in := &schema.EnvVariableByNameInput{
+		Project:     cmdProjectName,
+		Environment: cmdProjectEnvironment,
+		Scope:       schema.EnvVariableScope(strings.ToUpper(varScope)),
+		Name:        varName,
+		Value:       varValue,
+	}
+	envvar, err := lagoon.AddOrUpdateEnvVariableByName(context.TODO(), in, lc)
+	if err != nil {
+		return err
+	}
+
+	if envvar.ID != 0 {
+		data := []output.Data{}
+		env := []string{
+			returnNonEmptyString(fmt.Sprintf("%v", envvar.ID)),
+			returnNonEmptyString(fmt.Sprintf("%v", cmdProjectName)),
 		}
-		envvar, err := lagoon.AddOrUpdateEnvVariableByName(context.TODO(), in, lc)
-		if err != nil {
-			return err
+		if cmdProjectEnvironment != "" {
+			env = append(env, returnNonEmptyString(fmt.Sprintf("%v", cmdProjectEnvironment)))
 		}
-
-		if envvar.ID != 0 {
-			data := []output.Data{}
-			env := []string{
-				returnNonEmptyString(fmt.Sprintf("%v", envvar.ID)),
-				returnNonEmptyString(fmt.Sprintf("%v", cmdProjectName)),
-			}
-			if cmdProjectEnvironment != "" {
-				env = append(env, returnNonEmptyString(fmt.Sprintf("%v", cmdProjectEnvironment)))
-			}
-			env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Scope)))
-			env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Name)))
-			env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Value)))
-			data = append(data, env)
-			header := []string{
-				"ID",
-				"Project",
-			}
-			if cmdProjectEnvironment != "" {
-				header = append(header, "Environment")
-			}
-			header = append(header, "Scope")
-			header = append(header, "Name")
-			header = append(header, "Value")
-			r := output.RenderOutput(output.Table{
-				Header: header,
-				Data:   data,
-			}, outputOptions)
-			fmt.Fprintf(cmd.OutOrStdout(), "%s", r)
-		} else {
-			return handleNilResults("Variable '%s' remained unchanged\n", cmd, varName)
+		env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Scope)))
+		env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Name)))
+		env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Value)))
+		data = append(data, env)
+		header := []string{
+			"ID",
+			"Project",
 		}
-		return nil
-	},
+		if cmdProjectEnvironment != "" {
+			header = append(header, "Environment")
+		}
+		header = append(header, "Scope")
+		header = append(header, "Name")
+		header = append(header, "Value")
+		r := output.RenderOutput(output.Table{
+			Header: header,
+			Data:   data,
+		}, outputOptions)
+		fmt.Fprintf(cmd.OutOrStdout(), "%s", r)
+	} else {
+		return handleNilResults("Variable '%s' remained unchanged\n", cmd, varName)
+	}
+	return nil
 }
 
 var deleteVariableCmd = &cobra.Command{
@@ -150,10 +162,7 @@ var deleteVariableCmd = &cobra.Command{
 	},
 }
 
-var updateVariableCmd = addVariableCmd
-
 func init() {
-	updateCmd.AddCommand(updateVariableCmd)
 	addVariableCmd.Flags().StringP("name", "N", "", "Name of the variable to add")
 	addVariableCmd.Flags().StringP("value", "V", "", "Value of the variable to add")
 	addVariableCmd.Flags().StringP("scope", "S", "", "Scope of the variable[global, build, runtime, container_registry, internal_container_registry]")

diff --git a/docs/commands/lagoon_add_variable.md b/docs/commands/lagoon_add_variable.md
@@ -0,0 +1,42 @@
+## lagoon add variable
+
+Add or update a variable to an environment or project
+
+```
+lagoon add variable [flags]
+```
+
+### Options
+
+```
+  -h, --help           help for variable
+  -N, --name string    Name of the variable to add
+  -S, --scope string   Scope of the variable[global, build, runtime, container_registry, internal_container_registry]
+  -V, --value string   Value of the variable to add
+```
+
+### Options inherited from parent commands
+
+```
+      --config-file string                Path to the config file to use (must be *.yml or *.yaml)
+      --debug                             Enable debugging output (if supported)
+  -e, --environment string                Specify an environment to use
+      --force                             Force yes on prompts (if supported)
+  -l, --lagoon string                     The Lagoon instance to interact with
+      --no-header                         No header on table (if supported)
+      --output-csv                        Output as CSV (if supported)
+      --output-json                       Output as JSON (if supported)
+      --pretty                            Make JSON pretty (if supported)
+  -p, --project string                    Specify a project to use
+      --skip-update-check                 Skip checking for updates
+  -i, --ssh-key string                    Specify path to a specific SSH key to use for lagoon authentication
+      --ssh-publickey string              Specify path to a specific SSH public key to use for lagoon authentication using ssh-agent.
+                                          This will override any public key identities defined in configuration
+      --strict-host-key-checking string   Similar to SSH StrictHostKeyChecking (accept-new, no, ignore) (default "accept-new")
+  -v, --verbose                           Enable verbose output to stderr (if supported)
+```
+
+### SEE ALSO
+
+* [lagoon add](lagoon_add.md)	 - Add a project, or add notifications and variables to projects or environments
+
diff --git a/docs/commands/lagoon_update_variable.md b/docs/commands/lagoon_update_variable.md
@@ -9,10 +9,7 @@ lagoon update variable [flags]
 ### Options
 
 ```
-  -h, --help           help for variable
-  -N, --name string    Name of the variable to add
-  -S, --scope string   Scope of the variable[global, build, runtime, container_registry, internal_container_registry]
-  -V, --value string   Value of the variable to add
+  -h, --help   help for variable
 ```
 
 ### Options inherited from parent commands