Skip to main content

Install BoatKit with Podman

Use this early-access installation target only when you intentionally want to keep and maintain an existing Linux system. If you are dedicating a device to BoatKit, need BoatKit hardware profiles, or want an onboard BoatKit display, follow Build a BoatKit device for the more complete managed device-image path.

Early-access target

This target has not yet completed a clean-host acceptance run on a named Linux, Raspberry Pi, Wi-Fi, and CAN configuration. Verify the requirements below for your host. Do not treat this package as a production-qualified appliance image.

The Podman package installs and updates the BoatKit vessel runtime. It does not install or manage the host operating system, firmware, boot configuration, firewall, NetworkManager, Podman, or an attached-display browser or kiosk. It leaves host networking unchanged by default. This is a headless target: BoatKit serves native apps and browsers over the network, but it does not add a BoatKit display to the Linux desktop.

Before you start​

You need:

  • A 64-bit Linux host using ARM64 (aarch64), including a compatible Raspberry Pi host, or x86-64 (x86_64).
  • systemd and cgroup v2.
  • Podman 5 or newer with Quadlet, Podman's systemd integration.
  • Root or sudo access.
  • The host system D-Bus socket at /run/dbus/system_bus_socket and host udev data at /run/udev.
  • An active internet connection for initial account and BoatKit Cloud registration and for future updates.
  • A BoatKit native or desktop app signed in to an accepted early-access account.

Podman's official Linux installation page and the Raspberry Pi networking documentation can help you prepare the host. Distribution package versions differ, so verify the installed Podman major version instead of relying on the distribution name or release. These references do not indicate that a particular host configuration has been validated for BoatKit.

The commands below are read-only:

uname -m
podman version --format '{{.Client.Version}}'
podman info --format '{{.Host.CgroupsVersion}}'
test -S /run/dbus/system_bus_socket && echo "system D-Bus is available"
test -d /run/udev && echo "udev is available"

Check the results:

  • aarch64 uses the Linux ARM64 bundle. x86_64 uses the Linux x64 bundle. Other architectures are not supported by these bundles.
  • The Podman version must start with 5 or a larger major version.
  • The cgroup result must be v2.
  • The final two commands must report that system D-Bus and udev are available.

These commands do not independently prove that your Podman package includes every Quadlet component. Confirm Quadlet availability through your operating system's Podman packaging documentation.

Download and install BoatKit​

  1. Sign in to BoatKit Account Web with an accepted early-access account.

  2. Find BoatKit vessel host for Podman, then select Download for Linux ARM64 for aarch64 or Download for Linux x64 for x86_64.

  3. In a terminal, change to the directory containing the download and run:

    tar -xzf BoatKit-*-linux-*-podman.tar.gz
    cd BoatKit-*-linux-*-podman
    sudo ./install.sh

The download card appears only after a Podman release is available. If you are signed in with an accepted account but do not see the card, there is no release available to install yet; the missing card does not indicate an account error.

The first archive includes the BoatKit container image. The installer therefore does not need a public-registry login or the vessel's BoatKit credential.

During installation, the installer:

  • Confirms the host architecture, Podman version, cgroup version, D-Bus socket, and udev directory.
  • Imports the bundled image and assigns it the local localhost/boatkit:stable tag.
  • Installs and starts the rootful boatkit.service Quadlet service.
  • Waits for BoatKit's /ready health check before accepting the service as started.
  • Enables boatkit-update.timer for future updates.

An existing /etc/boatkit/boatkit.env file is preserved. When replacing an existing BoatKit installation, the installer restores the previous image tag if the replacement does not pass its initial health gate.

Choose who manages Wi-Fi​

Host-managed networking (default)​

Podman installations leave Wi-Fi and Ethernet configuration to the host administrator. Connect the host to the ordinary vessel LAN before installing BoatKit. BoatKit still listens and advertises boatkitsetup.local on eligible existing interfaces; disabling Wi-Fi management does not disable LAN discovery, local access, or BoatKit Cloud connectivity.

Optional BoatKit-managed Wi-Fi​

You can explicitly allow BoatKit to reconfigure one host Wi-Fi adapter and create the open BoatKit Setup network. The adapter must be managed by an active NetworkManager service, and its hardware and driver must support access-point mode.

Check the host's interface name before enabling this option:

systemctl is-active NetworkManager.service
nmcli -t -f DEVICE,TYPE device status

Edit /etc/boatkit/boatkit.env as root. Set the actual interface name reported by NetworkManager; it does not have to be wlan0.

GOATKIT_MANAGE_WIFI=1
GOATKIT_WIFI_INTERFACE=wlan0

Apply the host-level change:

sudo systemctl restart boatkit.service
BoatKit can change this adapter's connection

This opt-in lets the privileged BoatKit container disconnect, enable, disable, scan, and reconnect the selected Wi-Fi adapter. It can also create an open BoatKit Setup network with a local DHCP and DNS service. Do not enable it for an adapter whose existing connection must remain under another network manager's control.

The installer preserves /etc/boatkit/boatkit.env during upgrades. Set GOATKIT_MANAGE_WIFI=0 and restart boatkit.service to return networking control to the host. BoatKit stops any setup network it started before the service exits.

Provision the vessel runtime​

With the default host-managed networking:

  1. Keep the signed-in BoatKit native or desktop app on the same ordinary LAN as the host.
  2. The unregistered runtime advertises boatkitsetup.local on eligible LAN interfaces. When background discovery succeeds, the app may show Set Up The New BoatKit Device.
  3. Open the device and complete its account and BoatKit Cloud registration.

