Documentation

Nebua Gateway

Install the Nebua Nebua Gateway to power environment gateway proxy routing and site exposure.

Nebua Nebua Gateway

The Nebua Nebua Gateway is a host-level service for Environment Gateway Proxy. It runs on the gateway host, pulls desired reverse-proxy state for one environment, renders local proxy configuration, reloads the selected proxy, and reports sync health back to NebuaCloud.

Like the Nebua cluster agent, the gateway agent should be installed on the target host. It manages host services such as Caddy, NGINX, or another reverse proxy reload command, so systemd is the right production home.

When To Use It

Install one gateway agent on each gateway host that should expose NebuaCloud environments through a managed reverse proxy.

Use a separate gateway agent per gateway host and bind it to one environment ID. This keeps routing ownership clear and avoids multiple agents writing the same proxy configuration.

What It Does

Pulls desired gateway state from NebuaCloud for a single environment
Renders Caddy or NGINX configuration on the gateway host
Runs the configured reload command after configuration changes
Reports connectivity, generated config, and sync status back to NebuaCloud
Enables Environment Gateway checks before the dashboard allows proxy routing

Current Support

The gateway agent renderer supports:

caddy
nginx

The installer also supports --provider custom for hosts where you want to provide your own reload command. Custom providers still require the NebuaCloud environment gateway provider and rendered config path to match what the agent can render.

Prerequisites

Ubuntu, Debian, or another systemd-based Linux gateway host
curl and tar
Outbound HTTPS access to NebuaCloud on port 443
Gateway token from NebuaCloud
Environment ID managed by this gateway host
Caddy, NGINX, or another reverse proxy installed on the host

The hosted installer downloads a Nebua agent bundle that already contains the Node.js runtime and compiled gateway agent code. The target host does not need Node.js, pnpm, or a monorepo checkout.

Quick Host Installation

Run the hosted installer on the target gateway host. The NebuaCloud dashboard should generate this command with the correct environment ID and token. Choose the proxy provider that the host should operate.

For Caddy:

curl -fsSL https://nebuacloud.com/install/nebua-gateway.sh | sudo bash -s -- \
  --environment-id <environment-id> \
  --token '<gateway-token>' \
  --provider caddy

For NGINX:

curl -fsSL https://nebuacloud.com/install/nebua-gateway.sh | sudo bash -s -- \
  --environment-id <environment-id> \
  --token '<gateway-token>' \
  --provider nginx

For a custom application server or reload flow:

curl -fsSL https://nebuacloud.com/install/nebua-gateway.sh | sudo bash -s -- \
  --environment-id <environment-id> \
  --token '<gateway-token>' \
  --provider custom \
  --reload-cmd 'systemctl reload my-proxy'

If you omit --provider, the installer uses auto and does not force a reload command. The running agent will use the provider returned by NebuaCloud desired state. NGINX has a built-in default reload command; Caddy and custom providers should be given a reload command when the host needs one.

The hosted bootstrap script downloads the NebuaCloud agent bundle for the selected release, runs the host installer, installs bundled Node under /usr/local/lib/nebua/bin/node, installs the runtime under /usr/local/lib/nebua/runtime, writes /etc/nebua/nebua-gateway.env, installs /etc/systemd/system/nebua-gateway.service, and starts the service.

For local development from a monorepo checkout, you can run the underlying source installer directly. Source mode requires Node.js 20 or newer and pnpm:

sudo ./nebua-gateway-install.sh \
  --environment-id <environment-id> \
  --token '<gateway-token>' \
  --provider nginx

Provider And Reload Behavior

The gateway provider is controlled by the Environment Gateway settings in NebuaCloud. The installer --provider value is a host hint and a convenience for choosing defaults.

Provider behavior:

--provider auto: no reload command is written unless NEBUA_GATEWAY_RELOAD_CMD is already set
--provider caddy: writes NEBUA_GATEWAY_PROVIDER_HINT=caddy and defaults reload to systemctl reload caddy
--provider nginx: writes NEBUA_GATEWAY_PROVIDER_HINT=nginx and defaults reload to nginx -t && (systemctl reload nginx || service nginx reload || nginx -s reload)
--provider custom: requires --reload-cmd

You can always override the reload command explicitly:

curl -fsSL https://nebuacloud.com/install/nebua-gateway.sh | sudo bash -s -- \
  --environment-id <environment-id> \
  --token '<gateway-token>' \
  --provider nginx \
  --reload-cmd 'nginx -t && systemctl reload nginx'

