Skip to content
a pure-Go userland for your Raspberry Pi 3 appliances
Go HTML CSS
Branch: master
Clone or download

Latest commit

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github rename GitHub action workflow to diskimage May 31, 2020
assets status: use partuuid-based path in mkfs instruction May 30, 2020
cmd dhcp: make network interface name configurable May 27, 2020
docs add userguide entries for unencrypted wifi and tls Jun 1, 2020
empty add empty package Mar 5, 2017
internal status: use partuuid-based path in mkfs instruction May 30, 2020
website add userguide entries for unencrypted wifi and tls Jun 1, 2020
LICENSE Initial commit Mar 4, 2017
README.md README: FAT16B → SquashFS May 25, 2020
authenticated.go Initial commit Mar 4, 2017
bundle.go gofmt GENERATED_bundled.go Nov 9, 2019
doc.go Initial commit Mar 4, 2017
go.mod pull in latest gokrazy/internal May 31, 2020
go.sum pull in latest gokrazy/internal May 31, 2020
goembed.go Initial commit Mar 4, 2017
gokrazy.go Added proof of concept TLS support (#7) (#53) May 31, 2020
httpsredirect.go Added proof of concept TLS support (#7) (#53) May 31, 2020
listeners.go
mount.go update to new rootdev API Apr 7, 2020
netlink.go update listeners when netlink reports an address change Nov 1, 2018
reboot.go reboot: use kexec where possible Jun 17, 2018
reboot_amd64.go update to new rootdev API Apr 7, 2020
status.go status: use partuuid-based path in mkfs instruction May 30, 2020
supervise.go status: print module info details May 30, 2020
update.go fix switchRootPartition on non-PARTUUID installations May 1, 2020
xsrf.go implement XSRF/CSRF protection for /stop and /restart Jun 25, 2018

README.md

Build Status Go Report Card

Overview

gokrazy packs your Go application(s) into an SD card image for the Raspberry Pi 3 which — aside from the Linux kernel and proprietary Raspberry Pi bootloader — only contains Go software.

The motivation is that @stapelberg spends way more time on C software and their various issues than he would like. Hence, he is going Go-only where feasible.

Usage

Installation

Install the latest Go version if you haven’t already.

Then, use the go tool to download and install gokr-packer:

go get -u github.com/gokrazy/tools/cmd/gokr-packer

Overwriting an SD card for the Raspberry Pi 3

To re-partition and overwrite the SD card /dev/sdx, use:

gokr-packer -overwrite=/dev/sdx github.com/gokrazy/hello

Then, put the SD card into your Raspberry Pi 3 and power it up! Once the Raspberry Pi 3 has booted (takes about 10 seconds), you should be able to reach the gokrazy web interface at the URL which gokr-packer printed.

Under the hood, gokr-packer

  1. …packed the latest firmware and kernel binaries into the boot file system.

  2. …built the specified Go packages using go install and packed all their binaries into the /user directory of the root file system.

  3. …created a minimal gokrazy init program which supervises all binaries (i.e. restarts them when they exit).

Updating your installation

To update gokrazy, including the firmware and kernel binaries, use:

go get -u github.com/gokrazy/tools/cmd/gokr-packer

To update your gokrazy installation (running on a Raspberry Pi 3), use:

GOKRAZY_UPDATE=http://gokrazy:mysecretpassword@gokrazy/ gokr-packer github.com/gokrazy/hello

SD card contents

gokrazy uses the following partition table:

num size purpose file system
1 100 MB boot (kernel+firmware) FAT16B
2 500 MB root2 (gokrazy+apps) SquashFS
3 500 MB root3 (gokrazy+apps) SquashFS
4 rest permanent data ext4

The two root partitions are used alternatingly (to avoid modifying the currently active file system) when updating.

If you’d like to store permanent data (i.e. data which will not be overwritten on the next update), you’ll need to create an ext4 file system on the last partition. If your SD card is /dev/sdx, use mkfs.ext4 /dev/sdx4.

Customization

Changing program behavior for gokrazy

gokr-packer sets the “gokrazy” build tag for conditional compilation.

You can find an example commit which implements a gokrazy-specific controller that triggers the main program logic every weekday at 10:00 at https://github.com/stapelberg/zkj-nas-tools/commit/6f90ace35981f78dcd66d611269f17f37ce4b4ef

Changing init behavior

Assuming the application you’d like to create on gokrazy lives in the repository github.com/stapelberg/mediaserver, this is how you can make gokrazy dump the generated init package’s source:

mkdir -p $(go env GOPATH)/src/github.com/stapelberg/mediaserver/cmd/init
gokr-packer \
  -overwrite_init=$(go env GOPATH)/src/github.com/stapelberg/mediaserver/cmd/init/init.go \
  github.com/gokrazy/hello

(Note that the package must result in a binary called “init”.)

Then, edit the github.com/stapelberg/mediaserver package to your liking. When done, pack an image with your own init package:

gokr-packer \
  -init_pkg=github.com/stapelberg/mediaserver/cmd/init \
  -overwrite=/dev/sdx \
  github.com/gokrazy/hello

Repository structure

You can’t perform that action at this time.