gokrazy

https://gokrazy.org
Admin
gokrazy is a framework for deploying Go programs as minimal appliances to Raspberry Pi, virtual...
Tokens:28,644
Snippets:363
Trust Score:8.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Define instance packages in config.json

Source: https://gokrazy.org/userguide/package-config/index.html

The Packages field lists the Go packages to be started at boot.

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

--------------------------------

### Packages List Configuration Example

Source: https://gokrazy.org/userguide/instance-config/index.html

Defines the list of Go packages to be built and included in the instance image.

```json
{
    "Hostname": "hello",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "github.com/stapelberg/scan2drive/cmd/scan2drive"
    ]
}
```

--------------------------------

### Add QEMU guest agent

Source: https://gokrazy.org/userguide/qemu/index.html

Installs the guest agent package to the gokrazy instance.

```bash
gok -i virtual add github.com/bradfitz/qemu-guest-kragent
```

--------------------------------

### Configure the gokrazy instance

Source: https://gokrazy.org/userguide/qemu/index.html

Example JSON configuration for a virtual machine instance.

```json
{
  "Hostname": "virtual",
  "KernelPackage": "github.com/rtr7/kernel",
  "FirmwarePackage": "github.com/rtr7/kernel",
  "SerialConsole": "ttyS0,115200",
  // ...
}
```

--------------------------------

### Install gok CLI

Source: https://gokrazy.org/quickstart/index.html

Install the gokrazy command line tool (CLI) using the Go toolchain. Ensure you have a working Go installation before running this command.

```bash
go install github.com/gokrazy/tools/cmd/gok@main
```

--------------------------------

### Install Prometheus Server

Source: https://gokrazy.org/packages/prometheus/index.html

Adds the Prometheus server package to the gokrazy instance.

```bash
gok add github.com/prometheus/prometheus/cmd/prometheus
```

--------------------------------

### Install the wifi package

Source: https://gokrazy.org/userguide/wifi/index.html

Add the wifi package to your gokrazy instance using the gok command-line tool.

```bash
gok add github.com/gokrazy/wifi
```

--------------------------------

### Example gokrazy Configuration

Source: https://gokrazy.org/packages/prometheus/index.html

A sample configuration file showing how to include Prometheus with command-line flags and extra file paths.

```json
{
    "Hostname": "hello",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "github.com/prometheus/prometheus"
    ],
    "PackageConfig": {
        "github.com/prometheus/prometheus": {
            "CommandLineFlags": [
                "--config.file=/etc/prometheus/prometheus.yml"
            ],
            "WaitForClock": true,
            "ExtraFilePaths": {
                "/etc/prometheus/prometheus.yml": "prometheus.yml"
            }
        }
    }
}
```

--------------------------------

### DeviceType Configuration Example

Source: https://gokrazy.org/userguide/instance-config/index.html

Specifies the target hardware architecture for the gokrazy instance.

```json
{
    "Hostname": "alternative",
    "DeviceType": "odroidhc1",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ]
}
```

--------------------------------

### Verify Podman Installation with a Debian Container

Source: https://gokrazy.org/packages/docker-containers/index.html

Log in to your gokrazy instance using breakglass and run a Debian container to verify Podman is working correctly. This example checks the Debian version inside the container.

```bash
/tmp/breakglass187145741 $ podman run --rm -ti docker.io/library/debian:sid
root@gokrazy:/# cat /etc/debian_version
12.0
```

--------------------------------

### Hostname Configuration Example

Source: https://gokrazy.org/userguide/instance-config/index.html

Sets the instance hostname, which is used for network identification and browser access.

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

--------------------------------

### Create a test bucket with MinIO client

Source: https://gokrazy.org/packages/minio/index.html

Use the `mc` command to create a new bucket named `testbucket` on your gokrazy MinIO instance to verify the setup.

```bash
$ mc mb gokrazy/testbucket
```

--------------------------------

### Add Tailscale packages to gokrazy

Source: https://gokrazy.org/packages/tailscale/index.html

Install the necessary Tailscale daemon, CLI, and filesystem initialization packages.

```bash
gok add tailscale.com/cmd/tailscaled
gok add tailscale.com/cmd/tailscale
# Automatically initialize a file system on the /perm partition on first boot:
gok add github.com/gokrazy/mkfs
```

--------------------------------

### Package C binary with dependencies using freeze

Source: https://gokrazy.org/development/non-go/index.html

Use a Debian container to install the target binary and its dependencies, then use the freeze tool to bundle them for gokrazy.

