Package config: flags, environment variables, extra files

gokrazy will arrange for each included package to be started at boot. For example, given the following instance config.json (open in your editor using gok edit):

{
    "Hostname": "docs",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ]
}

…gokrazy will start the fbstatus, hello, serial-busybox and breakglass programs.

Package config

This article shows how you can configure different aspects of individual packages.

Each bit of configuration is nested under the PackageConfig map field in your instance’s config.json, see Instance Config Reference → PackageConfig. The map is keyed by package name (from the Packages field), and each map entry can have the following fields:

Command-line flags

The breakglass package provides emergency/debugging access to a gokrazy installation.

To enable SSH port forwardings to localhost, set the -forward flag to loopback:

{
    "PackageConfig": {
        "github.com/gokrazy/breakglass": {
            "CommandLineFlags": [
                "-forward=loopback"
            ]
        }
    },
    …
}

Environment variables

Environment variables such as the Go runtime’s GODEBUG variable can be set as follows:

{
    "PackageConfig": {
        "github.com/gokrazy/breakglass": {
            "Environment": [
                "GODEBUG=gctrace=1"
            ]
        }
    },
    …
}

Go build flags

If you want to influence the build of the package at image-creation time (as opposed to runtime), you can specify flags to be passed to the Go build invocation.

This example overwrites the value of the world variable using the -X linker flag, which is a common technique to embed version information:

{
    "PackageConfig": {
        "github.com/gokrazy/hello": {
            "GoBuildFlags": [
                "-ldflags=-X main.world=Welt"
            ]
        }
    },
    …
}

Extra files

If your program needs extra files to be present in gokrazy’s root file system image at a specific location, you can add them with the extrafiles mechanism:

{
    "PackageConfig": {
        "github.com/caddyserver/caddy/v2/cmd/caddy": {
            "ExtraFileContents": {
                "/etc/caddy/Caddyfile": "http://:80 {
	root * /tmp
	file_server browse
}
"
            }
        }
    },
    …
}

Or, if managing the file contents within the config.json becomes unwieldy, you can manage it in a separate file:

cat > ~/gokrazy/hello/Caddyfile <<'EOT'
http://:80 {
	root * /tmp
	file_server browse
}
EOT

{
    "PackageConfig": {
        "github.com/caddyserver/caddy/v2/cmd/caddy": {
            "ExtraFilePaths": {
                "/etc/caddy/Caddyfile": "Caddyfile"
            }
        }
    },
    …
}