Environment File

The systemd unit reads configuration from /etc/nebua/nebua-gateway.env. This file is owned by root and installed with 0600 permissions.

NEBUACLOUD_API_URL=https://api.nebuacloud.com
NEBUACLOUD_TOKEN=token
GATEWAY_ENVIRONMENT_ID=123
NEBUA_GATEWAY_ENVIRONMENT_ID=123
NEBUA_GATEWAY_AGENT_ID=nebua-gateway-prod-1
NEBUA_GATEWAY_PROVIDER_HINT=nginx
NEBUA_GATEWAY_PULL_MS=30000
NEBUA_GATEWAY_RELOAD_CMD=nginx -t && (systemctl reload nginx || service nginx reload || nginx -s reload)

Common values:

NEBUACLOUD_TOKEN: authentication token for gateway pull/report requests
GATEWAY_ENVIRONMENT_ID: environment managed by this gateway host
NEBUACLOUD_API_URL: API base URL, defaults to https://api.nebuacloud.com
NEBUA_GATEWAY_AGENT_ID: stable gateway agent ID for this host
NEBUA_GATEWAY_PROVIDER_HINT: reported provider hint for this host
NEBUA_GATEWAY_PULL_MS: desired-state pull interval in milliseconds
NEBUA_GATEWAY_CONFIG_PATH: output path for generated gateway config
NEBUA_GATEWAY_CADDYFILE_PATH: legacy Caddyfile output alias
NEBUA_GATEWAY_NGINX_SITE_PATH: active NGINX include path
NEBUA_GATEWAY_RELOAD_CMD: shell command used to reload the local proxy

After changing the env file, restart the service:

sudo systemctl restart nebua-gateway

Verify Installation

sudo systemctl status nebua-gateway --no-pager
sudo journalctl -u nebua-gateway -f

Check the selected proxy service too:

sudo systemctl status caddy --no-pager
sudo systemctl status nginx --no-pager

How It Connects To Environment Gateway

When a user enables Environment Gateway Proxy in NebuaCloud, the dashboard checks whether:

a gateway is configured for the environment
the gateway agent is installed or registered
the gateway agent has reported recently
the gateway agent reports a healthy sync state

If the gateway agent is unavailable, the environment UI blocks gateway enablement and shows an unavailable state in the environment list and details view.

Generated Files

By default the gateway agent writes generated and cached state under its working tree. Production deployments should set explicit output paths for the selected provider when needed.

Common paths:

generated Caddy config via NEBUA_GATEWAY_CADDYFILE_PATH
generated NGINX config via NEBUA_GATEWAY_NGINX_SITE_PATH
cached desired-state JSON via NEBUA_GATEWAY_STATE_PATH

Updating The Nebua Gateway

To update the gateway agent, rerun the hosted installer:

curl -fsSL https://nebuacloud.com/install/nebua-gateway.sh | sudo bash -s -- \
  --environment-id <environment-id> \
  --token '<gateway-token>' \
  --provider nginx

The installer replaces /usr/local/lib/nebua/runtime, refreshes the env file, reloads systemd, and restarts nebua-gateway.service.

Troubleshooting

Missing token

If NEBUACLOUD_TOKEN is missing, the process exits immediately. Add the token to /etc/nebua/nebua-gateway.env and restart the service.

Agent shows offline

verify the gateway host can reach NEBUACLOUD_API_URL
verify the token is valid for gateway pull/report APIs
confirm nebua-gateway.service is running
inspect sudo journalctl -u nebua-gateway -n 100 --no-pager

Agent shows degraded

check the provider configured on the environment gateway
verify NEBUA_GATEWAY_RELOAD_CMD works manually on the host
inspect the generated Caddyfile or NGINX config
check the local proxy service logs

Proxy reload fails

Run the reload command directly:

sudo systemctl reload caddy
sudo nginx -t
sudo systemctl reload nginx

Then inspect the proxy logs:

sudo journalctl -u caddy -n 100 --no-pager
sudo journalctl -u nginx -n 100 --no-pager

Security Considerations

The gateway agent connects outbound only.
Store tokens only in /etc/nebua/nebua-gateway.env or your secret manager.
Keep /etc/nebua/nebua-gateway.env owned by root with 0600 permissions.
Run one gateway agent per gateway host/environment ownership boundary.