```bash
% docker run -t -i debian:trixie
root@6e530a973d45:/# dpkg --add-architecture arm64
root@6e530a973d45:/# apt update
root@6e530a973d45:/# apt install iproute2:arm64 qemu-user-static golang-go ca-certificates
root@6e530a973d45:/# go install github.com/gokrazy/freeze/cmd/...@latest
root@6e530a973d45:/# ~/go/bin/freeze -wrap=qemu-aarch64-static $(which tc)
2022/03/20 11:45:46 /sbin/tc
2022/03/20 11:45:46 Copying tc together with its 12 ELF shared library dependencies
2022/03/20 11:45:46 [cp /sbin/tc /tmp/freeze2237965672/tc]
2022/03/20 11:45:46 [cp /usr/lib/aarch64-linux-gnu/libbpf.so.0.7.0 /tmp/freeze2237965672/libbpf.so.0]
2022/03/20 11:45:46 [cp /usr/lib/aarch64-linux-gnu/libelf-0.186.so /tmp/freeze2237965672/libelf.so.1]
2022/03/20 11:45:46 [cp /usr/lib/aarch64-linux-gnu/libmnl.so.0.2.0 /tmp/freeze2237965672/libmnl.so.0]
2022/03/20 11:45:46 [cp /usr/lib/aarch64-linux-gnu/libbsd.so.0.11.5 /tmp/freeze2237965672/libbsd.so.0]
2022/03/20 11:45:46 [cp /lib/aarch64-linux-gnu/libcap.so.2.44 /tmp/freeze2237965672/libcap.so.2]
2022/03/20 11:45:46 [cp /lib/aarch64-linux-gnu/libm-2.33.so /tmp/freeze2237965672/libm.so.6]
2022/03/20 11:45:46 [cp /lib/aarch64-linux-gnu/libdl-2.33.so /tmp/freeze2237965672/libdl.so.2]
2022/03/20 11:45:46 [cp /usr/lib/aarch64-linux-gnu/libxtables.so.12.4.0 /tmp/freeze2237965672/libxtables.so.12]
2022/03/20 11:45:46 [cp /lib/aarch64-linux-gnu/libc-2.33.so /tmp/freeze2237965672/libc.so.6]
2022/03/20 11:45:46 [cp /lib/aarch64-linux-gnu/ld-2.33.so /tmp/freeze2237965672/ld-linux-aarch64.so.1]
2022/03/20 11:45:46 [cp /lib/aarch64-linux-gnu/libz.so.1.2.11 /tmp/freeze2237965672/libz.so.1]
2022/03/20 11:45:46 [cp /usr/lib/aarch64-linux-gnu/libmd.so.0.0.5 /tmp/freeze2237965672/libmd.so.0]
2022/03/20 11:45:46 [tar cf /tmp/freeze2237965672.tar freeze2237965672]
2022/03/20 11:45:46 Download freeze2237965672.tar to your gokrazy device and run:
	LD_LIBRARY_PATH=$PWD ./ld-linux-aarch64.so.1 ./tc
root@6e530a973d45:/# exit
% mkdir /tmp/freeze
% cd /tmp/freeze
% docker cp 6e530a973d45:/tmp/freeze2237965672.tar .
% caddy file-server -listen=:4080
```

--------------------------------

### Prevent Automatic Startup of a Package

Source: https://gokrazy.org/userguide/instance-config/index.html

Set DontStart to true to prevent the gokrazy init system from starting a program automatically. The program can still be started manually.

```json
{
    "Hostname": "ts",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "tailscale.com/cmd/tailscaled",
        "tailscale.com/cmd/tailscale"
    ],
    "PackageConfig": {
        "tailscale.com/cmd/tailscale": {
            "DontStart": true
        }
    }
}
```

--------------------------------

### Wait for Clock Synchronization Before Starting a Package

Source: https://gokrazy.org/userguide/instance-config/index.html

Use WaitForClock to ensure the system's clock is synchronized before a program starts. This is useful when direct calls to gokrazy.WaitForClock() are inconvenient.

```json
{
    "Hostname": "scanner",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "github.com/stapelberg/scan2drive/cmd/scan2drive"
    ],
    "PackageConfig": {
        "github.com/stapelberg/scan2drive/cmd/scan2drive": {
            "WaitForClock": true
        }
    }
}
```

--------------------------------

### Install rsync-prom Tool

Source: https://gokrazy.org/userguide/rsync-backups/index.html

Installs the rsync-prom tool, which is used to monitor rsync transfers with Prometheus. This is a prerequisite for setting up the automated cron job.

```bash
go install github.com/stapelberg/rsyncprom/cmd/rsync-prom@latest
```

--------------------------------

### Install Dependencies and Freeze tc Binary

Source: https://gokrazy.org/prototyping

Run these commands within a Debian Docker container to install necessary packages, the `freeze` tool, and then package the `tc` binary along with its ELF shared library dependencies.

```bash
docker run -t -i debian:trixie
root@6e530a973d45:/# dpkg --add-architecture arm64
root@6e530a973d45:/# apt update
root@6e530a973d45:/# apt install iproute2:arm64 qemu-user-static golang-go ca-certificates
root@6e530a973d45:/# go install github.com/gokrazy/freeze/cmd/...@latest
root@6e530a973d45:/# ~/go/bin/freeze -wrap=qemu-aarch64-static $(which tc)
```

--------------------------------

### Configure Bootloader Extra Lines (config.txt)

Source: https://gokrazy.org/userguide/instance-config/index.html

Add custom lines to the Raspberry Pi's config.txt file. Example enables 1-Wire support.

```json
{
    "Hostname": "hello",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ],
    "BootloaderExtraLines": [
	    "dtoverlay=w1-gpio"
	]
}
```

