# Install API Maker on a Server
> Put API Maker on your own servers - deploy a whole architecture from your computer with API Maker Local Run, or set up one Ubuntu server with the install script. The reference architectures, the downloads, the installer flags, a second server and the manual setup.
Source: https://docs.apimaker.dev/v1/docs/getting-started/install-on-server.html
API Maker runs on your own servers, at any provider : a VPS, a dedicated machine or a virtual machine in your data centre. There are two ways to set it up, and both produce the same installation : API Maker run by PM2, its MongoDB and Redis in Docker, and a reverse proxy with HTTPS in front.
Recommended⌘API Maker Local RunThe desktop app for macOS, Windows and Linux. Design the architecture on a diagram and deploy it from your computer over SSH, from one server to a load balanced cluster with replicated databases. The same app runs API Maker on your computer.
$The install scriptOne command in the terminal of a fresh Ubuntu server installs everything on that server and prints the admin panel URL. Run it again on more servers to build a cluster.
## Deploy with API Maker Local Run
**API Maker Local Run** is the one application for every place API Maker runs. Its **Local** mode runs API Maker and its databases on your computer for development ([Run on your computer](/v1/docs/getting-started/local-run.html)). Its **Cloud** mode takes servers you rent anywhere and turns them into a production environment : add a server with its SSH sign-in, choose a layout, and deploy. Everything happens over SSH from your computer, with no agent on the servers and no third party service in between.
| | |
|---|---|
| Sets up | API Maker run by PM2, its MongoDB and Redis, a reverse proxy (Caddy, Ferron or Pingap) with Let's Encrypt certificates renewed on their own, and the firewall. |
| Your databases | MongoDB replica sets, PostgreSQL with streaming replicas, MySQL and Percona with replicas, MariaDB replicas or a Galera cluster, SQL Server, Oracle and TiDB. Passwords are rotated and databases move between servers with their data. |
| Environments | Production, staging, development… each one with its own servers, version and license key, in one project. |
| Day two | New versions deployed with rolling updates behind the load balancer, live logs and health of every server, a full uninstall. |
| Servers | Ubuntu 24.04 LTS, x86-64 or ARM64 ; 1 core, 900 MB of memory and 10 GB of disk at least (4 GB and 20 GB recommended). Sign in as root or a sudo user, with a password, a key or your SSH agent. |
| Security | SSH host keys are pinned on first connection ; credentials are stored encrypted on your computer, with the key in the keychain of the operating system. |
### Download
⌘macOS
13 Ventura or later · Apple silicon and Intel
UniversalDisk image .dmgZip .zip
Open the .dmg and drag the app to Applications.
⊞Windows
Windows 10 and 11
x64Installer .exePortable .zip
ARM64Installer .exePortable .zip
Installs for your user, no administrator rights needed.
>_Linux
Ubuntu 22.04+, Debian 12+, Fedora 39+
x64Debian, Ubuntu .debAny distro .tar.gz
ARM64Debian, Ubuntu .debAny distro .tar.gz
Needs GTK 3 and WebKitGTK 4.1 ; the .deb installs them.
Version 1.0.0 · the SHA-256 checksum of every file and the install steps are on apimaker.dev/download
Open the app, switch to the **Cloud** tab, add your servers, create a project and an environment, then press **Deploy**. Local mode needs Docker on your computer ; Cloud mode only needs SSH access to your servers.
## Choose an architecture { #architectures }
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 Local Run deploys the everyday ones straight from its diagram :
| Architecture | What it is | In API Maker Local Run |
|---|---|---|
| [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.
## 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 → PM2 (API Maker backend, WebSocket, admin panel) → Docker (MongoDB, Redis, sandboxes) → your databases
| | |
|---|---|
| Server | Ubuntu 22.04, 24.04 or 26.04 (20.04 works too), root user, 20 GB of disk or more, 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/v1/install.sh > install.sh && bash install.sh --default --version=latest --license_key=YOUR_KEY` |
| Installs | Node.js 22 (with Volta) and PM2, Docker, MongoDB and Redis as containers, the Oracle client, Caddy for HTTPS, and API Maker itself in `~/projects/sava_api_maker`. |
| Writes | `~/config/.env` (the [configuration](/v1/docs/am-resources/api-maker-configurations.html)), `~/config/Caddyfile`, the license file. Existing files are backed up and reused. |
| Prints | The admin panel URL, the API and WebSocket URLs, the default users, the start and stop commands. |
### 1. Run the installer
```sh
curl -fsSL https://apimaker.dev/v1/install.sh > install.sh && bash install.sh --default --version=latest --license_key=YOUR_KEY
```
| 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=3.3.0`. Run it again to upgrade or to reinstall. |
| `--default` | No questions : Caddy without SSL on the IP of the server, MongoDB and Redis in Docker with generated passwords, a primary server. Leave it out to answer the questions below. |
| `--mongoVersion=8.0.10` | The MongoDB image to run (`8.0.10` by default). |
### 2. What it asks without `--default`
1. **Do you want to install caddy server?** Caddy is the reverse proxy in front of API Maker : it serves the admin panel and the APIs on port 80, and HTTPS when you say yes to **Do you want to install SSL?** and give the host names of the API, the WebSocket server and the admin panel.
2. **Are you setting up server for QA | UAT | PROD environment?**
3. The swap size, when the server has less than the minimum.
4. **Primary** or **secondary** server : the first server of a cluster or another one attached to it.
5. On a primary server : the MongoDB and Redis to use (the containers it creates, or your own connection strings), and the API Maker settings (ports, passwords).
### 3. What it does
1. Checks the server : Ubuntu version, root, disk, AVX, glibc, swap.
2. Downloads API Maker from npm into `~/projects/sava_api_maker` and installs its dependencies. An earlier `node_modules` is reused when the version allows it.
3. Installs Docker if needed, then starts **MongoDB** (container `mongodb_api_maker`, a one node replica set, data in `~/docker-data`) and **Redis** (container `redis_api_maker`).
4. Installs the Oracle Instant Client and the D2 diagram library.
5. Writes `~/config/.env` : the connection strings, `passJWT`, `passDBEncryptDecrypt`, the ports (`38246` for the API, `38245` for the WebSocket server) and `BE_HOST_PORT`, then copies the values into the admin panel.
6. Starts the backend and the admin panel with **PM2**, and registers PM2 to start them again after a reboot.
7. Installs **Caddy**, writes `~/config/Caddyfile` and starts it : the admin panel on port 80 (or 443 with SSL), `/api` and the WebSocket server proxied to API Maker.
8. Registers the MAC address of the server for the license, and prints the summary.
```text title="The end of the output"
———— # Important URLs ————
Frontend Admin Panel http://
Backend APIs http:///api
Backend WebSocket endpoint ws://:8081
———— # Default User Credentials ————
root@root.com R00t_123456789
admin@admin.com Admin_123456789
———— # Commands to start/stop API Maker processes ————
[START] : …
[STOP] : …
```
### 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](/v1/docs/getting-started/first-api.html) : try its APIs, then add your own [instance](/v1/docs/apis-all/overview.html#instances).
### A second server
- Run the same command on the next server and answer **secondary** : it installs API Maker only, and points it to the MongoDB and Redis of the primary server.
- The installer then prints the two `reverse_proxy` lines to add to the Caddyfile of the primary server (`127.0.0.1:38246` and `:38245` become a list of servers), and the commands to restart Caddy. Every server of the cluster shows on the [Server Node Configurations](/v1/docs/dashboard/node-dashboard.html) dashboard, and [Deploy API Maker](/v1/docs/features/deploy-api-maker.html) upgrades them all.
## By hand
The pieces are ordinary : a Node.js process (`node main.js` in the package, or PM2), MongoDB as a replica set, Redis, and any reverse proxy for TLS. The [configuration](/v1/docs/am-resources/api-maker-configurations.html) page lists every setting of `.env` ; the MongoDB connection string goes in `am__mongo_db_connection`, Redis in `am__redisInternal` and `am__redisExternal`. The blocks below set up each piece the way the installer does, on Ubuntu as root.
??? example "Node.js 22 with NVM"
API Maker needs **Node.js 22 or newer** (`engines` of its package).
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 22
nvm alias default 22
node --version
```
??? example "Docker with Docker Compose"
From the official apt repository of Docker, the commands the installer runs. They work on Ubuntu 20.04 to 26.04 ; a release too new for Docker's repository falls back to the one of 24.04 (`noble`).
```bash
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do apt-get remove -y $pkg; done
apt-get update
apt-get install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
CODENAME=$(. /etc/os-release && echo "$VERSION_CODENAME")
curl -fsL -o /dev/null "https://download.docker.com/linux/ubuntu/dists/$CODENAME/Release" || CODENAME=noble
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $CODENAME stable" > /etc/apt/sources.list.d/docker.list
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
docker compose version
```
??? example "MongoDB as a one node replica set"
API Maker needs MongoDB as a replica set : transactions only work there. A replica set with authentication needs a key file.
```bash
mkdir -p ~/config && cd ~/config
openssl rand -base64 756 > keyfile
chmod 600 keyfile && chown 999:999 keyfile
```
```yaml title="~/config/mongodb_api_maker.yml"
services:
am_mongodb:
image: mongo:8.0.10
restart: always
container_name: mongodb_api_maker
command: [ "--replSet", "rs0", "--bind_ip_all", "--port", "27017", "--keyFile", "/opt/keyfile" ]
ports:
- 38248:27017
environment:
- MONGO_INITDB_ROOT_USERNAME=api_maker_user # 👈 your user
- MONGO_INITDB_ROOT_PASSWORD=CHANGE_ME # 👈 your password
- MONGO_REPLICA_SET_NAME=rs0
healthcheck:
# Starts the replica set on the first run.
test: echo "try { rs.status() } catch (err) { rs.initiate({_id:'rs0',members:[{_id:0,host:'127.0.0.1:27017'}]}) }" | mongosh -u "api_maker_user" -p "CHANGE_ME" --port 27017 --quiet
interval: 10s
timeout: 30s
start_period: 5s
retries: 10
volumes:
- ~/docker-data/mongodb_api_maker/data:/data/db
- ~/docker-data/mongodb_api_maker/configdb:/data/configdb
- ./keyfile:/opt/keyfile
```
```bash
docker compose --project-name api_maker -f ~/config/mongodb_api_maker.yml up -d
```
```text title="am__mongo_db_connection"
mongodb://api_maker_user:CHANGE_ME@127.0.0.1:38248/api_maker_db?authSource=admin&replicaSet=rs0&directConnection=true
```
MongoDB Compass, Studio 3T or any other client connects with the same string.
??? example "Redis"
```yaml title="~/config/redis_api_maker.yml"
services:
redis_api_maker:
image: 'redis:7.0.5-alpine'
restart: always
container_name: redis_api_maker
ports:
- '7479:6379'
command: redis-server --loglevel warning --requirepass CHANGE_ME # 👈 your password
volumes:
- ~/docker-data/redis_api_maker:/data
logging:
driver: "json-file"
options:
max-size: "5m"
max-file: "3"
```
```bash
docker compose --project-name api_maker -f ~/config/redis_api_maker.yml up -d
```
```text title="am__redisInternal and am__redisExternal"
{"nodes": [{port: 7479, host: "127.0.0.1", pass: "CHANGE_ME"}]}
```
## Related
- [Run on your computer](/v1/docs/getting-started/local-run.html) : API Maker Local Run in detail · [Local setup](/v1/docs/getting-started/local-setup.html) · [How it works](/v1/docs/getting-started/how-it-works.html) · [API Maker configuration](/v1/docs/am-resources/api-maker-configurations.html) · [Deployment architectures](https://apimaker.dev/architectures)
Next : your first API →
Local setup