Running the gateway

Who this is for: whoever looks after the computer on the vessel or mast during a campaign.

What you need:

A computer running Linux or macOS (Intel or ARM), connected to the gateway radio by USB. There is no Windows version.
Internet access from that computer, with outbound connections to port 8883 allowed. If the site has a firewall, ask for mqtt.marine.nebli.ai on port 8883 to be open outbound.
A gateway credential for the campaign: its id and its secret. An administrador creates it in Settings, as described in Getting started. The secret is shown once; the id stays visible in the credentials list.

What the gateway does

The gateway reads the drifters' reports from the radio, keeps every one of them in a buffer on the computer, and sends them to Nebli Marine over the campaign's credential. It removes a reading from its buffer only after Nebli Marine has confirmed receiving it. If the internet connection drops, readings keep collecting in the buffer, and the gateway sends the backlog in order when the connection returns. You do not need to do anything.

The gateway does not show your record. Campaigns, maps and exports are in the web app.

1. Download and check it

Releases are published at downloads.nebli.ai/marine/gateway/. The file latest.json there names the current version, and each version has four archives, one per computer:

Computer	Archive ends in
Mac with Apple silicon	`_darwin_arm64.tar.gz`
Mac with an Intel processor	`_darwin_amd64.tar.gz`
Linux, Intel or AMD	`_linux_amd64.tar.gz`
Linux, ARM	`_linux_arm64.tar.gz`

Each version also carries a signed list of checksums (SHA256SUMS and SHA256SUMS.sig) and the release's public key (release-key.pem). Check all three before you run anything.

This downloads the current version for a Mac with Apple silicon, checks it and unpacks it. For another computer, change darwin_arm64 on the third and last lines:

BASE=https://downloads.nebli.ai/marine/gateway
V=$(curl -fsS $BASE/latest.json | sed 's/.*"version":"\([^"]*\)".*/\1/')
ARCHIVE=marine-gateway_v${V}_darwin_arm64.tar.gz
for f in $ARCHIVE SHA256SUMS SHA256SUMS.sig release-key.pem; do curl -fsSO $BASE/versions/$V/$f; done
openssl pkey -pubin -in release-key.pem -outform DER | shasum -a 256
openssl dgst -sha256 -verify release-key.pem -signature SHA256SUMS.sig SHA256SUMS
shasum -a 256 --ignore-missing -c SHA256SUMS
tar -xzf $ARCHIVE
cd marine-gateway_v${V}_darwin_arm64 && ./marine-gateway version

Read the output of the three checks before going further:

The public key. The first line printed must be exactly:
```
611943c24df2f671dd523231bc2861e3dc767afd829eaf32e9d44145f27a5eff  -
```
A key downloaded from the same place as the archive proves nothing until its fingerprint matches this one.
The signature on the list. It must say Verified OK.
Your archive against the list. It must say OK after the archive's name. On Linux, use sha256sum --ignore-missing -c SHA256SUMS in place of the shasum line.

If any of the three fails, do not run the program.

The archive unpacks into a folder named after the version and your computer, holding the marine-gateway program, a README, and THIRD_PARTY_NOTICES, which lists the open-source software inside the program. The last line prints the version you have.

If you download the archive with a browser on a Mac, the build is not notarized yet: after checking it, clear the download quarantine once with xattr -d com.apple.quarantine marine-gateway.

2. Store the secret

Put the credential's secret in a file of its own, on one line, readable only by you:

chmod 600 gateway-secret

The gateway refuses a secret file that anyone else can read or write. It also refuses a secret written into the configuration file or given on the command line, so the secret never ends up in a shared file or in your shell history. On a machine where a file does not suit you, you can pass the secret in the MARINE_GATEWAY_SECRET environment variable instead, but not both ways at once.

3. Write the configuration

The configuration is a plain file of key = value lines. Tell the gateway where it is with the MARINE_GATEWAY_CONFIG environment variable.

credential_id = <the credential's id>
secret_file   = /path/to/gateway-secret
source        = serial:<the radio's device>

Setting	What it is
`credential_id`	The credential's id, from the list in Settings. Required.
`secret_file`	The file that holds the secret. Required unless you use `MARINE_GATEWAY_SECRET`.
`source`	Where the radio is: `serial:` followed by the radio's device, with `@` and a baud rate if yours needs one. Required.
`buffer`	Where the buffer file is kept. Defaults to `gateway-buffer.db` in the folder you run the gateway from.
`broker`	Where the gateway sends readings. Defaults to `mqtt.marine.nebli.ai:8883`; leave it as it is.

Each setting can also come from an environment variable, which wins over the file: MARINE_GATEWAY_CREDENTIAL_ID, MARINE_GATEWAY_SECRET_FILE, MARINE_GATEWAY_SOURCE, MARINE_GATEWAY_BUFFER and MARINE_GATEWAY_BROKER. The gateway refuses a setting it does not know, so a typo is caught before anything runs.

4. Run it

marine-gateway run

It reads the radio and sends readings until you stop it.

5. Check on it

marine-gateway status

Status shows whether the link to Nebli Marine is up, how many readings are waiting in the buffer, and when Nebli Marine last confirmed receiving them. It reads the buffer only, so it works even while the link is down, and it does not need the secret. If it cannot find the buffer, it says which file it looked for.

marine-gateway version

prints the version of the build you are running.

To confirm readings are arriving, open Data stream in the web app.

If you lose the computer

Revoke its credential in Settings. Its gateway is disconnected at once and can send nothing more; the readings it already sent stay in your record. Create a new credential for the replacement computer.