--------------------------------

### Create Caddyfile for Caddy server

Source: https://gokrazy.org/packages/caddy-http-server/index.html

Create and populate the Caddyfile to configure Caddy's webserver. This example sets up an HTTP listener on port 80, serves files from /tmp, and enables directory browsing. It explicitly disables automatic HTTPS.

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

--------------------------------

### Add Bluetooth package to gokrazy

Source: https://gokrazy.org/userguide/bluetooth/index.html

Install the necessary kernel modules and firmware by adding the bluetooth package to your instance.

```bash
gok add github.com/gokrazy/bluetooth
```

--------------------------------

### Install Prometheus Node Exporter

Source: https://gokrazy.org/packages/prometheus/index.html

Adds the node exporter package to the gokrazy instance.

```bash
gok add github.com/prometheus/node_exporter
```

--------------------------------

### Configure Environment for amd64 PC

Source: https://gokrazy.org/userguide/instance-config/index.html

Set the Environment field to specify the target operating system and architecture. This example configures a gokrazy instance for linux/amd64.

```json
{
    "Hostname": "vm",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ],
    "Environment": [
        "GOOS=linux",
        "GOARCH=amd64"
    ],
    "KernelPackage": "github.com/gokrazy/kernel.amd64",
    "FirmwarePackage": "github.com/gokrazy/kernel.amd64"
}
```

--------------------------------

### Old gokr-packer command

Source: https://gokrazy.org/userguide/migration-guide/index.html

Example of a gokr-packer command used before the introduction of instance configuration.

```bash
gokr-packer \
  -hostname=scanner \
  -update=yes \
  github.com/gokrazy/hello \
  github.com/gokrazy/breakglass \
  github.com/gokrazy/serial-busybox \
  github.com/stapelberg/scan2drive/cmd/scan2drive
```

--------------------------------

### Add gokrazy rsync Daemon

Source: https://gokrazy.org/userguide/rsync-backups/index.html

Installs the gokrazy rsync implementation to your gokrazy instance. Ensure you are in the correct directory.

```bash
gok add github.com/gokrazy/rsync/cmd/gokr-rsync
```

--------------------------------

### Run gokrazy/mkfs once with gok run

Source: https://gokrazy.org/userguide/permanent-data/index.html

Execute the `gokrazy/mkfs` program once without permanently including it in your installation by using `gok run` after cloning the repository.

```bash
git clone https://github.com/gokrazy/mkfs
cd mkfs
gok -i bakery run
```

--------------------------------

### Example gokrazy build directory structure

Source: https://gokrazy.org/development/modules/index.html

After building an instance, gokrazy creates a hierarchical build directory structure. Each subdirectory typically contains a `go.mod` file for its Go module, ensuring isolation between packages.

```bash
cd ~/gokrazy/scanner
find . -name go.mod
./builddir/init/go.mod
./builddir/github.com/stapelberg/scan2drive/cmd/scan2drive/go.mod
./builddir/github.com/gokrazy/serial-busybox/go.mod
./builddir/github.com/gokrazy/hello/go.mod
./builddir/github.com/gokrazy/fbstatus/go.mod
./builddir/github.com/gokrazy/gokrazy/go.mod
./builddir/github.com/gokrazy/gokrazy/cmd/randomd/go.mod
./builddir/github.com/gokrazy/gokrazy/cmd/ntp/go.mod
./builddir/github.com/gokrazy/gokrazy/cmd/dhcp/go.mod
./builddir/github.com/gokrazy/rpi-eeprom/go.mod
./builddir/github.com/gokrazy/firmware/go.mod
./builddir/github.com/gokrazy/kernel/go.mod
```

--------------------------------

### Add gokrazy/mkfs to gokrazy instance

Source: https://gokrazy.org/userguide/permanent-data/index.html

Use `gok add` to include the `gokrazy/mkfs` program in your gokrazy installation for automatic filesystem creation.

```bash
gok add github.com/gokrazy/mkfs
```

--------------------------------

### Configure Bootloader EEPROM Settings

Source: https://gokrazy.org/userguide/instance-config/index.html

Add custom lines to the Raspberry Pi's bootloader EEPROM configuration (bootconf.txt). Example sets boot order to prioritize NVMe.

```json
{
    "Hostname": "hello",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ],
    "BootloaderExtraEEPROM": [
	    "BOOT_ORDER=0xf16"
	]
}
```

--------------------------------

### Configure Update with TLS

Source: https://gokrazy.org/userguide/instance-config/index.html

Set up automatic updates for your gokrazy instance, including enabling self-signed TLS certificates for secure communication. This example configures the hostname, update settings, and necessary packages.

```json
{
    "Hostname": "webserver",
    "Update": {
        "HTTPPassword": "secret",
        "UseTLS": "self-signed"
    },
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ]
}
```

--------------------------------

### Create ext4 filesystem on macOS

Source: https://gokrazy.org/userguide/permanent-data/index.html

Create an ext4 filesystem on a macOS device using `mkfs.ext4` after installing e2fsprogs via homebrew. Replace `X` and `Y` with the appropriate disk identifiers.

