Install Nucleus

Progress checklist

• Prepare the core completed (SSH works)
• Core certs copied to the NUC
• Java / Python packages installed
• Nucleus installed and HEALTHY

You install NucleusNucleus
Greengrass Nucleus — the edge runtime on the core device. Installs components, talks to AWS, and hosts the local client-device stack. with manual provisioning on the NUCNUC
Intel NUC6CAY — compact x86 PC used as the Greengrass core in this lab (spare unit on hand; any quiet Ubuntu 24.04 x86 host works). — every cloud resource already exists from Identities, and the host OS is ready from Prepare the core.

Official path: Install with manual resource provisioning (--init-config + config.yaml, not interactive prompts).

What moves where:

Workstationhas AWS CLI

core certswalkthrough.env

→→

NUC · nuc-gg-edgeno AWS CLI

/greengrass/v2/certs/

install on the NUC

OpenJDK 21 · Python 3.12

→

nucleus zip + config.yaml--init-config

→

greengrass.serviceNucleus 2.18.x

Nucleus online

↔

AWS IoT Core

←

Workstationget-core-device

• Workstation only ships certs + config over SSH.
• NUC runs the install; no AWS CLI on it.
• Nucleus ↔ IoT Core over mTLS.
• Verify HEALTHY with get-core-device.

Steps on this page:

1. 1Copy core certsworkstation
2. 2Host packagesNUC
3. 3Place certificatesNUC
4. 4Download installerNUC
5. 5Endpoints + config.yamlNUC
6. 6Install (manual provision)NUC
7. 7Verify HEALTHYNUC + workstation

Certs ship from the workstation; the install runs on the NUC. The NUC never needs the AWS CLI — only the workstation does.

1. Copy core certificates to the NUC

From the workstation (repo root, after Identities):

set -a && source config/walkthrough.env && set +a
ssh "${NUC_USER}@${NUC_HOST}" 'mkdir -p ~/gg-edge-core-certs'
scp "$CORE_CERTS_DIR/device.pem.crt" \
    "$CORE_CERTS_DIR/private.pem.key" \
    "$CORE_CERTS_DIR/AmazonRootCA1.pem" \
    "${NUC_USER}@${NUC_HOST}:~/gg-edge-core-certs/"

device.pem.crt        100%
private.pem.key      100%
AmazonRootCA1.pem    100%

2. Host packages (on the NUC)

SSH in, then install Java for Nucleus (AWS requires 8+; this lab uses OpenJDK 21) and Ubuntu’s Python 3.12 for closed-loop components (awsiotsdk). Same default interpreter as the workstation — no deadsnakes PPA.

SSH to the NUC

ssh "${NUC_USER}@${NUC_HOST}"

… login on the NUC …

Install OpenJDK and Python

sudo apt-get update
sudo apt-get install -y openjdk-21-jdk-headless python3 python3-pip curl unzip
java -version
python3 --version

openjdk version "21.0.12.1" 2026-08-18
OpenJDK Runtime Environment (build 21.0.12.1+1-1-24.04.4-Ubuntu)
OpenJDK 64-Bit Server VM (build 21.0.12.1+1-1-24.04.4-Ubuntu, mixed mode, sharing)
Python 3.12.3

Install AWS IoT Device SDK for Python (IPC)

Loop components import awsiot.greengrasscoreipc. Install system-wide so ggc_user can import it (Ubuntu 24.04 needs --break-system-packages for PEP 668):

sudo python3 -m pip install --break-system-packages awsiotsdk
python3 -c "import awsiot.greengrasscoreipc; print('ok')"

… Successfully installed awsiotsdk-…
ok

See Linux device setup and interprocess communication in the AWS docs. The installer can create ggc_user / ggc_group when you pass --component-default-user.

3. Place certificates (on the NUC)

sudo mkdir -p /greengrass/v2/certs
sudo chmod 755 /greengrass
sudo cp ~/gg-edge-core-certs/device.pem.crt \
        ~/gg-edge-core-certs/private.pem.key \
        ~/gg-edge-core-certs/AmazonRootCA1.pem \
        /greengrass/v2/certs/
sudo chmod 644 /greengrass/v2/certs/device.pem.crt /greengrass/v2/certs/AmazonRootCA1.pem
sudo chmod 600 /greengrass/v2/certs/private.pem.key

(no output)

4. Download the installer (on the NUC)

curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip \
  -o /tmp/greengrass-nucleus-latest.zip
rm -rf /tmp/GreengrassInstaller
unzip -o /tmp/greengrass-nucleus-latest.zip -d /tmp/GreengrassInstaller
java -jar /tmp/GreengrassInstaller/lib/Greengrass.jar --version

Archive:  /tmp/greengrass-nucleus-latest.zip
  …
AWS Greengrass v2.18.3

Record that version — you need it in config.yaml next. Client devicesClient devices
Greengrass client device — an IoT Thing (here the ESP32-S3) that discovers a core and uses local MQTT. It does not run Nucleus. need Nucleus 2.2.0+; this evidence pass used 2.18.3.

5. Endpoints and config.yaml

Look up credentials endpoint

On the workstation (has AWS CLI); keep your data endpoint from walkthrough.env:

aws iot describe-endpoint --endpoint-type iot:CredentialProvider \
  --query endpointAddress --output text

example123abc.credentials.iot.ap-southeast-2.amazonaws.com

Write config.yaml on the NUC

Create /tmp/GreengrassInstaller/config.yaml (use your real endpoints and thing name — placeholders below):

cat >/tmp/GreengrassInstaller/config.yaml <<'EOF'
---
system:
  certificateFilePath: "/greengrass/v2/certs/device.pem.crt"
  privateKeyPath: "/greengrass/v2/certs/private.pem.key"
  rootCaPath: "/greengrass/v2/certs/AmazonRootCA1.pem"
  rootpath: "/greengrass/v2"
  thingName: "gg-edge-wt-dev-core"
services:
  aws.greengrass.Nucleus:
    componentType: "NUCLEUS"
    version: "2.18.3"
    configuration:
      awsRegion: "ap-southeast-2"
      iotRoleAlias: "gg-edge-wt-dev-token-alias"
      iotDataEndpoint: "example123abc-ats.iot.ap-southeast-2.amazonaws.com"
      iotCredEndpoint: "example123abc.credentials.iot.ap-southeast-2.amazonaws.com"
EOF

(no output)

Replace version with the java -jar … --version value, and both endpoints with your account’s values from walkthrough.env / the CredentialProvider lookup. The role alias is the token exchangetoken exchange
IoT role alias + IAM role — lets Nucleus exchange its device certificate for temporary AWS credentials on the core. alias from the cloud page.

6. Install with manual provisioning

sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
  -jar /tmp/GreengrassInstaller/lib/Greengrass.jar \
  --init-config /tmp/GreengrassInstaller/config.yaml \
  --component-default-user ggc_user:ggc_group \
  --setup-system-service true

Creating user ggc_user
ggc_user created
Creating group ggc_group
ggc_group created
Added ggc_user to ggc_group
Successfully set up Nucleus as a system service

Note

--deploy-dev-tools only works with --provision true. Manual install does not ship greengrass-cligreengrass-cli
Greengrass CLI — local tool under /greengrass/v2/bin/greengrass-cli for listing components and creating local deployments on the core.. Deploy aws.greengrass.Cli on Loop component when you need local tooling (see also Greengrass CLI).

7. Verify

Check systemd and effective config (NUC)

sudo systemctl status greengrass.service --no-pager
sudo grep -E 'thingName|version:' /greengrass/v2/config/effectiveConfig.yaml | head -10

● greengrass.service - Greengrass Core
     Active: active (running) …
…
  thingName: "gg-edge-wt-dev-core"
    version: "2.18.3"

Confirm IoT Core connect in logs (NUC)

sudo grep 'Successfully connected to AWS IoT Core' /greengrass/v2/logs/greengrass.log | tail -1

… Successfully connected to AWS IoT Core. {clientId=gg-edge-wt-dev-core, …}

List HEALTHY cores (workstation)

aws greengrassv2 list-core-devices --status HEALTHY

{
    "coreDevices": [
        {
            "coreDeviceThingName": "gg-edge-wt-dev-core",
            "status": "HEALTHY",
            "platform": "linux",
            "architecture": "amd64",
            …
        }
    ]
}

Get this core device (workstation)

aws greengrassv2 get-core-device --core-device-thing-name "$CORE_THING_NAME"

{
    "coreDeviceThingName": "gg-edge-wt-dev-core",
    "coreVersion": "2.18.3",
    "status": "HEALTHY",
    "platform": "linux",
    "architecture": "amd64",
    …
}

Next: Local MQTT stack.