Document Configuration (#12)

README.md

@@ -15,3 +15,24 @@ may also use this service.
 The simplest way to run the courier service is to use the docker image
 `trisa/courier:latest` and to configure it from the environment. This allows the
 courier service to be easily run on a Kubernetes cluster.
+
+### Configuration
+
+This application is configured via the environment. The following environment
+variables can be used:
+
+| KEY                                    | TYPE         | DEFAULT | DESCRIPTION                                                         |
+|----------------------------------------|--------------|---------|---------------------------------------------------------------------|
+| COURIER_MAINTENANCE                    | Boolean      | FALSE   | starts the server in maintenance mode                               |
+| COURIER_BIND_ADDR                      | String       | :8842   | ip address and port of server                                       |
+| COURIER_MODE                           | String       | release | either debug or release                                             |
+| COURIER_LOG_LEVEL                      | LevelDecoder | info    | verbosity of logging: trace, debug, info, warn, error, fatal, panic |
+| COURIER_CONSOLE_LOG                    | Boolean      | FALSE   | set for human readable logs (otherwise json logs)                   |
+| COURIER_MTLS_INSECURE                  | Boolean      | TRUE    | set to false to enable TLS configuration                            |
+| COURIER_MTLS_CERT_PATH                 | String       |         | the certificate chain and private key of the server                 |
+| COURIER_MTLS_POOL_PATH                 | String       |         | the cert pool to validate clients for mTLS                          |
+| COURIER_LOCAL_STORAGE_ENABLED          | Boolean      | FALSE   | set to true to enable local storage                                 |
+| COURIER_LOCAL_STORAGE_PATH             | String       |         | path to the directory to store certs and passwords                  |
+| COURIER_GCP_SECRET_MANAGER_ENABLED     | Boolean      | FALSE   | set to true to enable GCP secret manager                            |
+| COURIER_GCP_SECRET_MANAGER_CREDENTIALS | String       |         | path to json file with gcp service account credentials              |
+| COURIER_GCP_SECRET_MANAGER_PROJECT     | String       |         | name of gcp project to use with secret manager                      |

cmd/courier/main.go

@@ -8,9 +8,11 @@ import (
 	"io"
 	"log"
 	"os"
+	"text/tabwriter"
 	"time"
 
 	"github.com/joho/godotenv"
+	confire "github.com/rotationalio/confire/usage"
 	courier "github.com/trisacrypto/courier/pkg"
 	"github.com/trisacrypto/courier/pkg/api/v1"
 	"github.com/trisacrypto/courier/pkg/config"
@@ -44,6 +46,19 @@ func main() {
 					},
 				},
 			},