```bash
$ sudo `brew --prefix e2fsprogs`/sbin/mkfs.ext4 /dev/diskXsY
```

--------------------------------

### Configure Kernel Command Line Arguments

Source: https://gokrazy.org/userguide/instance-config/index.html

Provide extra arguments to the Linux kernel for hardware workarounds. Example enables ACPI resource enforcement.

```json
{
    "Hostname": "hello",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ],
    "KernelExtraArgs": [
	    "acpi_enforce_resources=lax"
	]
}
```

--------------------------------

### Configure gokrazy instance for Caddy

Source: https://gokrazy.org/packages/caddy-http-server/index.html

Modify your instance's config.json to set the HTTP port and configure Caddy's command-line flags and extra file paths. This example moves the gokrazy web interface to port 1080 and configures Caddy to run on port 80 with a specified Caddyfile.

```json
{
    "Hostname": "webserver",
    "Update": {
        "HTTPPort": "1080"
    },
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "github.com/caddyserver/caddy/v2/cmd/caddy"
    ],
    "PackageConfig": {
        "github.com/caddyserver/caddy/v2/cmd/caddy": {
            "CommandLineFlags": [
                "run",
                "--config",
                "/etc/caddy/Caddyfile"
            ],
            "ExtraFilePaths": {
                "/etc/caddy/Caddyfile": "Caddyfile"
            }
        }
    }
}
```

--------------------------------

### Configure Extra Files for Caddy

Source: https://gokrazy.org/userguide/instance-config/index.html

Use ExtraFilePaths to include additional files in the gokrazy instance's root file system. This example adds a Caddyfile to the /etc/caddy directory.

```json
{
    "Hostname": "webserver",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "github.com/caddyserver/caddy/v2/cmd/caddy"
    ],
    "PackageConfig": {
        "github.com/caddyserver/caddy/v2/cmd/caddy": {
            "ExtraFilePaths": {
                "/etc/caddy/Caddyfile": "Caddyfile"
            }
        }
    }
}
```

--------------------------------

### Prepare and Run Grafana Server

Source: https://gokrazy.org/prototyping

After recompiling, download the Grafana server binary, make it executable, and run it. Ensure the binary is placed in the correct directory for execution.

```shell
/tmp/breakglass531810560 # cd grafana-5.3.2
/tmp/breakglass531810560/grafana-5.3.2 # wget http://10.0.0.76:4080/grafana-server
/tmp/breakglass531810560/grafana-5.3.2 # install -m 755 grafana-server bin/ && rm grafana-server
/tmp/breakglass531810560/grafana-5.3.2 # ./bin/grafana-server
```

--------------------------------

### Add Podman and CNI Plugins to gokrazy Installation

Source: https://gokrazy.org/packages/docker-containers/index.html

Include necessary packages for Podman and CNI plugins in your gokrazy installation using the 'gok add' command.

```bash
gok add github.com/gokrazy/iptables
gok add github.com/gokrazy/nsenter
gok add github.com/gokrazy/podman
gok add github.com/greenpau/cni-plugins/cmd/cni-nftables-portmap
gok add github.com/greenpau/cni-plugins/cmd/cni-nftables-firewall
```

--------------------------------

### Boot the image in QEMU

Source: https://gokrazy.org/userguide/qemu/index.html

Executes the generated image using QEMU with a serial console.

```bash
qemu-system-x86_64 \
  -machine accel=kvm \
  -smp 8 \
  -m 2048 \
  -drive file=virtual.img,format=raw \
  -nographic
```

--------------------------------

### Minimal Instance Configuration

Source: https://gokrazy.org/userguide/instance-config/index.html

A basic configuration defining the hostname and a list of included Go packages.

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

--------------------------------

### Add MinIO and mkfs to gokrazy instance

Source: https://gokrazy.org/packages/minio/index.html

Use `gok add` to include the MinIO program and `mkfs` for filesystem initialization on the `/perm` partition during the first boot.

```bash
gok add github.com/minio/minio
# Automatically initialize a file system on the /perm partition on first boot:
gok add github.com/gokrazy/mkfs
```

--------------------------------

### Create and add a package to a gokrazy instance

Source: https://gokrazy.org/development/modules/index.html

Use `gok new` to create a new instance and `gok add` to include a specific Go package. This sets up the necessary build directories and module configurations.

```bash
gok -i scanner new
gok -i scanner add github.com/stapelberg/scan2drive/cmd/scan2drive
```

--------------------------------

### Create a new gokrazy instance

Source: https://gokrazy.org/userguide/qemu/index.html

Initializes a new gokrazy instance configuration in the home directory.

```bash
gok -i virtual new
```

--------------------------------

### List buckets on MinIO instance

Source: https://gokrazy.org/packages/minio/index.html

After creating a bucket, use `mc ls` to list the buckets on your gokrazy MinIO instance and confirm the creation of `testbucket`.

```bash
$ mc ls gokrazy
```

--------------------------------

### Prometheus Web UI Error

Source: https://gokrazy.org/packages/prometheus/index.html

