Package config: flags, environment variables, extra files :: gokrazy

Edit this page

# 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:

- `CommandLineFlags` for Command-line flags
- `Environment` for Environment variables
- `GoBuildFlags` for Go build flags
- `ExtraFilePaths` or `ExtraFileContents` for Extra files

## 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"
                }
            }
        },
        …
    }