# Deploy API Maker

> Upgrade or downgrade API Maker v4 on every server of the cluster from the admin panel, from npm, from an uploaded package or with a webhook your pipeline calls, with live progress for each server and an automatic way back.

Source: https://docs.apimaker.dev/v4/docs/features/deploy-api-maker.html

- Install another version of API Maker on every server of the cluster from the **Deploy API Maker** page of the admin panel.
- This page upgrades API Maker itself. To deploy your APIs, use a Git pull. Learn more [Git](https://docs.apimaker.dev/v4/docs/Git/git.html).

> Diagram : Deploy API Maker v4 : admin panel → Caddy → API Maker → Redis → every server installs the package of its machine (5 stages, live progress) → the new version takes the place of the running one, wait for it, reload
>
> How Deploy API Maker upgrades a cluster of API Maker v4 : the admin panel sends the chosen version, or an uploaded package, through Caddy to API Maker, which sends it through Redis to every server. Each server gets the package of its own machine from npm (its SHA-512 checked) or takes the uploaded one, unpacks it next to the running version, checks its program, moves the current link to it and is started on it by systemd; a watchdog goes back to the version which ran before when the new one does not answer. Every stage is reported live over the WebSocket. When every server is done the page waits until they answer on the new version and reloads. A server which fails keeps its version and the page says why.

- Video: [Upgrade API Maker on Every Server from One Page, Safely](https://apimaker.dev/videos/upgrade-every-server) (6 min)

## 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](https://docs.apimaker.dev/v4/docs/features/deploy-api-maker.html#upgrade-by-api) 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 |
|---|---|---|
| The [installer](https://docs.apimaker.dev/v4/docs/getting-started/install-on-server.html), or the steps [by hand](https://docs.apimaker.dev/v4/docs/getting-started/install-by-hand.html) | `~/projects/api_maker/current` | systemd |
| API Maker Launchpad (Cloud mode) | `~/projects/sava_api_maker` | systemd, PM2 or Docker |
| 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

1. The package is downloaded (its SHA-512 checked) or received (its SHA-256 checked).
2. It is unpacked next to the running version : into `releases/<version>` for the installer's layout, into
   `.am-deploy/<version>.new` of the folder of the program for every other one.
3. Its program is checked : built for this machine, and it starts (`api_maker_be --version`).
4. The new version takes the place of the running one.
    - **Installed by the installer 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. 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 :
        - 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.
5. 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

- Video: [Upgrade or Downgrade API Maker From Your Pipeline With One Call](https://apimaker.dev/videos/engine-webhooks) (6 min)

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

```bash
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 :

```json
{
  "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

```bash
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 installer 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 : the installer moves a server to v4.
- 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.
