Run the course project on Windows

This repository currently contains the course book, not the completed app source. You create the field-notes app by following the chapters. Do not run go run from the book folder; it has no go.mod or server source yet.

The course uses PowerShell and an Android emulator for the mobile client. Flutter can build an iOS app only from macOS; on Windows, use Android, Windows desktop, or web as your target.

1. Install the tools

Go

Install the current stable Go release from go.dev/dl. Open a new PowerShell window and verify:

go version

Flutter and Android

Install Flutter using the official Windows instructions and add <flutter-sdk>\bin to your Windows Path. Install Android Studio, then open Device Manager and create/start an Android emulator. In PowerShell, run:

flutter doctor
flutter doctor --android-licenses
flutter devices

Accept the Android SDK licenses when prompted. flutter devices should list your running emulator. If Android Studio reports missing SDK components, install the components it identifies and run flutter doctor again.

Protocol Buffer compiler

Install protoc using WinGet, then reopen PowerShell:

winget install protobuf
protoc --version

If WinGet cannot find the package on your machine, download the Windows ZIP from the protobuf compiler installation guide, extract it, and add its bin directory to Path.

Go and Dart code generators

Install the Go generators and make them visible in the current PowerShell session:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
$env:Path += ";$(go env GOPATH)\bin"

Install the Dart generator and add Pub's Windows executable directory to this session's PATH:

dart pub global activate protoc_plugin
$env:Path += ";$env:LOCALAPPDATA\Pub\Cache\bin"

To make these PATH additions permanent, search Windows for Edit environment variables for your account, select Path, and add the two directories. Open a new terminal afterward.

Verify the tools:

protoc --version
protoc-gen-go --version
protoc-gen-go-grpc --version
flutter --version
dart --version

If PowerShell cannot resolve a generator, check PATH. The Go executables are in $(go env GOPATH)\bin; the Dart global executable directory is usually %LOCALAPPDATA%\Pub\Cache\bin.

2. Create the course project

Open PowerShell and create an app folder. For example, keep it next to the book:

cd "D:\Projects"
mkdir field-notes
cd field-notes

Now follow the chapters in order. Chapter 1 initializes the Go module at this new folder's root. Chapters 1–6 teach the Go foundations; chapters 7–10 create the shared API, Go server, and Flutter client.

3. Run the Go server

After completing the proto generation and Go server chapters, open a PowerShell terminal in the field-notes root and start the service:

go run ./server/cmd/api

Keep this terminal open. It should print that gRPC is listening on port 50051.

4. Run Flutter on the Android emulator

Open a second PowerShell terminal:

cd "D:\Projects\field-notes\flutter_app"
flutter pub get
flutter run --dart-define=GRPC_HOST=10.0.2.2

Choose the Android emulator if Flutter asks for a device. 10.0.2.2 is the Android emulator's special route to the Windows host, where the Go server is listening. Tap Load task; the sample task should appear. If the screen shows a connection error, check that the Go terminal is still running and that the emulator can reach port 50051 through Windows Firewall.

For a physical Android phone, connect it to the same LAN as the PC and pass the PC's LAN IP instead, such as --dart-define=GRPC_HOST=192.168.1.25. Allow inbound traffic to port 50051 on the private network only. Do not use the insecure local channel for a release build; the later security chapter configures TLS.

5. Read the book on Windows

Open README.md or SUMMARY.md in VS Code or another Markdown editor. To publish it as an online GitBook, connect/import this folder as a GitBook content source; that is separate from running the Go/Flutter project.

Common problems

go or flutter is not recognized: add the SDK's bin directory to PATH and open a fresh terminal.
protoc-gen-go is not recognized: add $(go env GOPATH)\bin to PATH.
protoc-gen-dart is not recognized: add %LOCALAPPDATA%\Pub\Cache\bin to PATH.
flutter devices shows no Android device: start an emulator in Android Studio's Device Manager, then run flutter doctor again.
gRPC connection refused: start the Go server and pass 10.0.2.2 when using the Android emulator.
A chapter command cannot find a file: make sure you created the project files from preceding chapters and run the command from the stated working directory.

Run the course on Windows