Example error message encountered when web assets are missing.

```text
Error opening React index.html: open web/ui/static/react/index.html: no such file or directory
```

--------------------------------

### Complex Instance Configuration with PackageConfig

Source: https://gokrazy.org/userguide/instance-config/index.html

An advanced configuration demonstrating how to pass command-line flags and environment variables to specific packages.

```json
{
    "Hostname": "ts",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "tailscale.com/cmd/tailscaled",
        "tailscale.com/cmd/tailscale",
        "github.com/gokrazy/mkfs",
        "github.com/stapelberg/dr"
    ],
    "PackageConfig": {
        "tailscale.com/cmd/tailscale": {
            "CommandLineFlags": [
                "up"
            ]
        },
        "tailscale.com/cmd/tailscaled": {
            "CommandLineFlags": [
                "--outbound-http-proxy-listen=localhost:9080"
            ]
        },
        "github.com/stapelberg/dr": {
            "Environment": [
                "HTTPS_PROXY=localhost:9080",
                "HTTP_PROXY=localhost:9080"
            ]
        }
    }
}
```

--------------------------------

### Configure Package Basename

Source: https://gokrazy.org/userguide/instance-config/index.html

Set the Basename field in PackageConfig to install a Go program under a different name than its default.

```json
{
    "PackageConfig": {
        "github.com/gokrazy/rsync/cmd/gokr-rsync": {
            "Basename": "rsync"
        }
    },
    …
}
```

--------------------------------

### Set up MinIO client alias

Source: https://gokrazy.org/packages/minio/index.html

Configure the `mc` command-line tool to alias your gokrazy MinIO instance, providing the endpoint, access key, and secret key.

```bash
$ mc alias set gokrazy http://gokrazy:3001 minio minio-on-gokrazy
```

--------------------------------

### gok build log output

Source: https://gokrazy.org/quickstart/index.html

This log output shows the process of building and preparing the gokrazy system for an SD card. It includes details on package building, file inclusion, kernel modules, partitioning, and file system creation.

```bash
gokrazy gok ga84f00+ on GOARCH=amd64 GOOS=linux

Build target: CGO_ENABLED=0 GOARCH=arm64 GOOS=linux
Build timestamp: 2023-01-12T23:36:34+01:00
Loading system CA certificates from /etc/ssl/certs/ca-certificates.crt
Building 4 Go packages:

  github.com/gokrazy/fbstatus

  github.com/gokrazy/hello

  github.com/gokrazy/serial-busybox

  github.com/gokrazy/breakglass
    will be started with command-line flags
      from /home/michael/gokrazy/hello/config.json
      last modified: 2023-01-12T23:36:23+01:00 (10s ago)

[done] in 1.40s

Including extra files for Go packages:

  github.com/gokrazy/breakglass
    will include extra files in the root file system
      from /home/michael/gokrazy/hello/breakglass.authorized_keys
      last modified: 2023-01-12T23:36:23+01:00 (12s ago)

Including loadable kernel modules from:
/home/michael/go/pkg/mod/github.com/gokrazy/kernel@v0.0.0-20230111172439-0cd82b0bec82/lib/modules

Feature summary:
  use GPT: true
  use PARTUUID: true
  use GPT PARTUUID: true
2023/01/12 23:36:36 partitioning /dev/disk/by-id/usb-TS-RDF5_SD_Transcend_000000000037-0:0 (GPT + Hybrid MBR)
2023/01/12 23:36:36 device holds 15931539456 bytes
2023/01/12 23:36:36 Re-reading partition table failed: permission denied. Remember to unplug and re-plug the SD card before creating a file system for persistent data, if desired.

Creating boot file system
[creating boot file system]
Kernel directory: /home/michael/go/pkg/mod/github.com/gokrazy/kernel@v0.0.0-20230111172439-0cd82b0bec82
EEPROM update summary:
  pieeprom.upd (sig d1e44edf33)
  recovery.bin
  vl805.bin (sig 6246230ecd)
[done] in 0.18s, 71 MiB
MBR summary:
  LBAs: vmlinuz=51795 cmdline.txt=144875
  PARTUUID: 4f9f2cab

Creating root file system
[done] in 0.33s
If your applications need to store persistent data, unplug and re-plug the SD card, then create a file system using e.g.:

	mkfs.ext4 /dev/disk/by-partuuid/60c24cc1-f3f9-427a-8199-4f9f2cab0004

To boot gokrazy, plug the SD card into a supported device (see https://gokrazy.org/platforms/)


Build complete!

To interact with the device, gokrazy provides a web interface reachable at:

	http://gokrazy:<automatically-generated-random-password>@hello/

In addition, the following Linux consoles are set up:

	1. foreground Linux framebuffer console on HDMI

```

--------------------------------

### Configure Command Line Flags for a Package

Source: https://gokrazy.org/userguide/instance-config/index.html

Use CommandLineFlags to specify arguments passed to a program when it starts. No shell escaping is needed.

