# 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 systemd, its MongoDB and Redis in Docker, and a reverse proxy with HTTPS in front. - [API Maker Local Run](https://docs.apimaker.dev/v1/docs/getting-started/install-on-server.html#deploy-with-api-maker-local-run) : (Recommended) · The 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 script](https://docs.apimaker.dev/v1/docs/getting-started/install-on-server.html#install-with-one-command) : One 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](https://docs.apimaker.dev/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 systemd, its MongoDB and Redis, a reverse proxy (Caddy, Ferron or Pingap) with Let's Encrypt certificates renewed on their own, and the firewall. | | A server with PM2 | When PM2 already runs API Maker on a server, the review of the deployment asks, for that server : **Switch to systemd** (recommended) or **Keep PM2**. Whatever else PM2 runs stays. The choice can be changed later, under **Run by** in the API Maker servers of the architecture. A server without PM2 gets no question. | | 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 Universal · [Disk image **.dmg**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-macos-universal.dmg) · [Zip **.zip**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-macos-universal.zip) Open the .dmg and drag the app to Applications. **Windows** Windows 10 and 11 x64 · [Installer **.exe**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-windows-amd64-setup.exe) · [Portable **.zip**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-windows-amd64.zip) ARM64 · [Installer **.exe**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-windows-arm64-setup.exe) · [Portable **.zip**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-windows-arm64.zip) Installs for your user, no administrator rights needed. **Linux** Ubuntu 22.04+, Debian 12+, Fedora 39+ x64 · [Debian, Ubuntu **.deb**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/api-maker-local-run_1.0.0_amd64.deb) · [Any distro **.tar.gz**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-linux-amd64.tar.gz) ARM64 · [Debian, Ubuntu **.deb**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/api-maker-local-run_1.0.0_arm64.deb) · [Any distro **.tar.gz**](https://images.apimaker.dev/prod/api_maker_local/1.0.0/API-Maker-Local-Run-1.0.0-linux-arm64.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](https://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 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 → systemd (API Maker backend, WebSocket) and the files of the 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, its admin panel served by Caddy from its files, 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 (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), Docker, MongoDB and Redis as containers, the Oracle client, Caddy for HTTPS, and API Maker itself in `~/projects/sava_api_maker`, run by systemd as the service `api_maker_be`. | | Writes | `~/config/.env` (the [configuration](https://docs.apimaker.dev/v1/docs/am-resources/api-maker-configurations.html)), `~/config/Caddyfile`, the license file. Existing files are backed up and reused. The systemd service is `/etc/systemd/system/api_maker_be.service`. | | Prints | The state of the service, the admin panel URL, the API and WebSocket URLs, the default users, the commands to start, stop and watch API Maker. | ### 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` | Keeps the default ports and user names, generates the passwords and sizes the swap file, with MongoDB and Redis in Docker. A few questions are still asked : primary or secondary, the IP of the server, Caddy, SSL and whether it is a QA, UAT or PROD environment. Leave it out to answer every question 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 on port 80, the APIs on port 8080 and the WebSocket server on port 8081, or all three over 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. Say no on a server whose ports 80 and 443 are taken : the APIs then answer on port 38246, and a small service of its own, `api_maker_fe`, serves the admin panel on port 4626. 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). 6. Only on a server installed earlier, where **PM2** runs API Maker : **Do you want to switch API Maker to systemd?** Yes hands API Maker to systemd and takes it out of PM2, which keeps whatever else it runs. No keeps PM2 running it, like before. This one is asked with `--default` too. ### 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. Sets API Maker up as the **systemd** service `api_maker_be` and starts it : systemd starts it again a second after it stops, and at every boot. What API Maker prints goes to `~/logs/api_maker_be.txt`, which is rotated past 50 MB. 7. Installs **Caddy**, writes `~/config/Caddyfile` and starts it : the admin panel on port 80, the APIs on port 8080 and the WebSocket server on port 8081, each proxied to API Maker, or each on its own domain over HTTPS with SSL. Caddy serves the admin panel from its files. 8. Registers the MAC address of the server for the license, and prints the summary. **The end of the output** ```text ———— # API Maker, run by systemd ———— api_maker_be.service active (running) enabled ———— # Important URLs ———— Frontend Admin Panel http://:80 Backend APIs http://:8080 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] : 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 ``` `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. Inside the service, API Maker starts again any of its workers that exits, so systemd only steps in when the whole process stops. ### 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/v1/docs/getting-started/first-api.html) : try its APIs, then add your own [instance](https://docs.apimaker.dev/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](https://docs.apimaker.dev/v1/docs/dashboard/node-dashboard.html) dashboard, and [Deploy API Maker](https://docs.apimaker.dev/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, kept running by systemd), MongoDB as a replica set, Redis, and any reverse proxy for TLS. The [configuration](https://docs.apimaker.dev/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 > ``` > > **~/config/mongodb_api_maker.yml** > > ```yaml > 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 > ``` > > **am__mongo_db_connection** > > ```text > 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** > > **~/config/redis_api_maker.yml** > > ```yaml > 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 > ``` > > **am__redisInternal and am__redisExternal** > > ```text > {"nodes": [{port: 7479, host: "127.0.0.1", pass: "CHANGE_ME"}]} > ``` > **Example : API Maker as a systemd service** > > systemd starts API Maker when the server boots, and again whenever it stops. `main.js` starts the workers itself, one per CPU core with `am__cpuCount=AUTO`. > > **/etc/systemd/system/api_maker_be.service** > > ```ini > [Unit] > Description=API Maker > Wants=network-online.target > After=network-online.target docker.service > # It never gives up : a database that is down for a while must not leave API Maker stopped. > StartLimitIntervalSec=0 > > [Service] > Type=exec > User=root > WorkingDirectory=/root/projects/sava_api_maker > # 👈 the folder of your node, from "dirname $(which node)" : npm and node are found there > Environment=PATH=/root/.nvm/versions/node/v22.20.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin > Environment=HOME=/root > # 👈 the full path of your node, from "which node" > ExecStart=/root/.nvm/versions/node/v22.20.0/bin/node main.js --envPath=/root/config/.env --logFilePath=/root/logs/api_maker_be.txt > StandardOutput=append:/root/logs/api_maker_be.txt > StandardError=append:/root/logs/api_maker_be.txt > Restart=always > RestartSec=1s > # Every process gets SIGTERM, what still runs after 30 seconds is killed. > KillMode=control-group > TimeoutStopSec=30s > # A worker the kernel kills for its memory is started again by API Maker, the others keep serving. > OOMPolicy=continue > LimitNOFILE=infinity > > [Install] > WantedBy=multi-user.target > ``` > > ```bash > mkdir -p ~/logs > systemctl daemon-reload > systemctl enable --now api_maker_be > > systemctl status api_maker_be # active (running) > tail -f ~/logs/api_maker_be.txt # what API Maker prints > ``` > > The installer also puts the time in front of every line of the log and rotates it past 50 MB with `logrotate`. ## Related - [Run on your computer](https://docs.apimaker.dev/v1/docs/getting-started/local-run.html) : API Maker Local Run in detail · [Local setup](https://docs.apimaker.dev/v1/docs/getting-started/local-setup.html) · [How it works](https://docs.apimaker.dev/v1/docs/getting-started/how-it-works.html) · [API Maker configuration](https://docs.apimaker.dev/v1/docs/am-resources/api-maker-configurations.html) · [Deployment architectures](https://apimaker.dev/architectures) - [Next : your first API →](https://docs.apimaker.dev/v1/docs/getting-started/first-api.html) - [Local setup](https://docs.apimaker.dev/v1/docs/getting-started/local-setup.html)