# Install API Maker on a Server

> Put API Maker v4 on your own Ubuntu server with one command - one program for the APIs, the WebSockets and the admin panel, MongoDB and Redis in Docker, Caddy with HTTPS. The flags, what it asks and does, upgrades and rollbacks, a second server, the files, and the manual setup.

Source: https://docs.apimaker.dev/v4/docs/getting-started/install-on-server.html

API Maker v4 is one program for Linux : one process serves your APIs, the WebSockets and the admin panel on every core of the server, and the code of your accounts runs in Docker sandboxes. Nothing of Node.js is installed on the server. One command sets up a fresh Ubuntu server with everything around it : MongoDB and Redis in Docker, systemd to keep API Maker running, and Caddy in front with HTTPS.

- [The install script](https://docs.apimaker.dev/v4/docs/getting-started/install-on-server.html#install-with-one-command) : (API Maker v4) · One command in the terminal of a fresh Ubuntu server installs everything on that server and prints the admin panel URL. Run it again to upgrade : a version which does not start is rolled back on its own. Run it on more servers to build a cluster.
- [API Maker Launchpad](https://docs.apimaker.dev/v4/docs/getting-started/install-on-server.html#deploy-with-api-maker-launchpad) : The desktop app for macOS, Windows and Linux : draw an architecture on a diagram, and it installs API Maker v4 on your servers over SSH. It also moves a server of API Maker v3 to v4.

## Install with one command

On a fresh Ubuntu server, one command installs everything and starts API Maker. The installer prints what it does at every step, and ends with the URLs, the default users and the commands to start and stop.

> Diagram : One server after the install script : Caddy → systemd (API Maker : APIs, WebSockets, admin panel) → Docker (MongoDB, Redis, sandboxes) → your databases
>
> What the installer sets up on one Ubuntu server : Caddy on ports 80 and 443 in front, API Maker run by systemd as the service api_maker_be (one program : the APIs and the WebSockets on port 38246, the admin panel on port 4626), MongoDB and Redis in Docker for the internal data of API Maker, sandbox containers for your code, and your own databases anywhere.

| | |
|---|---|
| Server | Ubuntu 22.04, 24.04 or 26.04, x86-64 or ARM64, the root user, systemd. 20 GB of disk or more ; on x86-64 a CPU with AVX (MongoDB needs it). 1 CPU and 1 GB of RAM run it : the installer adds swap. |
| Command | `curl -fsSL https://apimaker.dev/v4/install.sh > install.sh && bash install.sh --default --version=latest --license_key=YOUR_KEY` |
| Installs | Docker, MongoDB and Redis as containers, the Oracle Instant Client, Caddy, and API Maker itself in `~/projects/api_maker`, run by systemd as the service `api_maker_be`. |
| Writes | `~/config/.env` (the [configuration](https://docs.apimaker.dev/v4/docs/am-resources/api-maker-configurations.html)), `~/config/Caddyfile`, the license file. Each one is backed up first, and the answers of an earlier installation are its defaults. |
| Prints | The state of the services, the admin panel URL, the API and WebSocket URLs, the default users, the commands to start, stop, watch and upgrade API Maker. |

### 1. Run the installer

```sh
curl -fsSL https://apimaker.dev/v4/install.sh > install.sh && bash install.sh --default --version=latest --license_key=YOUR_KEY
```

Every question has a flag, so the installer also runs without a terminal (a cloud-init script, `curl … | bash`) : what no flag answers takes its default.

| Flag | Meaning |
|---|---|
| `--license_key=YOUR_KEY` | The license key of your account (write to [contact@apimaker.dev](mailto:contact@apimaker.dev) for one). It is written to `license.txt` and bound to the server. |
| `--version=latest` | The version of API Maker to install, or an exact one like `--version=4.0.0`. Run it again to upgrade or to reinstall. |
| `--default` | Takes the default of every question which has one : the ports, the user names, new passwords, the swap. The domains of SSL have none and are still asked. |
| `--primary`, `--secondary` | The first server of an installation, or one more server which uses its MongoDB and Redis. Asked when not given. |
| `--ip=203.0.113.10` | The public IPv4 address of the server. Found on its own and asked to confirm : some providers answer with the address of a gateway. On an upgrade without SSL, the default is the address the earlier installation confirmed. |
| `--caddy=yes` | Caddy in front of API Maker. `no` on a server whose ports 80 and 443 belong to another web server : API Maker then answers on its own ports. |
| `--ssl=no` | `yes` : HTTPS with certificates of Let's Encrypt, renewed by Caddy, on `--api_domain=`, `--ws_domain=` (the domain of the APIs when not given) and `--panel_domain=`. Each domain has to point to the server first ; `--skip_dns_check` takes it anyway. |
| `--qa_uat_prod=no` | `yes` for a QA, UAT or PROD environment of a project : `passDBEncryptDecrypt` is then asked, it is the one of the DEV server of the same git repository. |
| `--mongoVersion=8.0.10` | The MongoDB image to run. |
| `--package=<file or URL>` | A release archive to install instead of downloading one : for a server without access to npm, or a build of your own (`scripts/release/build.sh` of api_maker_be_rust). |

### 2. What it asks

Without `--default`, and for what no flag answers :

1. **Primary** or **secondary** server, and the **public IP address** of the server.
2. **Do you want to install the Caddy server?** and **Do you want to install SSL?**, then the domains of the APIs, of the WebSockets and of the admin panel.
3. **Are you setting up a server of a QA | UAT | PROD environment?**
4. The size of the swap file, when the server has less swap than memory (2 to 8 GB).
5. On a primary server : the port, user name and password of MongoDB, the port and password of Redis. On a server installed before, **Do you want to re-install MongoDB?** and **Redis?** : no keeps them, with their data.
6. The port of API Maker (`38246` : its APIs and its WebSockets) and of its admin panel (`4626`), and the three secrets `passCommunication`, `passJWT` and `passDBEncryptDecrypt` : new random ones, or the ones of the earlier installation, taken as they are.
7. On a secondary server : its name, the three secrets and the MongoDB and Redis connection strings of the primary server.

### 3. What it does

1. Checks the server : Ubuntu, root, systemd, the processor, glibc 2.35 or newer, the disk, AVX.
2. Stops API Maker when it runs, and takes it out of PM2 when PM2 ran it (an installation of the Node.js edition) : whatever else PM2 runs stays. Until the new version is in place, a failure starts the old API Maker again.
3. Installs Docker if needed, gives the network of the server [room for many connections](https://docs.apimaker.dev/v4/docs/getting-started/install-by-hand.html#network) (`/etc/sysctl.d/90-api-maker.conf`), then starts **MongoDB** (container `mongodb_api_maker`, a replica set of one member with a key of its own, data in `~/docker-data`) and **Redis** (container `redis_api_maker`).
4. Installs the Oracle Instant Client in `/opt/oracle/instantclient` : instances of Oracle need it, a failure here is only a warning.
5. Downloads API Maker for the processor of the server (the npm package `@sava-info-systems/api-maker-engine-linux-x64` or `-arm64`, read with `curl` : npm itself is not needed), checks it against the hash npm publishes, and runs it once (`api_maker_be --version`) before anything else changes. Every version has its own folder, `~/projects/api_maker/releases/<version>`, and `~/projects/api_maker/current` points to the one that runs.
6. Writes `~/config/.env` : the connection strings, the secrets, the ports, the folder of the admin panel and where the panel reaches API Maker (`BE_HOST_PORT`). The lines of the earlier `.env` it does not write itself are kept.
7. Sets API Maker up as the **systemd** service `api_maker_be`, starts it and waits until it answers. A version which does not start is rolled back to the one which ran before. systemd starts API Maker again a second after it stops, and at every boot. Its log is `~/logs/api_maker_be.txt`, rotated past 50 MB.
8. Installs **Caddy** (the release of Caddy, checked against its SHA-512), writes `~/config/Caddyfile` and runs it as the systemd service `caddy`, so it comes back after a reboot : the admin panel on port 80, the APIs on port 8080 and the WebSockets on port 8081, or each on its own domain over HTTPS.
9. Registers the MAC address of the server for the license, keeps the last three versions, and prints the summary.

**The end of the output**

```text
———— API Maker, run by systemd ————
  api_maker_be.service       active (running), enabled at boot, PID 4224, 0 restarts
  caddy.service              active (running)

———— Important URLs ————
  Admin panel                    http://<ip>
  APIs                           http://<ip>:8080
  Web sockets                    ws://<ip>:8081

———— Default users (change their passwords after the first sign in) ————
  root@root.com                  R00t_123456789
  admin@admin.com                Admin_123456789
  Before you go live             https://docs.apimaker.dev/v4/docs/security/go-live.html

———— Commands ————
  [START]      systemctl start api_maker_be
  [STOP]       systemctl stop api_maker_be
  [RESTART]    systemctl restart api_maker_be
  [STATUS]     systemctl status api_maker_be
  [LOGS]       tail -f /root/logs/api_maker_be.txt
  [UPGRADE]    bash install.sh --version=latest
```

`systemctl stop api_maker_be` stops API Maker until the next boot ; `systemctl disable --now api_maker_be` keeps it stopped after a reboot too. The installer writes its own log to `~/logs/install/`.

### 4. First sign in

- Open the admin panel URL, sign in as `admin@admin.com` and change both passwords : the root user in **Root Settings**, the admin user in its profile.
- The admin account comes with a [sample shop](https://docs.apimaker.dev/v4/docs/getting-started/first-api.html) : try its APIs, then add your own [instance](https://docs.apimaker.dev/v4/docs/apis-all/overview.html#instances).

### Upgrade and roll back

- **Upgrade** : run the same command again, with `--version=latest` or a version. The answers of the installation are the defaults, MongoDB and Redis stay, and the new version takes the place of the old one only once it has started.
- **Roll back** by hand : point `current` at a version kept in `releases`, then restart.

```bash
ls ~/projects/api_maker/releases
ln -sfn ~/projects/api_maker/releases/4.0.0 ~/projects/api_maker/current
systemctl restart api_maker_be
```

- **From the Node.js edition (v1 to v3)** : run the installer on that server and answer no to re-installing MongoDB and Redis. API Maker v4 takes the place of the service `api_maker_be` with the same MongoDB, Redis and secrets ; the uploaded files and the license file are copied, and the folder `~/projects/sava_api_maker` is left as it was. The service `api_maker_fe` goes : API Maker serves the admin panel itself. The WebSockets move to the port of the APIs : a client which reached `:38245` directly connects to `:38246` (behind Caddy, `:8081` stays what it was).

### A second server

- Run the same command on the next server and answer **secondary** : it installs API Maker only, with the MongoDB and Redis of the primary server (their connection strings and the three secrets are in `~/config/.env` there).
- The installer then prints the line to change in the Caddyfile of the primary server, so one address spreads the requests over every server : `reverse_proxy 127.0.0.1:38246 <ip of the second server>:38246`, then `systemctl restart caddy` there. Only the primary server needs to reach port `38246` of the others. Every server shows on the [Server Node Configurations](https://docs.apimaker.dev/v4/docs/logs/logs-and-dashboards.html#servers) dashboard, and the [schedulers](https://docs.apimaker.dev/v4/docs/apis-all/schedulers/user-created-schedulers-api.html) are spread over them.

### The files on the server

| Path | What it is |
|---|---|
| `~/projects/api_maker/current` | The version that runs : `api_maker_be` (the server), `am_tools` (the compilers and libraries the server starts when code is saved), `am_agent` (the program inside every sandbox), `admin-panel/`. |
| `~/projects/api_maker/releases/<version>` | The versions installed, the last three. |
| `~/projects/api_maker/uploads`, `license.txt` | Files uploaded through the APIs, the license. They stay from one version to the next. |
| `~/config/.env` | The settings of API Maker ([configuration](https://docs.apimaker.dev/v4/docs/am-resources/api-maker-configurations.html)). Backups in `~/config/bkp_env`. |
| `~/config/Caddyfile` | The sites of Caddy. Backups in `~/config/bkp_caddyfile`. |
| `~/config/api_maker/` | The environment of the service and the rotation of its log. |
| `~/config/mongodb_api_maker.yml`, `redis_api_maker.yml`, `keyfile` | MongoDB and Redis, with Docker Compose. |
| `~/docker-data` | The data of MongoDB and Redis. |
| `~/logs/api_maker_be.txt`, `~/logs/install/` | The log of API Maker, the logs of the installer. |
| `/etc/systemd/system/api_maker_be.service` | The service. Caddy : `caddy.service`, with `/etc/systemd/system/caddy.service.d/api-maker.conf`. |
| `/etc/sysctl.d/90-api-maker.conf`, `/etc/modules-load.d/api-maker.conf`, `/etc/modprobe.d/api-maker.conf` | The limits of the network and of the open files : [room for many connections](https://docs.apimaker.dev/v4/docs/getting-started/install-by-hand.html#network). |

## Choose an architecture

Start on one server and grow without changing your APIs : API Maker keeps its state in MongoDB and Redis, so adding servers is a matter of configuration, not code. The website describes [13 reference architectures](https://apimaker.dev/architectures), each with a live diagram, the size of every server and the configuration to copy. API Maker Launchpad deploys the everyday ones straight from its diagram :

| Architecture | What it is | In API Maker Launchpad |
|---|---|---|
| [All-in-one server](https://apimaker.dev/architectures/single-server) | API Maker, its MongoDB, Redis and your database on a single VPS. | The **All in one** layout. |
| [Separate database server](https://apimaker.dev/architectures/separate-database) | API Maker on one VPS, your databases on servers of their own. | The **App + data** layout. |
| [Dedicated data tier](https://apimaker.dev/architectures/dedicated-data-tier) | A stateless API server, with the MongoDB and Redis of API Maker on servers of their own. | The **Dedicated databases** layout. |
| [Environments with Git](https://apimaker.dev/architectures/environments) | DEV, QA, UAT and PROD, each with its own servers and data. | One environment per stage, in one project. |
| [Load-balanced API servers](https://apimaker.dev/architectures/load-balanced) | Several API Maker servers behind a load balancer, sharing one data tier. | The **Load balanced** layout ; add API Maker servers at any time. |
| [Real-time events across servers](https://apimaker.dev/architectures/realtime-websockets) | WebSocket clients on any server, changes made on any server. | Any layout with several API Maker servers : they share Redis. |
| [Clustered Redis and databases](https://apimaker.dev/architectures/clustered-data) | No single data node to lose. | API Maker's MongoDB as a replica set, its Redis as a cluster, your databases replicated. |
| [High availability](https://apimaker.dev/architectures/high-availability) | A spare for every tier. | Several gateways, API Maker servers and database replicas ; the floating IP is set at your provider. |

[Many projects on one platform](https://apimaker.dev/architectures/multi-project) and [a database per customer](https://apimaker.dev/architectures/multi-tenant) are features of API Maker itself and work on any of these layouts. [Multi-cloud](https://apimaker.dev/architectures/multi-cloud), [geo-routing](https://apimaker.dev/architectures/geo-routing) and the [global enterprise platform](https://apimaker.dev/architectures/global-enterprise) combine the same pieces across providers and regions : their pages show how.

## Deploy with API Maker Launchpad

The **Cloud** mode of [API Maker Launchpad](https://docs.apimaker.dev/v4/docs/getting-started/local-run.html), the desktop app, installs API Maker on servers you rent anywhere, over SSH from your computer : add the servers, pick a layout on the diagram, press **Deploy**. It also sets up your databases with their replication, a reverse proxy with HTTPS and the firewall, and deploys new versions with rolling updates. See [Cloud mode](https://docs.apimaker.dev/v4/docs/getting-started/local-run.html#cloud-mode).

## By hand

The pieces are ordinary : one program kept running by systemd, MongoDB as a replica set, Redis, and any reverse proxy for TLS. [Install by hand](https://docs.apimaker.dev/v4/docs/getting-started/install-by-hand.html) sets up each piece the way the installer does.

## Related

- [Run on your computer](https://docs.apimaker.dev/v4/docs/getting-started/local-run.html) : API Maker Launchpad in detail · [How it works](https://docs.apimaker.dev/v4/docs/getting-started/how-it-works.html) · [API Maker configuration](https://docs.apimaker.dev/v4/docs/am-resources/api-maker-configurations.html) · [Deployment architectures](https://apimaker.dev/architectures)

- [Next : your first API →](https://docs.apimaker.dev/v4/docs/getting-started/first-api.html)
- [Run on your computer](https://docs.apimaker.dev/v4/docs/getting-started/local-run.html)