```json
{
    "Hostname": "ts",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "tailscale.com/cmd/tailscaled"
    ],
    "PackageConfig": {
        "tailscale.com/cmd/tailscaled": {
            "CommandLineFlags": [
                "--port=41641",
                "--outbound-http-proxy-listen=localhost:9080"
            ]
        }
    }
}
```

--------------------------------

### Go program for permanent data access

Source: https://gokrazy.org/userguide/permanent-data/index.html

This Go program demonstrates reading and writing configuration and data files within the `/perm` directory. It creates a config file if it doesn't exist and then creates additional data files based on the configuration.

```go
package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io/fs"
	"io/ioutil"
	"os"
)

const config = "/perm/my-example/config.json"

type Config struct {
	FilesToCreate int `json:"files_to_create"`
}

func main() {
	_, err := os.Stat(config)
	if err != nil {
		fsErr := &fs.ErrNotExist
		if !errors.As(err, fsErr) {
			panic(err)
		}

		content, err := json.Marshal(&Config{FilesToCreate: 4})
		if err != nil {
			panic(err)
		}

		if err = ioutil.WriteFile(config, content, 0600); err != nil {
			panic(err)
		}
	}

	content, err := ioutil.ReadFile(config)
	if err != nil {
		panic(err)
	}

	var c Config
	if err := json.Unmarshal(content, &c); err != nil {
		panic(err)
	}

	for i := 0; i < c.FilesToCreate; i++ {
		if err := ioutil.WriteFile(fmt.Sprintf("/perm/my-example/%d.txt", i), []byte("gokrazy rocks"), 0600); err != nil {
			panic(err)
		}
	}
}
```

--------------------------------

### Configure Runtime Environment Variables

Source: https://gokrazy.org/userguide/instance-config/index.html

Set environment variables that will be active when your program starts. Variables are defined as `key=value` pairs, similar to `os.Environ()` in Go.

```json
{
    "Hostname": "ts",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "github.com/stapelberg/dr"
    ],
    "PackageConfig": {
        "github.com/stapelberg/dr": {
            "Environment": [
                "HTTPS_PROXY=localhost:9080",
                "HTTP_PROXY=localhost:9080"
            ]
        }
    }
}
```

--------------------------------

### Programmatically Run an Irssi Docker Container on gokrazy

Source: https://gokrazy.org/packages/docker-containers/index.html

This Go program demonstrates how to programmatically run an Irssi Docker container on gokrazy. It ensures the system clock is updated, kills and removes any existing 'irssi' container, and then runs a new one with specified volume mounts, environment variables, and network settings. It also includes a helper function to expand the PATH environment variable for Podman.

```go
package main

import (
	"fmt"
	"log"
	"os"
	"os/exec"
	"strings"

	"github.com/gokrazy/gokrazy"
)

func podman(args ...string) error {
	podman := exec.Command("/usr/local/bin/podman", args...)
	podman.Env = expandPath(os.Environ())
	podman.Env = append(podman.Env, "TMPDIR=/tmp")
	podman.Stdin = os.Stdin
	podman.Stdout = os.Stdout
	podman.Stderr = os.Stderr
	if err := podman.Run(); err != nil {
		return fmt.Errorf("%v: %v", podman.Args, err)
	}
	return nil
}

func irssi() error {
	// Ensure we have an up-to-date clock, which in turn also means that
	// networking is up. This is relevant because podman takes what’s in
	// /etc/resolv.conf (nothing at boot) and holds on to it, meaning your
	// container will never have working networking if it starts too early.
	gokrazy.WaitForClock()

	if err := podman("kill", "irssi"); err != nil {
		log.Print(err)
	}

	if err := podman("rm", "irssi"); err != nil {
		log.Print(err)
	}

	// You could podman pull here.

	if err := podman("run",
		"-td",
		"-v", "/perm/irssi:/home/michael/.irssi",
		"-v", "/perm/irclogs:/home/michael/irclogs",
		"-e", "TERM=rxvt-unicode",
		"-e", "LANG=C.UTF-8",
		"--network", "host",
		"--name", "irssi",
		"docker.io/stapelberg/irssi:latest",
		"screen", "-S", "irssi", "irssi"); err != nil {
		return err
	}

	return nil
}

func main() {
	if err := irssi(); err != nil {
		log.Fatal(err)
	}
}

// expandPath returns env, but with PATH= modified or added
// such that both /user and /usr/local/bin are included, which podman needs.
func expandPath(env []string) []string {
	extra := "/user:/usr/local/bin"
	found := false
	for idx, val := range env {
		parts := strings.Split(val, "=")
		if len(parts) < 2 {
			continue // malformed entry
		}
		key := parts[0]
		if key != "PATH" {
			continue
		}
		val := strings.Join(parts[1:], "=")
		env[idx] = fmt.Sprintf("%s=%s:%s", key, extra, val)
		found = true
	}
	if !found {
		const busyboxDefaultPATH = "/usr/local/sbin:/sbin:/usr/sbin:/usr/local/bin:/bin:/usr/bin"
		env = append(env, fmt.Sprintf("PATH=%s:%s", extra, busyboxDefaultPATH))
	}
	return env
}
```

--------------------------------

### Listen on Tailscale addresses with Go