+			{
+				Name:     "config",
+				Usage:    "print courier configuration guide",
+				Category: "server",
+				Action:   usage,
+				Flags: []cli.Flag{
+					&cli.BoolFlag{
+						Name:    "list",
+						Aliases: []string{"l"},
+						Usage:   "print in list mode instead of table mode",
+					},
+				},
+			},
 			{
 				Name:     "status",
 				Usage:    "get the status of the courier server",
@@ -159,7 +174,7 @@ func main() {
 }
 
 //===========================================================================
-// CLI Actions
+// Server Actions
 //===========================================================================
 
 // Serve the courier service.
@@ -185,6 +200,25 @@ func serve(c *cli.Context) (err error) {
 	return nil
 }
 
+func usage(c *cli.Context) (err error) {
+	tabs := tabwriter.NewWriter(os.Stdout, 1, 0, 4, ' ', 0)
+	format := confire.DefaultTableFormat
+	if c.Bool("list") {
+		format = confire.DefaultListFormat
+	}
+
+	var conf config.Config
+	if err := confire.Usagef(config.Prefix, &conf, tabs, format); err != nil {
+		return cli.Exit(err, 1)
+	}
+	tabs.Flush()
+	return nil
+}
+
+//===========================================================================
+// Client Actions
+//===========================================================================
+
 // Get the status of the courier service.
 func status(c *cli.Context) (err error) {
 	var client api.CourierClient

go.mod

@@ -1,6 +1,6 @@
 module github.com/trisacrypto/courier
 
-go 1.21
+go 1.19
 
 require (
 	cloud.google.com/go/secretmanager v1.11.2

go.sum

@@ -1,7 +1,6 @@
 cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
 cloud.google.com/go v0.34.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
 cloud.google.com/go v0.110.6 h1:8uYAkj3YHTP/1iwReuHPxLSbdcyc+dSBbzFMrVwDR6Q=
-cloud.google.com/go v0.110.6/go.mod h1:+EYjdK8e5RME/VY/qLCAtuyALQ9q67dvuum8i+H5xsI=
 cloud.google.com/go/compute v1.23.0 h1:tP41Zoavr8ptEqaW6j+LQOnyBBhO7OkOMAGrgLopTwY=
 cloud.google.com/go/compute v1.23.0/go.mod h1:4tCnrn48xsqlwSAiLf1HXMQk8CONslYbdiEZc9FEIbM=
 cloud.google.com/go/compute/metadata v0.2.3 h1:mg4jlk7mCAj6xXp9UJ4fjI9VUI5rubuGBW5aJ7UnBMY=
@@ -51,7 +50,6 @@ github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm
 github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
 github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
-github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
 github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
 github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=

pkg/config/config.go

@@ -10,40 +10,42 @@ import (
 	"github.com/trisacrypto/trisa/pkg/trust"
 )
 
+const Prefix = "courier"
+
 type Config struct {
-	Maintenance      bool                `default:"false"`
-	BindAddr         string              `split_words:"true" default:":8842"`
-	Mode             string              `split_words:"true" default:"release"`
-	LogLevel         logger.LevelDecoder `split_words:"true" default:"info"`
-	ConsoleLog       bool                `split_words:"true" default:"false"`
+	Maintenance      bool                `default:"false" desc:"starts the server in maintenance mode"`
+	BindAddr         string              `split_words:"true" default:":8842" desc:"ip address and port of server"`
+	Mode             string              `split_words:"true" default:"release" desc:"either debug or release"`
+	LogLevel         logger.LevelDecoder `split_words:"true" default:"info" desc:"verbosity of logging: trace, debug, info, warn, error, fatal, panic"`
+	ConsoleLog       bool                `split_words:"true" default:"false" desc:"set for human readable logs (otherwise json logs)"`
 	MTLS             MTLSConfig          `split_words:"true"`
 	LocalStorage     LocalStorageConfig  `split_words:"true"`
 	GCPSecretManager GCPSecretsConfig    `split_words:"true"`
 	processed        bool
 }
 
 type MTLSConfig struct {
-	Insecure bool   `split_words:"true" default:"true"`
-	CertPath string `split_words:"true"`
-	PoolPath string `split_words:"true"`
+	Insecure bool   `split_words:"true" default:"true" desc:"set to false to enable TLS configuration"`
+	CertPath string `split_words:"true" desc:"the certificate chain and private key of the server"`
+	PoolPath string `split_words:"true" desc:"the cert pool to validate clients for mTLS"`
 	pool     *x509.CertPool
 	cert     tls.Certificate
 }
 
 type LocalStorageConfig struct {
-	Enabled bool   `split_words:"true" default:"false"`
-	Path    string `split_words:"true"`
+	Enabled bool   `split_words:"true" default:"false" desc:"set to true to enable local storage"`
+	Path    string `split_words:"true" desc:"path to the directory to store certs and passwords"`
 }
 
 type GCPSecretsConfig struct {
-	Enabled     bool   `split_words:"true" default:"false"`
-	Credentials string `split_words:"true"`
-	Project     string `split_words:"true"`
+	Enabled     bool   `split_words:"true" default:"false" desc:"set to true to enable GCP secret manager"`
+	Credentials string `split_words:"true" desc:"path to json file with gcp service account credentials"`
+	Project     string `split_words:"true" desc:"name of gcp project to use with secret manager"`
 }
 
 // Create a new Config struct using values from the environment prefixed with COURIER.
 func New() (conf Config, err error) {
-	if err = confire.Process("courier", &conf); err != nil {
+	if err = confire.Process(Prefix, &conf); err != nil {
 		return conf, err
 	}