Configuration settings

The available configuration settings for your application – and how to work with them – will vary depending on the options you select when generating the codebase.

However, at minimum, all applications will include configurations settings for the port that the application should listen on for HTTP requests, and the base URL for the application.

Important: You can change the default values for all configuration settings by editing the values in the run() function in cmd/web/main.go.

1. Configuration with command-line flags
2. Configuration with environment variables

Configuration with command-line flags

When using command-line flags, configuration settings are provided when you run the application, like so:

$ go run ./cmd/web --http-port=9999 --base-url="http://example.com"

Command-line flags are defined and parsed at the start of the run() function in the cmd/web/main.go file, using the standard library flag package. The values are then stored in a config struct for later use.

The generated code will vary depending on the features you select, but in general the cmd/web/main.go file looks similar to this:

type config struct {
	baseURL  string
	httpPort int
    // etc...
}

...

func run(logger *slog.Logger) error {
	var cfg config

    flag.StringVar(&cfg.baseURL, "base-url", "http://localhost:6633", "base URL for the application")
    flag.IntVar(&cfg.httpPort, "http-port", 6633, "port to listen on for HTTP requests")
    // etc...
}

Feel free to adapt the run() function and config struct to define additional command-line flags and store their values as needed.

The configuration values can then be accessed in your handlers, helpers, and middleware via app.config. For example:

func (app *application) exampleHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "The base URL is: %s", app.config.baseURL)
}

You can also use the --help flag when running your application to view all available flags along with their default values:

$ go run ./cmd/web --help

Configuration with environment variables

When using environment variables, configuration settings are read on application startup. Specifically, the values are read at the start of the run() function in the cmd/web/main.go file and stored in a config struct for later use.

The generated code will vary depending on the features you select, but in general the cmd/web/main.go file looks similar to this:

type config struct {
	baseURL  string
	httpPort int
    // etc...
}

...

func run(logger *slog.Logger) error {
	var cfg config

	cfg.baseURL = env.GetString("BASE_URL", "http://localhost:6633")
	cfg.httpPort = env.GetInt("HTTP_PORT", 6633)
    // etc...
}

Feel free to adapt the run() function and config struct to read additional environment variables and store their values as needed.

The internal/env package contains three helper functions for reading environment variables: env.GetString(), env.GetInt() and env.GetBool(). They return the value of an environment variable or a fallback if it is not set. For example, env.GetInt("HTTP_PORT", 6633) returns 6633 if no HTTP_PORT environment variable is present.

The env.GetInt() helper will panic if the environment variable is present but contains a non-integer value.

The env.GetBool() helper will return true if the environment variable contains the values 1, t, or true, and false for 0, f, or false (case-insensitive). Like env.GetInt(), it will panic if the environment variable is present but cannot be parsed as a boolean.

You should also feel free to add additional helper functions in internal/env or tweak their behavior as needed.

The configuration values can then be accessed in your handlers, helpers, and middleware via app.config. For example:

func (app *application) exampleHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "The base URL is: %s", app.config.baseURL)
}