Get the Edge Server

The Edge Server runs Growbud on your site. It keeps working when the internet is down. You can get an Edge Server from Growbud, or install the software on your own computer.

An Edge Server from Growbud

An Edge Server from Growbud comes ready to run. It is a standard PC with Ubuntu. The Edge Server software and the Growbud desktop app are installed.

  1. Connect the Edge Server to your network with an Ethernet cable.
  2. Connect a monitor, a keyboard and a mouse.
  3. Start the computer and wait for the desktop.
  4. Open the Growbud desktop app. It signs in with no password.
  5. Set a new administrator password when the app asks.

Use the desktop app on the Edge Server for your sensors, zones, charts and settings. You can also use the computer as a standard PC.

Add your phone. In the desktop app, open Settings, then Edge Server. Connect a phone shows a QR code. Scan it with the Growbud mobile app. The phone signs in with no password. The mobile app can also sign in with the IP address or the host name of the Edge Server. See Link your phone to an Edge Server.

API. The Edge Server has the Read API and the Write API. See Authentication and the Read API reference when you need them.

For the first password, the address of the box and the ports, see First boot and accounts.

Install it on your own computer

The Write API and the outlet and Controller reads run on the Growbud Edge Server. Install it on a computer on your site.

The Edge Server runs in Docker. On Linux, the Growbud desktop app on the same computer signs in to it without a password, shows its version and updates it.

On macOS or Linux, the Growbud desktop app can also install, start and stop the Edge Server on the same computer.

Calls to the Edge Server are free. API costs apply to Growbud Cloud only.

Install on Linux or macOS: version 5.4.6

BASH
curl -fsSL https://growbud.io/edge/install.sh | sudo bash

Run it on the Edge Server computer. Run it again to upgrade. For Windows, the files, the SHA-256 and the signature, go to Download Edge Server.

1. Check the computer

ItemNeed
CPU4 cores, x86-64 or ARM64
Memory for Docker16 GB (8 GB for a test)
Free disk100 GB SSD (20 GB for a test)
SoftwareDocker Engine 24+ with Compose v2, or Docker Desktop 4.30+
NetworkA fixed IP address on your LAN

2. Install

Run the command above. The installer:

  1. Downloads the latest release and checks its SHA-256 and signature.
  2. Installs it in /opt/growbud-edge.
  3. Starts the Edge Server and shows its address, for example https://192.0.2.10:8443.
  4. Creates the administrator admin, with a password made for this Edge Server only. There is no shared default password.

On the Edge Server computer, open the Growbud desktop app. It signs in as admin with a local key. No password is needed. To use a browser or a phone, open Settings, then Edge Server:

  • Set administrator password sets the password for admin. Then sign in at the address above from any computer.
  • Connect a phone shows a QR code. Scan it with the Growbud app. The phone signs in without a password.
  • Reset administrator password, for a lost password, writes a one-time password to a note on the desktop. It asks for the password of the computer.

Without the desktop app, the installer writes the one-time password to /opt/growbud-edge/ADMIN-CREDENTIALS.txt. Sign in with it in a browser and set a new password. Then delete the file. A lost password: sudo growbud-edge-reset-admin, or on macOS docker compose run --rm init reset-admin in the install folder.

For Windows, download the bundle from the download page and run install.ps1. The README in the bundle gives the steps.

3. Make an API token

On the Edge Server computer, make a token for the administrator. The administrator's email is admin@growbud.local, or the address you gave the installer with --admin-email. Add --scope control to let the token switch equipment:

cd /opt/growbud-edge
sudo docker compose exec outlets node /app/edge-outlets.mjs token create \
  --email admin@growbud.local --name "My integration" --scope control

The command shows the token one time only. See Authentication for read-only tokens, expiry and revoking.

4. Add your devices

The Edge Server has its own account and its own LoRaWAN network. It does not need a Growbud Cloud account. Get devices onto it in one of three ways.

Move devices from Growbud Cloud. A one-time move of sensors, Controllers and outlets, with their names, zones and settings. The devices keep their LoRaWAN keys, so you do not pair them again. You must be an administrator on Growbud Cloud and on the Edge Server. On the Edge Server computer, in the Growbud desktop app:

  1. Open Settings, then Edge Server.
  2. In Move devices, select To this Edge Server.
  3. Enter your Growbud Cloud email and password, then select Sign in to Growbud Cloud. The Edge Server does not keep this sign-in.
  4. Select the devices, then select Move to this Edge Server.
  5. Point each LoRaWAN gateway at the Edge Server: UDP port 1700 on its address.

Growbud Cloud turns off its copy of each device and keeps its history. To move devices back, select Back to Growbud Cloud.

Link devices to the Edge Server directly. No Growbud Cloud account is needed.

  • Sensors: connect a phone to the Edge Server, then link the sensor in the Growbud mobile app over Bluetooth. The Edge Server registers it on its own network. The sensor needs firmware 5.0.0 or later. A sensor that was on another network leaves that network. See Link a sensor and update its firmware. The desktop app does not link a sensor to an Edge Server.
  • Outlets: connect a phone to the Edge Server (Settings, Edge Server, Connect a phone), then add the outlet in the Growbud mobile app over Bluetooth.

Link the Edge Server to Growbud Cloud. The Edge Server keeps a copy of your Growbud Cloud organization and stays in sync with it. One side is primary. Devices you add in Growbud Cloud come to the Edge Server at the next sync.

  1. On the Edge Server, open Settings, then Edge Server. Select Get pairing code. The code is valid for 10 minutes.
  2. In Growbud web, open Settings, then Edge Server. Select Add Edge Server.
  3. Enter the Edge Server address, for example https://192.0.2.10:8443, and the pairing code.

Growbud Cloud stays primary until the first sync ends. Then the Edge Server becomes primary. While Growbud Cloud is primary, Write API calls get 409 managed_elsewhere.

5. Send your first call

With at least one outlet or Controller on the Edge Server:

export TOKEN=eyJ...
export EDGE=https://192.0.2.10:8443

# Your outlets
curl -sk -H "Authorization: Bearer $TOKEN" "$EDGE/sensing/v1/outlets"

# Switch an outlet on, and wait up to 30 s for it to confirm
curl -sk -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"on": true}' "$EDGE/control/v1/outlets/a84041fffe000001/switch?wait=30"

The Edge Server uses a self-signed certificate. curl -k accepts it.

Use it from outside your site

The Edge Server has no address on the internet. To open it from another network, use Tailscale or your own VPN. See Reach an Edge Server from another network.

Upgrade

On an Edge Server computer with the Growbud desktop app, open Settings, then Edge Server. The Edge Server software card shows the installed version and the latest version. Select Update. The app asks for the password of the computer, then runs the installer. Its output goes to /opt/growbud-edge/update.log.

From a terminal, run the install command again on the Edge Server computer:

curl -fsSL https://growbud.io/edge/install.sh | sudo bash

On a Linux computer, sudo growbud-edge-update does the same.

The installer:

  1. Downloads the latest release and checks its SHA-256 and signature.
  2. Saves both databases and the settings file (.env) in /opt/growbud-edge/backups/. If the backup fails, it stops and changes nothing.
  3. Keeps your settings, data, devices and API tokens.
  4. Starts the new version and updates the database.

Outlets and Controllers stop for a short time while the Edge Server restarts. They do not have to join again.

To see the version that runs now:

cat /opt/growbud-edge/VERSION

To go back to the previous version, use the backup. See the README in /opt/growbud-edge, section 8. Data that the Edge Server wrote after the upgrade is lost.

Next