This page View Markdown Open in ChatGPT Open in Claude

Deploy API Maker¶

Install another version of API Maker on every server of the cluster, from Operations → Upgrade/Downgrade Engine in the admin panel. This page upgrades API Maker itself. To deploy your APIs, use a Git pull : see Git.

In short

Pick a version from npm, upload a release file, or let your pipeline call a webhook.
Every server installs it and switches over without losing a request.
Going back to an older version works the same way.

Upgrade/Downgrade Engine : the version that runs, and two ways to deploy another one — The version that runs now.
Deploy another version : from npm, or a file you upload.

Upgrade API Maker on Every Server from One Page, Safely12 chapters and the transcript

Three ways¶

Deploy from NPM: pick a published version and click Deploy. Every server downloads the package of its own machine (@sava-info-systems/api-maker-engine-linux-x64 or -linux-arm64) from the npm registry and checks its SHA-512 before anything is installed. A cluster of x64 and arm64 servers is upgraded in one go.
Upload a package: select the .tgz of a version (the npm package of one machine), or the .tar.gz of a release, up to 512 MB, and click Upload. The page sends it in pieces of 4 MB, up to 6 at a time, so a slow connection or a package of more than 100 MB is no problem, and says how fast it goes and how long it takes. A piece whose request fails on the way is sent again, and an upload which stopped goes on where it stopped : click Upload again with the same file. The pieces wait in the Redis of the installation for an hour, every server reads the package from there, and each one checks the SHA-256 of every piece before using it. A server of another machine refuses it.
A webhook : your pipeline calls an address with the version to install.

Every way of installing¶

The page upgrades every Linux server of API Maker v4, whatever installed it and whatever keeps it running :

Installed with	Runs from	Kept running by
API Maker Launchpad (Cloud mode)	`~/projects/sava_api_maker`	systemd, PM2 or Docker
The install script of earlier releases	`~/projects/api_maker/current`	systemd
npm (`npm install -g @sava-info-systems/api-maker-engine`)	the package of its machine in `node_modules`	the `api-maker` command
A folder of your own	the folder of `api_maker_be`	systemd, PM2, Docker, `nohup`, a terminal…

What happens on each server¶

The package is downloaded (its SHA-512 checked) or received (its SHA-256 checked).
It is unpacked next to the running version : into releases/<version> on a server of the install script, into .am-deploy/<version>.new of the folder of the program for every other one.
Its program is checked : built for this machine, and it starts (api_maker_be --version).
The new version takes the place of the running one.
- Installed by the install script and run by systemd : the current link moves to it, all at once, and systemd starts API Maker on it. A watchdog outside of API Maker waits for it to answer; when it does not answer within two and a half minutes, current goes back to the version which ran before and that one is started again. The 3 newest versions are kept, the older ones removed.
- Every other installation : API Maker stops as it does for a restart (the requests in flight finish, the sandboxes stop), then each file and folder of the package takes the place of the one of the same name. The ones it replaces go to .am-deploy/previous. Then the process starts again as the new version : the same process, so systemd, PM2, Docker or the api-maker command keep it as theirs. Its listening sockets go to the new version with it (port 38246, and the ports of the built-in web server) : the clients that connect meanwhile wait a moment in the queue of the kernel, none is refused. The new version watches its own start : when it can not start (an error, three starts which never served, five minutes without serving), the files of the version which ran before go back to their place and that version starts again, in the same process.
- Installed by API Maker Launchpad (Cloud mode) : as every other installation, and also :
  - With the built-in web server of API Maker, the admin panel of the new version is served at once, from its package : nothing else to prepare.
  - The admin panel the reverse proxy of the server serves (Caddy, Ferron or Pingap, from ~/projects/sava_api_maker_admin_panel) is made for the new version while the server deploys, with the address of the API it called. It takes the place of the one served when the new version starts, so the page reloads on the admin panel of the new version.
  - The record Launchpad keeps in the folder (.amcr-install.json) says the new version. The next deployment of the environment from Launchpad keeps it : the environment asks for that version from then on, and nothing of API Maker is installed again.
  - A version which goes back takes its admin panel and the record back with it.
The server which took the request from the page restarts last, once every server has answered, so the page gets the result of each server.
.env, license.txt, uploads/, node_modules/, the logs and every other file of yours in the folder stay where they are : a package only replaces the files it is made of.
The page shows a card per server and the live progress of each stage, then waits until every server answers on the new version and reloads.
A server which fails keeps the version it runs, and the page says why : deploy again once the cause is gone. A version which went back says why in the log of API Maker ([DEPLOY]).

