Receiving transient alerts (NASA GCN)

Your installation can listen to NASA's General Coordinates Network (GCN), the stream over which space observatories announce transient events — gamma-ray bursts from Swift and SVOM, X-ray transients from Einstein Probe. Alerts arrive as database rows within seconds of the satellite's downlink and feed the Target-of-Opportunity features as they land in upcoming releases.

The service is optional. If you skipped it during arcsecond setup, re-run:

arcsecond setup --with-alerts
arcsecond start

Network prerequisites

The consumer opens outbound, encrypted connections to five names, and listens on nothing:

Name	Port	What for
auth.gcn.nasa.gov	443	signing in
kafka.gcn.nasa.gov	9092	the first contact, which hands out the three names below
kafka1.gcn.nasa.gov, kafka2.gcn.nasa.gov, kafka3.gcn.nasa.gov	9092	the alerts themselves

That is the complete list to hand your IT department if the observatory network is restricted. Note the port: 9092 is not a web port, and a network that only lets web traffic out blocks it. It cannot go through a web proxy.

Get your GCN credentials (about two minutes, once per installation)

GCN identifies each consumer individually — there are no shared Arcsecond credentials. Your installation gets its own identity, its own quota, and its own revocation switch.

1. Sign in (or create an account) at https://gcn.nasa.gov/quickstart.
2. Follow the Start streaming GCN Notices flow to create client credentials. When asked for a scope, select gcn.nasa.gov/kafka-public-consumer.
3. Copy the client ID and client secret it shows you.

Configure

Open the .env file in your Arcsecond folder and paste the two values:

GCN_CONSUMER_CLIENT_ID=your-client-id
GCN_CONSUMER_CLIENT_SECRET=your-client-secret

Then recreate just the alerts service, so it reads them:

arcsecond restart alerts

Verify

arcsecond logs alerts -f

Within about a minute you should see:

GCN consumer started (group.id=io.arcsecond.local.…, 32 topics).
GCN connection established (heartbeat received).

The heartbeat line repeats at most once per hour — that is the liveness signal. Real alerts are rare; a quiet log between heartbeats is normal and correct. Ctrl-C leaves the log; the service keeps running.

Troubleshooting

Symptom	Meaning and next action
arcsecond status does not list alerts	The service is not in your docker-compose.yml. Run arcsecond setup --with-alerts, then arcsecond start.
Log says GCN credentials not configured — transient alerts disabled	The two .env keys are empty. Follow Configure above, then arcsecond restart alerts.
Repeated authentication/SASL errors in the log	GCN rejected your credentials. Re-create them at https://gcn.nasa.gov/quickstart (check the scope is gcn.nasa.gov/kafka-public-consumer), update .env, then arcsecond restart alerts.
Connected, but no heartbeat line	An outbound connection to the names above is likely blocked, most often port 9092. Test from the host: curl -sI https://auth.gcn.nasa.gov, then curl -v telnet://kafka.gcn.nasa.gov:9092 (it must say Connected).
Log says Installation not initialized	The backend has not completed its first boot yet. Run arcsecond start, which waits for the backend to be ready, then arcsecond restart alerts.

Turning it off

Remove the service from your installation; the next start takes its container down:

arcsecond setup --without-alerts
arcsecond start

Your GCN credentials stay in .env; delete the two lines (and revoke the credential on gcn.nasa.gov) if you want them gone for good. arcsecond setup --with-alerts brings the service back at any time.