If you explicitly enabled BoatKit-managed Wi-Fi and the selected interface is not already connected:

  1. Wait for the open BoatKit Setup network.
  2. In the signed-in app, select Setup New Device—or Setup Device when no vessels are listed—and then Brand New BoatKit Device.
  3. Join BoatKit Setup when prompted. In the embedded setup page at http://10.42.0.1/, select the ordinary Wi-Fi network the vessel will use.
  4. When the setup flow reports BoatKit found, open the device and complete its account and BoatKit Cloud registration.

If the selected Wi-Fi interface already has a working connection, BoatKit keeps that connection and uses the ordinary-LAN discovery path instead of opening the setup network.

Do not use a chartplotter's isolated marine Ethernet network for this internet and ordinary-LAN connection path.

Prepare marine hardware separately​

A generic Podman installation does not create device-tree overlays or BoatKit hardware profiles for CAN HATs. The host must already expose the intended CAN, USB, or serial hardware to Linux.

Use the managed device-image path when you need an onboarding-supplied CAN HAT profile. See Build a BoatKit device for hardware selection and marine installation guidance.

Host access and storage​

BoatKit uses these host locations:

  • Persistent vessel data: /var/lib/boatkit
  • Optional environment overrides: /etc/boatkit/boatkit.env
  • Local Quadlet overrides: /etc/containers/systemd/boatkit.container.d/*.conf
  • Secured, replaceable update candidates and credentials: /var/lib/boatkit/updates

The container deliberately runs rootfully and privileged, with host networking and access to host D-Bus, udev, and devices. This access allows BoatKit to work with marine and network hardware, but it is not ordinary container isolation from the host. Treat the computer as a trusted vessel host.

How automatic updates and rollback work​

After BoatKit Cloud registration:

  1. The runtime checks for an update when its authenticated vessel relay connects and periodically thereafter.
  2. BoatKit Cloud returns a short-lived, pull-only private-registry credential only when a newer Podman release is available.
  3. The root updater timer runs after boot and every few minutes. It pulls only the needed OCI image layers, removes the temporary registry credential, updates the local localhost/boatkit:stable tag, and restarts boatkit.service. The credential is not stored in Podman's normal login store and is not the vessel's BoatKit credential.
  4. systemd waits up to three minutes for the new image's /ready check. If it does not become healthy, the updater retags and restarts the previous local image. It records the rejected version so the same failed release is not installed repeatedly.
  5. If the registry download fails, the current service and image remain in place and the download is retried later.

Rollback changes only the container image. BoatKit retains data under /var/lib/boatkit, so rollback is not a database downgrade mechanism.

Confirm it is working​

Run these read-only checks:

systemctl status boatkit.service
systemctl status boatkit-update.timer
curl --fail http://127.0.0.1:12456/ready

Successful operation looks like this:

  • boatkit.service is active and running.
  • boatkit-update.timer is active and waiting for its next run.
  • The /ready request succeeds.
  • The BoatKit app finds the device, BoatKit Cloud registration completes, and BoatKit opens from a device on the ordinary LAN.

Do not force an update or restart the service merely to verify the installation.

Operation without internet​

After installation and registration, the BoatKit runtime, local vessel data, local integrations, and LAN viewers continue to operate without an internet connection.

First BoatKit Cloud registration, remote access, cloud services, and software updates require internet access.

Troubleshooting​

The download card is missing​

Confirm that you are signed in to Account Web with an accepted early-access account. If you are and BoatKit vessel host for Podman is still absent, no Podman release is currently available to install.

The installer stops during preflight​

  • Wrong bundle architecture: Run uname -m again and download Linux ARM64 for aarch64 or Linux x64 for x86_64.
  • Podman is older than version 5: Update Podman through a supported method for your Linux distribution, then rerun the version check.
  • The cgroup result is not v2: The host does not meet the package contract. Correct the host's cgroup configuration before installing BoatKit.
  • D-Bus or udev is missing: Restore the host system D-Bus socket or udev runtime directory. The BoatKit installer does not configure those host services.
  • Quadlet is unavailable: Confirm that the host's Podman packaging includes Quadlet. A Podman version number alone does not guarantee that every component is installed.

The BoatKit Setup network does not appear​

Podman leaves Wi-Fi under host control by default. Confirm that /etc/boatkit/boatkit.env contains GOATKIT_MANAGE_WIFI=1. If it contains 0, keep the app on the same ordinary LAN and look for Set Up The New BoatKit Device instead.

When Wi-Fi management is enabled, confirm that NetworkManager.service is active, GOATKIT_WIFI_INTERFACE exactly matches the intended Wi-Fi adapter, and its adapter and driver support AP mode. If that interface already has a working connection, the missing setup network is expected.

BoatKit does not start after editing boatkit.env​

GOATKIT_MANAGE_WIFI must be 0 or 1. GOATKIT_WIFI_INTERFACE must contain a Linux interface name of 1–15 letters, numbers, dots, underscores, or hyphens. Correct the value, then restart boatkit.service.

BoatKit does not become healthy​

Repeat the service and /ready checks from Confirm it is working, then inspect the runtime log:

journalctl -u boatkit.service

Look for the first startup or health-check error. If the local /ready check succeeds but the app cannot find BoatKit, confirm that the app and host are on the same ordinary LAN. The installer does not modify the host firewall, so the host's existing network policy still applies.

Updates do not arrive​

Confirm that the vessel completed BoatKit Cloud registration, currently has an internet connection, and is connected to BoatKit Cloud. Also confirm that boatkit-update.timer is active.

Inspect both logs:

journalctl -u boatkit.service
journalctl -u boatkit-update.service

The runtime log can show BoatKit Cloud update-check problems. The updater log can show registry download or health-gate failures. A failed download leaves the current release running and is retried later.