Upgrade or downgrade by API¶

Upgrade or Downgrade API Maker From Your Pipeline With One Call10 chapters and the transcript

An engine webhook lets a pipeline install a version without opening the panel : a release job which upgrades the staging server, a rollback with one call. The section Upgrade or downgrade by API of the page makes them.

A webhook is an address, an access token and a secret. The three are random until you change them. The secret is kept encrypted and can not be read back : copy it when you create the webhook, or replace it later.
It belongs to this installation. It is not part of git : no commit writes it, no pull brings it, so a repository shared with another environment gives nobody the power to change its engine.
Allowed IP : when you list addresses, only those callers are answered. Otherwise any caller with the token and the secret is.
Allow downgrades : switched off, a call for a version older than the one which runs is refused.
Only the administrator of the account makes and sees webhooks, as with the page itself.

Install a version¶

curl -X POST 'https://<your server>/api/sites/engine-update/<user path>/<hook url>' \
  -H 'content-type: application/json' \
  -d '{"token":"<access token>","secret":"<secret>","version":"4.1.0"}'

Field	What it is
`token`, `secret`	The access token and the secret of the webhook.
`version`	An exact version of npm (older ones too), or `latest`.
`dryRun`	`true` checks the credentials, the address, the version and the direction, and installs nothing.

It answers at once, because a deployment takes longer than most proxies wait :

{
  "success": true,
  "data": {
    "deployId": "1793700000000-3f2a9c1e",
    "state": "RUNNING",
    "version": "4.1.0",
    "from": "4.0.0",
    "direction": "UPGRADE",
    "message": "Installing 4.1.0 on 2 server(s)."
  }
}

A GET with the same fields in the query works too, for a tool which can only open an address. The body of a POST stays out of the logs of proxies : prefer it.

Ask how it goes¶

curl -X POST 'https://<your server>/api/sites/engine-update/<user path>/<hook url>/status' \
  -H 'content-type: application/json' \
  -d '{"token":"<access token>","secret":"<secret>","deployId":"<deployId of the answer>"}'

`state`	What it means
`RUNNING`	The servers download and install the version.
`RESTARTING`	Every server has it, and they restart on it. The call itself may find nobody for a moment : ask again.
`DONE`	Every server answers on the new version.
`FAILED`	It stopped, and `message` says why. A server which does not start on the new version goes back to the one it ran.
`UNCHANGED`	Every server ran that version already : nothing was done.
`CHECKED`	A `dryRun` : nothing was installed.

The answer also lists servers, with the version each one runs. The section of the page shows a ready step for a pipeline, with the address and the token of the webhook filled in.

What the page shows¶

Open a webhook to see how to call it, and its last 50 calls with the address each came from : refused ones too, so a wrong secret or an address which is not allowed is seen. One deployment runs at a time : a call during a run is refused and says so.

Good to know¶

The folder of the program has to be writable by the user API Maker runs as.
A server whose program is in a Docker image (not in a folder mounted into its container) keeps the new version as long as its container lasts : a container made again from the image runs the version of the image.
An npm installation keeps its api-maker command as it is : npm install -g @sava-info-systems/api-maker-engine later brings both to the same version.
API Maker Launchpad : the admin panel served by the gateway of an environment on a server of its own (the Load balanced architecture) is out of reach of the API Maker servers. It shows the version it showed until the environment is deployed from Launchpad, which then gives it the admin panel of the version the servers run. The Full Docker installation needs one deployment from a Launchpad of November 2026 or newer first : its container then reaches the admin panel of the reverse proxy. A version installed from an uploaded package is not the package of npm : Launchpad keeps it only when you choose that version in the settings of the environment. A server of 4.1.0 or older does not do this yet : its first upgrade to a newer version is best done from Launchpad.
Local Run (API Maker on your computer) : change the version from API Maker Launchpad.
Servers of 4.0.0-beta.11 and older upgrade from this page only when the install script laid them out and systemd runs them : upgrade any other one once by hand to a newer version, then the page upgrades it.
macOS and Windows are machines to develop on : upgrade them with npm or API Maker Launchpad.
A server run from the sources of API Maker (a build of cargo) is upgraded by building its sources.
Versions of the Node.js edition (v1 to v3) are not deployed from here : Launchpad moves a server to v4, see Upgrade from v3.
A deployment waits up to 20 minutes for the servers to finish.
A cluster with a server of a version before 4.1.0 reads an uploaded package another way : the page says which server, before anything is installed. Deploy from npm, or upgrade that server first.
If the WebSocket connection of the page is down, the deployment keeps running and the page reports the result when it ends.