Installing IBM Application Modernization Accelerator locally

Edit online

Installation instructions for running Application Modernization Accelerator on a local workstation using Red Hat Enterprise Linux (RHEL), Windows 11, or macOS.

The following features are supported based on your operating system:

RHEL: Authentication, TLS, and proxy configuration.
Windows and macOS: Platform-level security features (authentication, TLS, and proxy) are not supported.

Application Modernization Accelerator runs in containers. The installation script pulls the container images from the IBM Container Registry and runs them locally by using Podman or Docker. If the machine on which you want to install Application Modernization Accelerator does not have internet access, see Non-OCP air-gapped installation instructions.

Before you begin

Register for the Application Modernization Accelerator Trial and download the installation script (application-modernization-accelerator-local-x.x.x.zip). If you are an EAR customer or have a permanent license, see Switching to a permanent license. To verify the ZIP file, see Security Considerations.
Install Podman 3.4 or higher or Podman Desktop. You can optionally use Docker instead.
Initialize Podman to create a machine with the following resources:
- 8 GB of memory
- 4 cores of CPU
- 20 GB of disk space
- On macOS only: allow Podman to run as root.
If you already have a machine initialized that does not have enough resources, see Current machine does not meet requirements in the Troubleshooting section for instructions on how to change it.

Procedure

In a terminal or at the command prompt, type the following command to ensure that Podman is running:
```
podman ps
```
Extract the downloaded ZIP file to a directory and change to that directory.
Run the installation script:
- On RHEL and macOS:
```
./launch.sh
```
- On Windows:
```
scripts\windowsPodmanDesktop\launch.bat
```
Accept the license terms to install Application Modernization Accelerator.

After the installation is complete, open Application Modernization Accelerator locally in a browser at the URL shown at the end of the installer.

Screenshot of the terminal output showing Installation Complete and the local https URL. — Figure 1. Installation success message showing the local access URL

Tip: For Application Modernization Accelerator to function correctly, your system must be configured to allow ingress and egress on ports 3000 and 2220.

Troubleshooting

Port 443 already in use

Problem: The installation fails because port 443 is already in use by another service.

Reason: For local installations, port 443 is the default, but it is often occupied.

Action: Update the configuration to use a different port:

Navigate to the scripts directory within the extracted installation folder.
Open the .configuration file in a text editor.
Locate the TA_EXTERNAL_UI_PORT parameter and change the port number (for example, to 8443).
Save the file.
Run the installation script again:
- On RHEL and macOS:
```
./launch.sh
```
The script detects the change to the .configuration file and reconfigures the system automatically.

VM already exists on macOS

Problem: On macOS, you see the error message Error: podman-machine-default: VM already exists.

Reason: An existing Podman machine is running but does not meet the minimum resource requirements.

Action: Update the machine resources by following the steps in Current machine does not meet requirements.

Current machine does not meet requirements

Problem: Warn: Current machine does not meet requirements...

Reason: The Podman machine does not meet the resource requirements listed in the Prerequisites section.

Action: Run the following commands:

podman machine stop
podman machine set --cpus=4 --memory=8000
podman machine start

The Podman machine is now updated to use the minimum resources required by the installer.

What to do next

Once you have accessed the Application Modernization Accelerator UI, you can begin your modernization journey.