Skip to content

First Start

Jump to bottom
bigbrainlabs edited this page Jul 23, 2026 · 1 revision

First Start

From a flashed image to a working chart with a GPS fix. This is the image route — the fastest way in, no Linux knowledge required. If you'd rather install from source, follow docs/installation.md instead.

Prerequisite: an SSD or SD card and the hardware from the Hardware page. An SSD is strongly recommended.

1. Download the image

Get the latest image from archive.org (~7.5 GB). It contains everything — the OS, all services, map data for Germany, and the built-in over-the-air updater. Anything newer than the image is pulled in later by the updater.

→ Download page and current link

2. Flash it

Use balenaEtcher (free, Windows/Mac/Linux) or the Raspberry Pi Imager: select the .img.gz file, select your SSD or SD card, click Flash. It's the same as flashing any USB stick.

3. Configure WiFi before first boot

After flashing, open the drive on your computer and edit wlan.txt in the root directory:

SSID=YourBoatNetwork
PASSWORD=YourPassword

You can skip this if you connect the Pi by LAN cable — which is the more stable option anyway (see Hardware).

4. Insert and power on

Put the SSD/SD into the Pi, connect the touchscreen and the GPS puck, power on. BoatOS boots automatically into Helm. The GPS position appears once the puck has a fix — give it a few minutes on first use, and make sure it has a clear view of the sky.

5. Open Deck from a phone or tablet

Connect your device to the same network as the Pi, open a browser and enter the Pi's address:

http://boatos.local:8000

If that doesn't resolve (some browsers can't handle .local, see Common Pitfalls), use the Pi's IP address directly, e.g. http://192.168.x.x:8000. Deck gives you the full chart and monitoring in the browser — no touchscreen required.

6. Change the default password

The image ships with a default password. Change it before the boat goes on the water:

ssh boatos@boatos.local
passwd

Staying up to date

BoatOS has a built-in updater — no reflashing needed. Under Settings → System you pick a channel:

  • stable — released versions only (currently v1.7.3). The default.
  • beta — pre-releases too (the v1.8 line with official charts and the route hazard check).

For what each channel contains, see the table on Home. Switching back to stable is safe.

Next: Maps & Charts — add offline maps and official charts. If anything misbehaves: Common Pitfalls.

BoatOS Wiki

Home

Getting started

When things go wrong

Clone this wiki locally