Source: https://gokrazy.org/packages/tailscale/index.html

Demonstrates creating an HTTP server that listens on a Tailscale address and validates the remote user identity using the tailscale.LocalClient.WhoIs method.

```go
package main

import (
	"flag"
	"fmt"
	"log"
	"net/http"

	"tailscale.com/client/tailscale"
)

func main() {
	listen := flag.String("listen", "gokrazy.monkey-turtle.ts.net:8111", "[host]:port listen address")
	allowedUser := flag.String("allowed_user", "", "the name of a tailscale user to allow")
	flag.Parse()
	log.Printf("starting HTTP listener on %s", *listen)
	var ts tailscale.LocalClient
	httpsrv := &http.Server{
		Addr: *listen,
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			who, err := ts.WhoIs(r.Context(), r.RemoteAddr)
			if err != nil {
				http.Error(w, err.Error(), http.StatusInternalServerError)
				return
			}
			if who.UserProfile.LoginName != *allowedUser || *allowedUser == "" {
				err := fmt.Sprintf("you are logged in as %q (userprofile: %+v), but -allowed_user flag does not match!", who.UserProfile.LoginName, who.UserProfile)
				log.Printf("forbidden: %v", err)
				http.Error(w, err, http.StatusForbidden)
				return
			}
			fmt.Fprintf(w, "hey there, %q! this message is served via tailscale from gokrazy!", who.UserProfile.LoginName)
		}),
	}
	log.Fatal(httpsrv.ListenAndServe())
}
```

--------------------------------

### Configure Firmware Package

Source: https://gokrazy.org/userguide/instance-config/index.html

Specify a Go import path for Raspberry Pi firmware files. If empty, no files are included. Defaults to github.com/gokrazy/firmware.

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

--------------------------------

### Build the gokrazy image

Source: https://gokrazy.org/userguide/qemu/index.html

Compiles the instance into a raw image file of a specified size.

```bash
GOARCH=amd64 gok -i virtual overwrite --full virtual.img --target_storage_bytes 4294967296
```

--------------------------------

### Copy and Run WireGuard Binary

Source: https://gokrazy.org/prototyping

Copy the compiled WireGuard binary to the gokrazy system using breakglass and make it executable. The `--help` flag can be used to verify the binary.

```shell
/tmp/breakglass531810560 # wget http://10.0.0.76:4080/wg
/tmp/breakglass531810560 # chmod +x wg
/tmp/breakglass531810560 # ./wg --help
```

--------------------------------

### Overwrite SD card with gokrazy

Source: https://gokrazy.org/quickstart/index.html

Overwrite an entire SD card with a build of the current gokrazy installation. Replace /dev/sdx with the actual device name of your SD card.

```bash
gok overwrite --full /dev/sdx
```

--------------------------------

### Configure wifi package in config.json

Source: https://gokrazy.org/userguide/wifi/index.html

Define the wifi package and its extra file path within the gokrazy instance configuration.

```json
{
    "Hostname": "wifi",
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass",
        "github.com/gokrazy/wifi"
    ],
    "PackageConfig": {
        "github.com/gokrazy/wifi": {
            "ExtraFilePaths": {
                "/etc/wifi.json": "wifi.json"
            }
        }
    }
}
```

--------------------------------

### Configure HTTPS Port for Updates

Source: https://gokrazy.org/userguide/instance-config/index.html

Configure the HTTPS port for gokrazy updates when TLS is enabled. This example sets the HTTPS port to 8443 and uses self-signed certificates.

```json
{
    "Hostname": "webserver",
    "Update": {
        "HTTPPassword": "secret",
        "UseTLS": "self-signed",
        "HTTPSPort": "8443"
    },
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ]
}
```

--------------------------------

### Execute packaged binary on gokrazy

Source: https://gokrazy.org/development/non-go/index.html

Download the tarball to the gokrazy device and execute the binary using the bundled dynamic loader.

```bash
/tmp/breakglass531810560 # wget -O- http://10.0.0.76:4080/freeze2237965672.tar | tar xf -
/tmp/breakglass531810560 # cd freeze2237965672
/tmp/breakglass531810560/freeze2237965672 # LD_LIBRARY_PATH=$PWD ./ld-linux-aarch64.so.1 ./tc
Usage: tc [ OPTIONS ] OBJECT { COMMAND | help }
…
```

--------------------------------

### Migrate instance config with gokr-packer

Source: https://gokrazy.org/userguide/migration-guide/index.html

Run your gokr-packer command with the -write_instance_config flag to create the new instance directory and config.json.

```bash
gokr-packer \
  -write_instance_config=scanner \
  -hostname=scanner \
  -update=yes \
  github.com/gokrazy/hello \
  github.com/gokrazy/breakglass \
  github.com/gokrazy/serial-busybox \
  github.com/stapelberg/scan2drive/cmd/scan2drive
```

--------------------------------

### Download and Run tc on gokrazy

Source: https://gokrazy.org/prototyping

On the gokrazy device, download the frozen `tc` binary archive, extract it, and then run `tc` using the provided dynamic loader and library path.

