Installing AI API Mapper

AI API Mapper runs as a set of Docker containers on one host. The installer checks the host, registers your evaluation (or installs your commercial license), downloads the images, and starts the platform. It takes one command on Linux, macOS or Windows.

• Before you start
• Download and run the installer
• What the installer asks
• If you do not have a Docker Hub access key
• After the installation
• Licenses
• Unattended installation
• Options
• Upgrading, stopping and removing
• Troubleshooting

Before you start

On every host:

• 10 GB of free disk space where you install, and two free TCP ports: 8443 (Portal) and 5253 (Gateway). Both ports can be changed.
• Access to the images. While the AI API Mapper images are private, downloading them needs a Docker Hub access key from Coded Projects. If you do not have one, the installer can ask for it for you: see If you do not have a Docker Hub access key.
• An evaluation or a license. Without a license file the installer registers a 30-day evaluation. The evaluation is not for production use.

The images are built for linux/amd64. On Apple silicon, Docker Desktop runs them under emulation (turn on Use Rosetta in Docker Desktop's settings for the best performance). On an arm64 Linux host, install amd64 emulation first: docker run --privileged --rm tonistiigi/binfmt --install amd64.

Download and run the installer

Download the script first and run it second. You can read it before running it, and check it against the published checksums.

Linux and macOS

curl -fsSLO https://apimapper.ai/install/install.sh && bash install.sh

To check the download first:

curl -fsSLO https://apimapper.ai/install/SHA256SUMS
grep ' install.sh$' SHA256SUMS | sha256sum -c -          # Linux
grep ' install.sh$' SHA256SUMS | shasum -a 256 -c -      # macOS

Windows (PowerShell 7)

Invoke-WebRequest https://apimapper.ai/install/install.ps1 -OutFile install.ps1; pwsh -ExecutionPolicy Bypass -File .\install.ps1

To check the download first:

$expected = ((Invoke-RestMethod https://apimapper.ai/install/SHA256SUMS) -split "`n" | Where-Object { $_ -like '*install.ps1' }).Split(' ')[0]
(Get-FileHash .\install.ps1 -Algorithm SHA256).Hash -eq $expected

The installer installs into ./apimapper below the current directory (change it with --install-dir, or -InstallDir on Windows) and installs the platform release it was published with.

What the installer asks

The installer works in six steps.

1. Preflight. It checks Docker, Docker Compose v2, the host architecture, the two ports and the free disk space. A host that cannot run the platform stops here, before you have typed anything.

2. Registration. For an evaluation it shows the current Evaluation License terms and the Coded Projects privacy statement (both links), then asks for:

   • your company name;
   • a contact full name, e.g. John Doe;
   • a contact email;
   • a contact phone (optional: press Enter to skip);
   • whether you accept the Evaluation License terms and the privacy statement.

   Each answer is checked as you type it, and a question repeats until the answer is valid. You then see a summary and confirm it once; answer n to correct it.

   If you do not accept both documents, nothing is sent to Coded Projects and the installation continues without a license: the Portal then shows No license installed. You can register later by running the installer again.

   With a license file (--license-file) this step is skipped.

3. Registry access. If the Docker credentials already on the host can download the images, nothing is asked. Otherwise you choose:

   Docker Hub access is required to download the AI API Mapper images.
     1) I have an access key
     2) Ask Coded Projects for an access key
   

   With 1, type your Docker Hub username and the access key. The key is not shown as you type, and it is handed to docker login directly. After three failed attempts you are back at the menu.

4. Download. The images of the pinned release are downloaded.

5. License. A license file is checked and installed. For an evaluation, the evaluation license is requested now, once the images are downloaded, so the 30 days do not start before the platform can run. Every license is checked by the platform itself before it is installed, so a damaged or unsuitable file never replaces a good one.

6. Start. The database schema is created and the platform starts. The installer prints the Portal address, how to sign in, and the license state reported by the running platform.

If you do not have a Docker Hub access key

Choose 2) Ask Coded Projects for an access key in step 3. The installer sends the registration you entered in step 2 (if you skipped step 2 with a license file, it asks those questions now), then verifies your email address:

We sent a 6-digit code to j***@acme.com. It is valid for 15 minutes.
Enter the code (or "r" to send a new one):

• Type the code from the email. A wrong code tells you how many attempts are left.
• Type r for a new code. An expired code, or one with no attempts left, offers a new one.
• Only a few codes can be sent per address per day. When the limit is reached, the installer tells you when to try again and stops; running the same command later resumes the same request.

Once the code is accepted:

Your request ACR-... has been sent to Coded Projects.
We will email your access key to <your email>.
When you receive it, run the same command again and choose "I have an access key".

The installer then stops with exit code 10, and nothing is downloaded yet. If a request for your email is already open, the installer tells you its number and date and sends nothing new.

An access key cannot be requested by an unattended run, because the email address has to be verified. Run the installer interactively once, or ask with the contact form.

After the installation

The certificate is self-signed, so browsers warn until you replace it. Put your own certificate and private key (PEM) in apimapper/certs/apimapper.crt and apimapper/certs/apimapper.key, then restart: docker compose -f apimapper/docker-compose.yml restart gateway portal-web. If users reach the host by a name other than localhost, install with --host <name> so the Portal and Gateway addresses match it.

Licenses

The platform reads license/license.json and shows its state in the Portal; the state is also available, without signing in, at https://<host>:5253/runtime/license. A missing, expired or invalid license never stops the platform: the Portal shows a yellow bar that says what is wrong.

Evaluation. Registered by the installer, valid for 30 days, not for production use. Running the installer again with the same email returns the same evaluation; it does not start a new one. A new evaluation after one has ended is not possible: contact Coded Projects.

Commercial license. Install it at installation time with --license-file <path> (-LicenseFile on Windows), or replace the current license at any time:

bash install.sh update-license /path/to/license.json

pwsh -ExecutionPolicy Bypass -File .\install.ps1 update-license C:\path\to\license.json

update-license checks the file with the platform first and leaves the current license untouched if the new one is not valid or has expired. It then replaces the file in one step and waits up to 90 seconds for the running platform to report the new license. No restart is needed. Add --install-dir <dir> (-InstallDir) if you did not install into ./apimapper.

Unattended installation

With --non-interactive, or when standard input is not a terminal (a script, CI), the installer never asks. Everything it would ask must be given as options, and if anything is missing it stops before downloading or sending anything, listing what is missing. The --accept-* options are your acceptance of the Evaluation License terms and the Coded Projects privacy statement.

APIMAPPER_REGISTRY_TOKEN='<access key>' bash install.sh --non-interactive \
  --registry-username <docker hub user> \
  --company "ACME S.p.A." --contact-name "John Doe" --contact-email john.doe@acme.example \
  --accept-evaluation-terms --accept-privacy-statement

$env:APIMAPPER_REGISTRY_TOKEN = '<access key>'
pwsh -File .\install.ps1 -NonInteractive -RegistryUsername <docker hub user> `
  -Company 'ACME S.p.A.' -ContactName 'John Doe' -ContactEmail john.doe@acme.example `
  -AcceptEvaluationTerms -AcceptPrivacyStatement

The access key is only ever read from APIMAPPER_REGISTRY_TOKEN or typed at the hidden prompt: it is never an option, because options are visible in the process list and the shell history. With a license file, or --no-license, no registration options are needed.

Options

Exit codes: 0 installed (or license updated), 1 failed, 2 an invalid option or a value an unattended run needs is missing, 10 waiting for registry access (an access-key request was sent).

Upgrading, stopping and removing

• Upgrade: download the installer of the new release and run it again in the same directory. It keeps .env (with the generated secrets), the certificate and the license, downloads the new images, updates the database schema and restarts the platform.
• Stop / start: docker compose -f apimapper/docker-compose.yml down and ... up -d. Your data is kept.
• Remove everything: docker compose -f apimapper/docker-compose.yml down -v deletes the containers and the data volumes; then delete the apimapper directory.

Troubleshooting

Your data. Your registration answers are sent to Coded Projects only with an evaluation request and an access-key request, and they are never written to .env, the installation directory or install.log. (The evaluation license itself names your company as its licensee, as every license does.) The registry access key is kept by Docker's own credential store after docker login; run docker logout to remove it.