Reference·The gatewayIndexClose
The gateway
The background gateway: its verbs, what it installs per platform, logout, automatic start and updates.
The gateway is the local server that shells attach to. The background gateway keeps it and the organism, a running Nodecode, up with no shell open.
Verbs
nodecode gateway
nodecode gateway on
nodecode gateway off
nodecode gateway restart
nodecode gateway logs --follow
| Verb | Does |
|---|---|
none, status | Prints the state: off, serving, waiting, starting, stopped, restarting, failed or unavailable. |
on | Writes the unit. Enables it. Starts it. On Linux, asks logind to keep it running after logout. |
off | Disables the unit, removes its file and stops the process. Writes gateway-off. |
restart | Restarts on the current build with the current config. Refused while the gateway is off. |
logs | Prints the last 60 log lines. |
logs --follow, logs -f | Keeps printing new lines. Command line only. |
run | Runs the gateway in the foreground. This is what the unit runs. Command line only. |
help [VERB] | Prints help. |
/gateway [on | off | restart | logs | help] does the same from a shell. A shell is the terminal UI.
For a profile, add -p NAME:
nodecode -p NAME gateway on
While it serves, the status adds the pid, the port, the uptime and the build. It says whether the gateway starts at login. It lists the standing notices of cells.
What on installs
| Platform | Installs | Unit file |
|---|---|---|
| Linux | A systemd user unit | ~/.config/systemd/user/nodecode-gateway.service |
| macOS | A LaunchAgent | ~/Library/LaunchAgents/nodecode-gateway.plist |
| Windows | Nothing | None |
Windows: no background gateway. status, on, restart and logs say so. Run nodecode serve in a terminal you keep open.
On Linux the unit folder follows XDG_CONFIG_HOME when it is set.
| Home | Unit name |
|---|---|
~/.nodecode/ | nodecode-gateway |
| A profile | nodecode-gateway-NAME |
Another NODECODE_HOME | nodecode-gateway- plus 8 hex digits of the path's hash |
The home is ~/.nodecode/ unless a profile or NODECODE_HOME names another.
| Setting | Linux | macOS |
|---|---|---|
| Runs | nodecode gateway run | The same, through a launcher |
| Restart after any exit | After 5 s | Yes, at most once per 5 s |
| Watchdog | 30 s | None |
| Stop timeout | 60 s | 60 s |
| Log | The user journal | ~/Library/Logs/nodecode/nodecode-gateway.log |
On macOS the launcher is copied once to ~/Library/Application Support/nodecode/launcher/1/nodecode.
on refuses to overwrite a unit file of that name that Nodecode did not write. off leaves such a file alone.
Shells and the gateway
| Situation | Result |
|---|---|
| A shell owns the store, then the gateway starts | The gateway waits. It takes the organism over when that shell closes. |
| The gateway serves, then a shell opens | The shell attaches. Its footer shows the gateway's port. |
/gateway off from an attached shell | The gateway stops. That shell takes the organism over. |
See The organism.
Logout
| Platform | Behaviour |
|---|---|
| Linux, linger on | The gateway starts at boot. It keeps running after logout. |
| Linux, linger off | The gateway starts at login. It stops at logout. |
| macOS | The agent starts at login. It stops at logout. launchd has no linger. |
on runs loginctl enable-linger for your account. If your system refuses, the status says so. Then run once:
sudo loginctl enable-linger $USER
Run the same command when the status says systemd has no user manager.
Automatic start
A cell is a folder of code under ~/.nodecode/cells/. Four cells turn the gateway on by themselves:
| Cell | When |
|---|---|
| Channels | A bot starts. |
| Cron | A job is scheduled, or active jobs exist at start. |
| Link | The link is on. |
| Prs | The pull request watch starts. |
Every attached shell shows a notice when this happens.
A cell does not turn the gateway on in these cases:
~/.nodecode/gateway-offexists.- The organism runs with
--ephemeral. - The platform is Windows.
gateway-off
nodecode gateway off writes the file ~/.nodecode/gateway-off.
While the file exists, no cell turns the gateway on. Bots and cron jobs then run only while a shell is open.
nodecode gateway on deletes the file.
Updates
The unit names the installer's current link. A restart runs the build installed last.
| Event | Result |
|---|---|
| The installer finishes, gateway running | The installer runs nodecode gateway restart for it. |
| The installer finishes, gateway stopped | Nothing. The next start runs the new build. |
nodecode update needs a restart | The organism restarts itself through the unit at an idle moment. |
nodecode gateway restart | Rewrites the unit first if the binary path or PATH changed. |
The installer restarts only units that Nodecode wrote. See Updates.