```bash
/tmp/breakglass531810560 # wget -O- http://10.0.0.76:4080/freeze2237965672.tar | tar xf -
/tmp/breakglass531810560 # cd freeze2237965672
/tmp/breakglass531810560/freeze2237965672 # LD_LIBRARY_PATH=$PWD ./ld-linux-aarch64.so.1 ./tc
```

--------------------------------

### Schedule Daily Rsync Backup with Cron

Source: https://gokrazy.org/userguide/rsync-backups/index.html

Configures a daily cron job to automatically run the rsync backup script. This example schedules the backup to run at 7:30 AM every day.

```cron
30 07 * * * /home/michael/scan2drive-backup-sync.sh
```

--------------------------------

### Edit instance configuration with gok CLI

Source: https://gokrazy.org/userguide/migration-guide/index.html

Open your instance's configuration file in your default editor using the gok CLI. Specify the instance name with -i.

```bash
gok -i scanner edit
```

--------------------------------

### Configure HTTP Port for Updates

Source: https://gokrazy.org/userguide/instance-config/index.html

Customize the HTTP port used for gokrazy updates and the web interface. This is useful if port 80 is already in use. This example sets the HTTP port to 1080.

```json
{
    "Hostname": "webserver",
    "Update": {
        "HTTPPassword": "secret",
        "HTTPPort": "1080"
    },
    "Packages": [
        "github.com/gokrazy/fbstatus",
        "github.com/gokrazy/hello",
        "github.com/gokrazy/serial-busybox",
        "github.com/gokrazy/breakglass"
    ]
}
```

--------------------------------

### Create gokrazy rsync Daemon Configuration

Source: https://gokrazy.org/userguide/rsync-backups/index.html

Sets up the TOML configuration file for the gokrazy rsync daemon, defining listeners and modules. This file specifies the SSH listener address and the path to serve.

```bash
cat > ~/gokrazy/hello/gokr-rsyncd.toml <<'EOT'
don't_namespace = true 
[[listener]]
  [listener.authorized_ssh]
    address = "scan2drive.lan:22873"
    authorized_keys = "/etc/gokr-rsyncd.authorized_keys"
[[module]]
  name = "scans"
  path = "/perm/scans"
EOT
```

--------------------------------

### Edit gokrazy Configuration

Source: https://gokrazy.org/packages/prometheus/index.html

Opens the instance configuration file for editing.

```bash
gok edit
```

--------------------------------

### Cross-compile WireGuard using Docker

Source: https://gokrazy.org/prototyping

Cross-compile the WireGuard tools for ARM64 architecture within a Debian Docker container. This involves installing necessary development packages and using make with a specific C compiler.

```shell
% mkdir /tmp/wg
% cd /tmp/wg
% docker run -t -i debian
root@d1728eaaa6e1:/# dpkg --add-architecture arm64
root@d1728eaaa6e1:/# apt update
root@d1728eaaa6e1:/# apt install libmnl-dev:arm64 libelf-dev:arm64 linux-headers-amd64 crossbuild-essential-arm64 pkg-config wget
root@d1728eaaa6e1:/# wget https://git.zx2c4.com/WireGuard/snapshot/WireGuard-0.0.20181018.tar.xz
root@d1728eaaa6e1:/# tar xf WireGuard-0.0.20181018.tar.xz
root@d1728eaaa6e1:/# cd WireGuard-0.0.20181018/src/tools
root@d1728eaaa6e1:/# make CC=aarch64-linux-gnu-gcc LDFLAGS=-static
root@d1728eaaa6e1:/# exit
% docker cp -L d1728eaaa6e1:/WireGuard-0.0.20181018/src/tools/wg .
```

--------------------------------

### Deploy Program to gokrazy

Source: https://gokrazy.org/development/gpio/index.html

Commands to add and update a gokrazy application from the project directory.

```bash
# From the hello-gpio directory, run:
gok add .
# Then, deploy as usual:
gok update
```

--------------------------------

### Build Prometheus Web Assets

Source: https://gokrazy.org/packages/prometheus/index.html

Commands to clone the repository and build the required web assets.

```bash
git clone https://github.com/prometheus/prometheus
cd prometheus
make assets-compress
```

--------------------------------

### Update gokrazy instance

Source: https://gokrazy.org/packages/caddy-http-server/index.html

After making configuration changes and creating the Caddyfile, run this command to deploy the updates to your gokrazy instance.

```bash
gok update
```

--------------------------------

### Configure command-line flags

Source: https://gokrazy.org/userguide/package-config/index.html

Use CommandLineFlags to pass arguments to the package at runtime.

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

--------------------------------

### Configure SSH Client for Backup

Source: https://gokrazy.org/userguide/rsync-backups/index.html

Sets up the SSH client configuration on the backup machine to connect to the gokrazy rsync daemon. This includes specifying the hostname, custom port, and identity file for passwordless authentication.

```sshconfig
Host scan2drive-backup
    Hostname scan2drive.lan
    Port 22873
    IdentityFile ~/.ssh/id_ed25519_scan2drivebackup
```
Tokens:
Raw