SAP_Developer_Edition_Setup_Guide.md

ABAP Trial

# SAP ABAP Cloud Developer Trial 2023 — Docker Setup Guide

**Image:** `sapse/abap-cloud-developer-trial:2023`  
**Add-on:** ABAP Accelerator MCP Server (AI-assisted development via Amazon Q Developer / Kiro)  
**Environment:** Mac Studio → Docker Desktop (macOS) + SAP GUI for Windows via Parallels  
**Last updated:** April 2026

---

## Prerequisites

| Requirement | Minimum | Recommended |
|---|---|---|
| RAM (host machine) | 32 GB | 64 GB+ |
| Free disk space | 100 GB | 200 GB+ |
| Docker Desktop | Installed & running | Latest stable |
| Parallels Desktop | Installed with Windows 10/11 | Latest stable |
| SAP account | Required for license | [sap.com](https://www.sap.com) |

> **Apple Silicon (M-series) note:**  
> SAP has confirmed that ABAP Cloud Developer Trial runs on Apple Silicon Macs (M2 Pro tested) with Docker Desktop on macOS Sequoia 15.5+. The image runs under Rosetta 2 emulation. Ensure Rosetta is installed:
> ```bash
> softwareupdate --install-rosetta
> ```

---

## Part 1: Docker Desktop Configuration

### 1.1 Allocate Resources

Open **Docker Desktop → Settings → Resources**:

- **Memory:** At least 16 GB (22 GB recommended if your Mac Studio has 64 GB+ RAM)
- **Disk image size:** At least **150 GB** (the image is ~23 GB compressed, expands to ~60 GB, and grows during use)
- **CPUs:** At least 4 cores

Click **Apply & Restart**.

### 1.2 Disable Resource Saver

Go to **Settings → Resources → Resource Saver** and **disable** it. This feature suspends TCP connections after idle time, causing SAP GUI disconnections.

---

## Part 2: Create and Start the Container

Since you already have the image `sapse/abap-cloud-developer-trial:2023` downloaded, skip the pull step and go straight to creating the container.

### 2.1 Verify the Image Is Present

```bash
docker images | grep abap-cloud-developer-trial
```

You should see a line with tag `2023`.

### 2.2 Create the Container

```bash
docker run \
  --stop-timeout 3600 \
  -i \
  --name a4h \
  -h vhcala4hci \
  --mac-address 02:42:ac:11:00:11 \
  -p 3200:3200 \
  -p 3300:3300 \
  -p 8443:8443 \
  -p 30213:30213 \
  -p 50000:50000 \
  -p 50002:50001 \
  sapse/abap-cloud-developer-trial:2023 \
  -skip-limits-check \
  -agree-to-sap-license
```

**What each parameter does:**

| Parameter | Purpose |
|---|---|
| `--stop-timeout 3600` | Gives SAP 60 minutes for graceful shutdown |
| `-i` | Interactive mode — allows Ctrl+C to stop gracefully |
| `--name a4h` | Names the container for easy reference |
| `-h vhcala4hci` | **Required** hostname — SAP expects this exactly |
| `--mac-address 02:42:ac:11:00:11` | Fixes the MAC address so the Hardware Key stays stable across restarts (prevents license invalidation) |
| `-p 3200:3200` | SAP GUI (dispatcher, instance 00) |
| `-p 3300:3300` | SAP Gateway |
| `-p 8443:8443` | SAP Cloud Connector (HTTPS) |
| `-p 30213:30213` | SAP HANA SQL/MDX |
| `-p 50000:50000` | HTTP (ICM) |
| `-p 50002:50001` | SAP's HTTPS (ICM) remapped to 50002 so Caddy can own port 50001 with a trusted certificate (see Part 7) |
| `-skip-limits-check` | Bypasses sysctl/limits checks (required on Mac/Windows) |
| `-agree-to-sap-license` | Accepts the SAP license automatically on restarts |

> **Why port 50002?** Eclipse ADT and Fiori Launchpad generate URLs using `vhcala4hci:50001`. By letting Caddy listen on port 50001 with a trusted certificate and proxying to Docker's remapped port 50002, **all** browser URLs — including those launched automatically by Eclipse — work with trusted HTTPS and no certificate warnings.

### 2.3 Wait for Startup

The first startup takes **15–30 minutes**. Watch the terminal output. When you see:

```
*** Have fun! ***
```

The system is ready. **Wait an additional 5–10 minutes** before logging in — internal services continue initializing, and premature login attempts may fail or hang.

### 2.4 Note the Hardware Key

During startup, the container prints a **Hardware Key**. **Copy and save this** — you need it for the license in Part 3.

---

## Part 3: Install the Developer License

The bundled license expires after **90 days**. Install a proper developer license right away.

### 3.1 Request a Developer License

1. Open the **SAP License Key Request** site:  
   **[https://go.support.sap.com/minisap/](https://go.support.sap.com/minisap/)**
2. Choose system **A4H**
3. Fill in your details (name, email, etc.)
4. Enter the **Hardware Key** from step 2.4
5. Download the license file (e.g., `A4H.txt`)

### 3.2 Install the License — Method A: Via SAP GUI

1. Log in to **client 000** as user **SAP\*** with password **`ABAPtr2023#00`**
2. Run transaction **SLICENSE**
3. Click **Install** and upload the downloaded license file
4. Log off from SAP*
5. Log in to **client 001** as **DEVELOPER** (same password: `ABAPtr2023#00`)
6. Run **SLICENSE** again and delete any old "INITIAL" licenses

### 3.3 Install the License — Method B: Via Docker (no SAP GUI needed)

```bash
# Copy the ABAP license file into the container
docker cp /path/to/A4H.txt a4h:/opt/sap/ASABAP_license

# Trigger the license update
docker exec -it a4h /usr/local/bin/asabap_license_update
```

For the HANA database license (if needed separately):

```bash
docker cp /path/to/A4H.txt a4h:/opt/sap/HDB_license
docker exec -it a4h /usr/local/bin/hdb_license_update
```

---

## Part 4: Connect SAP GUI from Windows on Parallels

### 4.1 Install SAP GUI for Windows

1. Download **SAP GUI for Windows** (version 8.10+) from:  
   **[https://developers.sap.com/trials-downloads.html](https://developers.sap.com/trials-downloads.html)**  
   (search for "SAP GUI")
2. Install it inside your **Windows VM running in Parallels**

### 4.2 Determine the Mac Host IP (from the Windows VM perspective)

The Docker container exposes SAP ports on all Mac network interfaces. From the Windows VM you need to find which IP reaches the Mac host on the Parallels virtual network.

**Step 1 — Find your Windows VM's own IP and gateway:**

In the Windows VM, open Command Prompt:

```cmd
ipconfig
```

Look for the **Ethernet adapter** section. You will see something like:

```
IPv4 Address. . . . . . . . . : 10.211.55.3
Subnet Mask . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . : 10.211.55.1
```

Note down both your **IPv4 Address** (e.g., `10.211.55.3`) and **Default Gateway** (e.g., `10.211.55.1`).

**Step 2 — Determine the Mac host IP to use:**

The Mac host typically sits at an IP on the same Parallels subnet. It may or may not be the Default Gateway. To find the correct IP, run this on the **Mac** Terminal:

```bash
ifconfig | grep "inet " | grep -v 127.0.0.1
```

Look for the IP address in the same `10.211.55.x` subnet as your Windows VM. Common values are `10.211.55.2` or the gateway address itself. Note this IP — we'll call it `<MAC_HOST_IP>`.

**Step 3 — Verify the IP works:**

Back in the Windows VM Command Prompt, test that SAP's dispatcher port is reachable:

```cmd
telnet <MAC_HOST_IP> 3200
```

If it connects (blank screen, no error message), that's the correct IP. If `telnet` isn't available, enable it via **Turn Windows features on or off** → **Telnet Client**. Alternatively:

```cmd
powershell Test-NetConnection -ComputerName <MAC_HOST_IP> -Port 3200
```

> **Tip:** If neither the gateway IP nor the `.2` address works, try every IP in the `10.211.55.x` range that appeared in your Mac's `ifconfig` output until you find the one where port 3200 connects.

### 4.3 Update the Windows Hosts File

In the Windows VM, open **Notepad as Administrator** and edit:

```
C:\Windows\System32\drivers\etc\hosts
```

Add this line, replacing `<MAC_HOST_IP>` with the IP you confirmed in Step 3 above:

```
<MAC_HOST_IP>    vhcala4hci
```

For example, if the working IP was `10.211.55.2`:

```
10.211.55.2    vhcala4hci
```

Save the file.

### 4.4 Test Connectivity via Hostname

Now that the hosts file is configured, verify the hostname resolves correctly:

```cmd
ping vhcala4hci
```

You should see replies from the `<MAC_HOST_IP>` you configured. Then confirm SAP is reachable by name:

```cmd
telnet vhcala4hci 3200
```

A blank screen (no error) means SAP GUI will be able to connect.

### 4.5 Configure SAP Logon

Open **SAP Logon** in the Windows VM and add a new system entry:

| Field | Value |
|---|---|
| Description | `ABAP Cloud Trial 2023 (Docker)` |
| Application Server | `vhcala4hci` |
| Instance Number | `00` |
| System ID | `A4H` |

### 4.6 Log In

**Default password for the 2023 edition: `ABAPtr2023#00`**

| Client | User | Password | Use |
|---|---|---|---|
| 001 | **DEVELOPER** | `ABAPtr2023#00` | Day-to-day development |
| 001 | BWDEVELOPER | `ABAPtr2023#00` | BW development |
| 000 | SAP* | `ABAPtr2023#00` | Administration & license management |
| 000 | DDIC | `ABAPtr2023#00` | Data Dictionary admin |

---

## Part 5: Day-to-Day Operations

### Starting and Stopping (Recommended Method)

After completing Part 7, use the convenience scripts that handle both Docker and Caddy together:

```bash
~/.sap-proxy/sap-start.sh          # Start SAP container + HTTPS proxy
~/.sap-proxy/sap-stop.sh           # Stop everything gracefully
~/.sap-proxy/sap-status.sh         # Check what's running
```

Wait 5–10 minutes after starting before logging in — SAP takes time to fully boot.

### Starting the Container Manually (without Caddy)

If you haven't set up Part 7 yet, or just want the container without the HTTPS proxy:

```bash
docker start -ai a4h
```

Wait for **`*** Have fun! ***`** and then another 5–10 minutes before logging in.

### Stopping the Container Manually — CRITICAL: Always Stop Gracefully

An unclean shutdown can corrupt the HANA database and make the container unusable.

**Method 1 — Docker stop with long timeout:**

```bash
docker stop -t 7200 a4h
```

**Method 2 — Ctrl+C** (if you started with `docker start -ai`):  
Press `Ctrl+C` in the interactive terminal and **wait** for the full shutdown sequence to complete. Do not close the terminal window.

> **WARNING:** Never use `docker kill`, never force-close the terminal, and never shut down Docker Desktop while the container is running.

### Checking Status

```bash
# Is it running?
docker ps

# Check memory
docker exec -it a4h free -h

# Check disk
docker exec -it a4h df -h /

# Check HANA
docker exec -it a4h su - hdbadm -c "sapcontrol -nr 02 -function GetProcessList"

# Check ABAP
docker exec -it a4h su - a4hadm -c "sapcontrol -nr 00 -function GetProcessList"
```

### Backing Up the Container

```bash
# Stop first
docker stop -t 7200 a4h

# Commit to a backup image
docker commit a4h sap-trial-backup:$(date +%Y%m%d)

# Verify
docker images | grep sap-trial-backup
```

---

## Part 6: Additional Access Methods

### Fiori Launchpad (Browser)

If Caddy is running (see Part 7), port 50001 serves trusted HTTPS — no certificate warnings:

```
https://vhcala4hci:50001/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html
```

This URL also works when launched automatically from Eclipse ADT (Fiori preview, OData testing, etc.) — Caddy intercepts it transparently.

Log in with DEVELOPER / `ABAPtr2023#00` on client 001.

### ABAP Development Tools (Eclipse / ADT)

1. Install Eclipse with the ADT plugin (on the Mac or Windows VM)
2. Add a new ABAP project:
   - System ID: `A4H`
   - Connection: `vhcala4hci` (or Mac IP), instance `00`
   - Client: `001`, User: `DEVELOPER`

### SAP HANA Studio / HANA Database

| Field | Value |
|---|---|
| Host | `vhcala4hci` (or Mac IP / localhost) |
| Instance | `02` |
| Mode | Multiple containers → System Database |
| User | `SYSTEM` |
| Password | `ABAPtr2023#00` |

---

## Part 7: Trusted HTTPS for Fiori Launchpad (No Browser Warnings)

The SAP container uses a self-signed certificate, which causes browser warnings every time you access the Fiori Launchpad or any HTTPS service. The fix is a lightweight reverse proxy (Caddy) on the Mac with a locally-trusted certificate generated by `mkcert`. This is a **one-time 10-minute setup** — after that, you start and stop everything with a single command.

### 7.1 Install the Tools

Open **Terminal** on the Mac (Finder → Applications → Utilities → Terminal) and run:

```bash
brew install mkcert
brew install caddy
```

### 7.2 Create a Dedicated Folder

We'll keep all SAP proxy config and certificates in one tidy folder inside your home directory:

```bash
mkdir -p ~/.sap-proxy
cd ~/.sap-proxy
```

> **Where is this?** The `~` means your home folder. In Finder, press `Cmd+Shift+G` and type `~/.sap-proxy` to see it. (The dot prefix makes it hidden by default — press `Cmd+Shift+.` in Finder to show hidden files.)

### 7.3 Generate Trusted Certificates

Still in Terminal:

```bash
# Install the local Certificate Authority into macOS Keychain
# (you'll be prompted for your Mac password once)
mkcert -install

# Generate a certificate covering the SAP hostname, localhost, IP, and Docker's host alias
cd ~/.sap-proxy
mkcert vhcala4hci localhost 127.0.0.1 host.docker.internal
```

This creates two files in `~/.sap-proxy/`:

```
vhcala4hci+3.pem         ← the certificate
vhcala4hci+3-key.pem     ← the private key
```

Your Mac's browsers (Safari, Chrome, Edge) will now trust these certificates automatically — no more warnings for any site using them.

> **Why `host.docker.internal`?** The ABAP Accelerator MCP server (Part 9) runs in its own Docker container and connects to SAP through Caddy using the hostname `host.docker.internal`. Including it in the certificate means the Accelerator can verify SSL without skipping certificate checks.

### 7.4 Create the Caddy Configuration File

In Terminal, run this command to create the Caddyfile. It auto-detects your home directory so there's nothing to edit manually:

```bash
cat > ~/.sap-proxy/Caddyfile << EOF
# SAP HTTPS services (Fiori Launchpad, Eclipse ADT browser previews, etc.)
# Caddy owns port 50001 with a trusted certificate
# Docker maps SAP's internal port 50001 to host port 50002
# So: Browser → Caddy (50001, trusted cert) → Docker (50002, self-signed)
# Binds to 0.0.0.0 so both Mac and Windows VM (Parallels) can access it

https://0.0.0.0:50001 {
    tls $HOME/.sap-proxy/vhcala4hci+3.pem $HOME/.sap-proxy/vhcala4hci+3-key.pem
    reverse_proxy https://localhost:50002 {
        transport http {
            tls_insecure_skip_verify
        }
    }
}

# SAP HTTP services wrapped in trusted HTTPS

https://0.0.0.0:44300 {
    tls $HOME/.sap-proxy/vhcala4hci+3.pem $HOME/.sap-proxy/vhcala4hci+3-key.pem
    reverse_proxy http://localhost:50000
}
EOF
```

Verify it was created:

```bash
cat ~/.sap-proxy/Caddyfile
```

You should see the config with your actual home directory path (e.g., `/Users/warren/.sap-proxy/...`) already filled in.

### 7.5 Add SAP Hostname to Mac Hosts File

The Mac needs `vhcala4hci` to resolve to localhost so Caddy can intercept requests:

```bash
# Check if it's already there
grep vhcala4hci /etc/hosts

# If nothing is returned, add it (you'll be prompted for your Mac password)
sudo sh -c 'echo "127.0.0.1    vhcala4hci" >> /etc/hosts'
```

### 7.6 Create the Start and Stop Scripts

These scripts start and stop **both** the SAP Docker container and the Caddy proxy together, so you only ever run one command.

**Create the start script:**

```bash
cat > ~/.sap-proxy/sap-start.sh << 'SCRIPT'
#!/bin/bash
echo "══════════════════════════════════════════════"
echo "  Starting SAP ABAP Cloud Developer Trial"
echo "══════════════════════════════════════════════"
echo ""

# Start the SAP Docker container
echo "▶ Starting Docker container 'a4h'..."
docker start a4h
echo "  Container started. SAP is booting up (this takes a few minutes)."
echo ""

# Kill any leftover Caddy process before starting fresh
pkill -x caddy 2>/dev/null
sleep 1

# Start Caddy reverse proxy in the background
echo "▶ Starting Caddy HTTPS proxy..."
caddy start --config ~/.sap-proxy/Caddyfile
if [ $? -eq 0 ]; then
    echo "  Caddy is running. Trusted HTTPS available on port 50001."
else
    echo ""
    echo "  ⚠ Caddy failed to start. To see the full error, run:"
    echo "    caddy run --config ~/.sap-proxy/Caddyfile"
fi

echo ""
echo "══════════════════════════════════════════════"
echo "  Waiting for SAP to finish starting..."
echo "  This usually takes 5–15 minutes."
echo ""
echo "  Fiori Launchpad (trusted HTTPS):"
echo "  https://vhcala4hci:50001/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html"
echo ""
echo "  SAP GUI: vhcala4hci, instance 00, system A4H"
echo "  Login: DEVELOPER / ABAPtr2023#00 / client 001"
echo "══════════════════════════════════════════════"
SCRIPT
chmod +x ~/.sap-proxy/sap-start.sh
```

**Create the stop script:**

```bash
cat > ~/.sap-proxy/sap-stop.sh << 'SCRIPT'
#!/bin/bash
echo "══════════════════════════════════════════════"
echo "  Stopping SAP ABAP Cloud Developer Trial"
echo "══════════════════════════════════════════════"
echo ""

# Stop Caddy first (instant)
echo "■ Stopping Caddy HTTPS proxy..."
pkill -x caddy 2>/dev/null
echo "  Caddy stopped."
echo ""

# Stop SAP container gracefully (this takes a while)
echo "■ Stopping Docker container 'a4h' (graceful shutdown)..."
echo "  This can take several minutes — do NOT close the terminal."
docker stop -t 7200 a4h
echo "  Container stopped safely."

echo ""
echo "══════════════════════════════════════════════"
echo "  SAP is fully stopped. Safe to close Docker"
echo "  Desktop or shut down your Mac."
echo "══════════════════════════════════════════════"
SCRIPT
chmod +x ~/.sap-proxy/sap-stop.sh
```

**Create a status check script:**

```bash
cat > ~/.sap-proxy/sap-status.sh << 'SCRIPT'
#!/bin/bash
echo "── SAP Docker Container ──"
if docker ps --format '{{.Names}}' | grep -q '^a4h$'; then
    echo "  ✓ Container 'a4h' is RUNNING"
    docker exec a4h free -h 2>/dev/null | head -2
else
    echo "  ✗ Container 'a4h' is STOPPED"
fi
echo ""
echo "── Caddy HTTPS Proxy ──"
if curl -s -o /dev/null -w "%{http_code}" --max-time 2 https://vhcala4hci:50001 -k 2>/dev/null | grep -q ""; then
    if pgrep -x caddy > /dev/null; then
        echo "  ✓ Caddy is RUNNING"
    else
        echo "  ✗ Caddy is STOPPED"
    fi
else
    if pgrep -x caddy > /dev/null; then
        echo "  ✓ Caddy is RUNNING"
    else
        echo "  ✗ Caddy is STOPPED"
    fi
fi
SCRIPT
chmod +x ~/.sap-proxy/sap-status.sh
```

### 7.7 Using the Scripts

Open **Terminal** on the Mac and run:

```bash
# Start everything (Docker container + Caddy proxy)
~/.sap-proxy/sap-start.sh

# Check if things are running
~/.sap-proxy/sap-status.sh

# Stop everything gracefully when you're done for the day
~/.sap-proxy/sap-stop.sh
```

> **Tip:** To make these even easier to type, add aliases to your shell. Run this once:
> ```bash
> echo '' >> ~/.zshrc
> echo '# SAP shortcuts' >> ~/.zshrc
> echo 'alias sap-start="~/.sap-proxy/sap-start.sh"' >> ~/.zshrc
> echo 'alias sap-stop="~/.sap-proxy/sap-stop.sh"' >> ~/.zshrc
> echo 'alias sap-status="~/.sap-proxy/sap-status.sh"' >> ~/.zshrc
> source ~/.zshrc
> ```
> Then you can simply type `sap-start`, `sap-stop`, or `sap-status` from anywhere in Terminal.

### 7.8 Test It (First Time)

Run the start script:

```bash
~/.sap-proxy/sap-start.sh
```

Wait for the SAP container to fully start (watch Docker Desktop — when the container shows as running and you've waited 5–10 minutes), then open a browser and go to:

```
https://vhcala4hci:50001/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html
```

You should see the Fiori Launchpad with a **green padlock** — no certificate warnings.

### 7.9 Trust the Root CA in the Windows VM (Parallels)

For Fiori Launchpad access from the Windows VM browser, Windows also needs to trust the mkcert root CA.

**Find the root CA on the Mac:**

```bash
mkcert -CAROOT
```

This prints a path like `/Users/warren/Library/Application Support/mkcert`. Open that folder in Finder (`Cmd+Shift+G`, paste the path) and find the file `rootCA.pem`.

**Copy it to the Windows VM** — easiest way: drag `rootCA.pem` from Finder onto the Windows desktop in Parallels.

**Install it in Windows:**

1. Press **Win+R**, type `mmc`, press Enter (accept the admin prompt)
2. In the MMC window, click **File → Add/Remove Snap-in**
3. Select **Certificates** from the left list, click **Add**
4. Choose **Computer account** → **Next** → **Local computer** → **Finish** → **OK**
5. In the left tree, expand **Certificates (Local Computer)** → **Trusted Root Certification Authorities** → **Certificates**
6. Right-click **Certificates** → **All Tasks** → **Import...**
7. Click **Next**, then **Browse**
8. In the file picker, change the file type dropdown (bottom right) from "X.509 Certificate" to **All Files (\*.\*)**
9. Navigate to the desktop, select `rootCA.pem`, click **Open**
10. Click **Next** → ensure the store says "Trusted Root Certification Authorities" → **Next** → **Finish**
11. Close MMC (you don't need to save the console)
12. **Restart Chrome/Edge** in the Windows VM

### 7.10 Access Fiori Launchpad Without Warnings

From the **Mac** browser:

```
https://vhcala4hci:50001/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html
```

From the **Windows VM** browser (after step 7.9):

```
https://vhcala4hci:50001/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html
```

Log in with DEVELOPER / `ABAPtr2023#00` on client 001. Green padlock, no warnings.

> **Note:** SAP GUI connections on port 3200 use SAP's own protocol (not HTTPS), so they are completely unaffected — SAP GUI works exactly as before.

### 7.11 Summary of What's Where

```
~/.sap-proxy/
├── sap-start.sh                  ← Start SAP container + Caddy proxy
├── sap-stop.sh                   ← Stop both gracefully
├── sap-status.sh                 ← Check if everything is running
├── Caddyfile                     ← Caddy reverse proxy configuration
├── vhcala4hci+3.pem              ← SSL certificate (trusted)
└── vhcala4hci+3-key.pem          ← SSL private key

/etc/hosts
└── 127.0.0.1    vhcala4hci       ← Hostname mapping (added in step 7.5)
```

---

## Part 8: Troubleshooting

### Container hangs at "HDB: starting"

Insufficient memory. Ensure Docker Desktop has at least 16 GB allocated and close memory-heavy applications on the Mac.

### "Connection refused" from SAP GUI in Parallels

1. Confirm the container is fully started (`*** Have fun! ***`)
2. Test from the Mac: `nc -zv localhost 3200`
3. Test from the Windows VM: `telnet <mac_ip> 3200`
4. Verify the hosts file entry in Windows points to the correct Mac IP
5. Check that Windows Firewall isn't blocking outbound connections on port 3200
6. Try using the Mac's LAN IP instead of the Parallels gateway IP

### License expired or Hardware Key changed

Re-request a license from [minisap](https://go.support.sap.com/minisap/) with the new Hardware Key. The `--mac-address` parameter in the docker run command (Part 2.2) should prevent the key from changing on restart.

### Port conflicts on the Mac

```bash
# Find what's using a port (e.g., 8443)
lsof -i :8443
```

Either stop the conflicting process or remap the port:

```bash
# Example: map container port 8443 to host port 9443
-p 9443:8443
```

### SAP GUI disconnects after Mac goes idle

Ensure Docker Desktop's **Resource Saver** is disabled (Part 1.2). Also disable macOS Energy Saver sleep settings while running SAP.

### Recovering from unclean shutdown

If the container won't start after a crash, you may need to recreate it from the image. This is why backing up (Part 5) is important. To recreate:

```bash
docker rm a4h
# Then repeat the docker run command from Part 2.2
```

---

## Part 9: ABAP Accelerator MCP Server (AI-Assisted ABAP Development)

The ABAP Accelerator is an MCP (Model Context Protocol) server from AWS that provides AI-powered ABAP development assistance through Amazon Q Developer or Kiro. It connects to your local SAP trial container and exposes 15 development tools: connection management, object creation/retrieval, syntax checking, code activation, ATC quality checks, unit testing, transport management, and migration analysis.

**Source:** [github.com/aws-solutions-library-samples/guidance-for-deploying-sap-abap-accelerator-for-amazon-q-developer](https://github.com/aws-solutions-library-samples/guidance-for-deploying-sap-abap-accelerator-for-amazon-q-developer)

> **Important:** The ABAP Accelerator is intended for development/sandbox environments only — not production systems.

### 9.1 Prerequisites

Before starting, ensure:

- The SAP trial container (`a4h`) is running and fully started (Part 2 / Part 5)
- Docker Desktop is running with sufficient resources (Part 1)
- You have Git installed on the Mac (`brew install git` if not)
- You have Node.js installed on the Mac (`brew install node` if not) — required for the Claude Desktop MCP bridge

### 9.2 Clone the Repository and Build the Docker Image

Open **Terminal** on the Mac:

```bash
# Create a working directory alongside the SAP proxy config
mkdir -p ~/abap-accelerator
cd ~/abap-accelerator

# Clone the repository
git clone https://github.com/aws-solutions-library-samples/guidance-for-deploying-sap-abap-accelerator-for-amazon-q-developer.git
cd guidance-for-deploying-sap-abap-accelerator-for-amazon-q-developer

# The Dockerfile expects a .env.example file that isn't included in the repo — create an empty one
touch .env.example

# Build for ARM64 (Apple Silicon M1/M2/M3/M4)
docker buildx build --platform linux/arm64 -f Dockerfile.simple -t abap-accelerator-enterprise:latest .
```

Verify the image was created:

```bash
docker images | grep abap-accelerator
```

### 9.3 Configure the SAP System Connection

Create a `sap-systems.yaml` file that tells the Accelerator how to reach your local SAP trial. The Accelerator runs inside its own Docker container, so it uses `host.docker.internal` (Docker's built-in DNS for reaching the host machine) instead of `vhcala4hci`.

**Option A — Connect via Caddy's trusted HTTPS (port 50001, recommended):**

If you completed Part 7, Caddy provides trusted HTTPS on port 50001. Since the certificate was generated with `host.docker.internal` included (step 7.3), the Accelerator can verify SSL properly:

```bash
cat > ~/abap-accelerator/sap-systems.yaml << 'EOF'
# SAP System Configuration for ABAP Accelerator
# Connects to the local SAP trial via Caddy's trusted HTTPS proxy
# Credentials are prompted interactively at container startup

systems:
  A4H-LOCAL:
    host: host.docker.internal:50001
    client: "001"
    description: "Local ABAP Cloud Developer Trial 2023 (via Caddy)"
EOF
```

**Option B — Connect directly to the SAP container (port 50002, skip SSL verification):**

If you don't have Caddy running, connect directly to Docker's remapped HTTPS port. You'll need to disable SSL verification since the container uses a self-signed certificate:

```bash
cat > ~/abap-accelerator/sap-systems.yaml << 'EOF'
# SAP System Configuration for ABAP Accelerator
# Connects directly to the SAP container's self-signed HTTPS
# Credentials are prompted interactively at container startup

systems:
  A4H-LOCAL:
    host: host.docker.internal:50002
    client: "001"
    description: "Local ABAP Cloud Developer Trial 2023 (direct)"
EOF
```

### 9.4 Run the ABAP Accelerator Container

**With Caddy (Option A — trusted SSL with CA mount):**

The Accelerator container needs the mkcert root CA so it can verify Caddy's certificate. Mount it at `/app/certs/custom-ca.pem`:

```bash
docker run -it -p 8000:8000 \
  -v ~/abap-accelerator/sap-systems.yaml:/app/config/sap-systems.yaml:ro \
  -v "$(mkcert -CAROOT)/rootCA.pem":/app/certs/custom-ca.pem:ro \
  -e CREDENTIAL_PROVIDER=interactive-multi \
  -e ENABLE_PRINCIPAL_PROPAGATION=false \
  -e CUSTOM_CA_CERT_PATH=/app/certs/custom-ca.pem \
  --name abap-accel \
  abap-accelerator-enterprise:latest
```

**Without Caddy (Option B — skip SSL verification):**

```bash
docker run -it -p 8000:8000 \
  -v ~/abap-accelerator/sap-systems.yaml:/app/config/sap-systems.yaml:ro \
  -e CREDENTIAL_PROVIDER=interactive-multi \
  -e ENABLE_PRINCIPAL_PROPAGATION=false \
  -e SSL_VERIFY=false \
  --name abap-accel \
  abap-accelerator-enterprise:latest
```

The container will prompt you for credentials:

```
============================================================
  SAP CREDENTIALS INPUT (Stored in memory only)
============================================================

System: A4H-LOCAL (Local ABAP Cloud Developer Trial 2023)
  Host: host.docker.internal:50001
  Client: 001
  Username: DEVELOPER
  Password: ********
  ✓ Credentials stored for A4H-LOCAL

============================================================
  All credentials stored. Starting MCP server...
============================================================
```

Enter `DEVELOPER` as the username and `ABAPtr2023#00` as the password.

### 9.5 Configure Your AI Tool (Claude Desktop, Amazon Q Developer, or Kiro)

Once the Accelerator container is running, configure your AI tool to connect to it. The Accelerator uses **Streamable HTTP** transport on `http://localhost:8000/mcp`.

**For Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

Claude Desktop uses stdio transport to communicate with MCP servers, so it needs a bridge to connect to the Accelerator's HTTP endpoint. The `mcp-remote` package handles this translation. You'll need Node.js installed (`brew install node` if you don't have it).

```json
{
  "mcpServers": {
    "abap-accelerator": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp"
      ]
    }
  }
}
```

Restart Claude Desktop completely (quit and reopen) after saving. You should see the hammer icon (🔨) appear in the chat input area once it connects.

> **Why the bridge?** Claude Desktop launches MCP servers as local processes using stdio (standard input/output). The ABAP Accelerator runs as an HTTP server inside Docker. The `mcp-remote` npm package translates between these two protocols — Claude Desktop talks stdio to `mcp-remote`, which talks Streamable HTTP to the Accelerator container.

**For Amazon Q Developer** — edit `~/.aws/amazonq/mcp.json` (or workspace `.amazonq/mcp.json`):

```json
{
  "mcpServers": {
    "abap-accelerator": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

**For Kiro** — edit `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "abap-accelerator": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

Restart your IDE after saving the configuration. The ABAP Accelerator tools should appear in the tool list.

### 9.6 Verify the Connection

After configuring your AI tool, ask it to check the SAP connection:

```
Check SAP connection status
```

The Accelerator should report a successful connection to your local SAP trial system.

### 9.7 Day-to-Day Operations

The Accelerator container is lightweight and starts quickly, unlike the SAP trial itself. Here's the typical workflow:

```bash
# 1. Start SAP first (if not already running)
~/.sap-proxy/sap-start.sh

# 2. Wait for SAP to fully boot (5–15 minutes)

# 3. Start the Accelerator (subsequent runs — container already exists)
docker start -ai abap-accel

# 4. When done, stop the Accelerator first (instant)
# Press Ctrl+C in the Accelerator terminal, or:
docker stop abap-accel

# 5. Then stop SAP
~/.sap-proxy/sap-stop.sh
```

> **Note:** If you used `docker run` with `--name abap-accel` and the container already exists, use `docker start -ai abap-accel` for subsequent runs. If you need to change environment variables or the mounted config, remove the container first with `docker rm abap-accel` and run `docker run` again.

### 9.8 Update the Start/Stop/Status Scripts (Optional)

To incorporate the Accelerator into your existing convenience scripts, update them to manage both containers together.

**Updated start script** — add the Accelerator start after Caddy:

```bash
cat > ~/.sap-proxy/sap-start.sh << 'SCRIPT'
#!/bin/bash
echo "══════════════════════════════════════════════"
echo "  Starting SAP ABAP Cloud Developer Trial"
echo "══════════════════════════════════════════════"
echo ""

# Start the SAP Docker container
echo "▶ Starting Docker container 'a4h'..."
docker start a4h
echo "  Container started. SAP is booting up (this takes a few minutes)."
echo ""

# Kill any leftover Caddy process before starting fresh
pkill -x caddy 2>/dev/null
sleep 1

# Start Caddy reverse proxy in the background
echo "▶ Starting Caddy HTTPS proxy..."
caddy start --config ~/.sap-proxy/Caddyfile
if [ $? -eq 0 ]; then
    echo "  Caddy is running. Trusted HTTPS available on port 50001."
else
    echo ""
    echo "  ⚠ Caddy failed to start. To see the full error, run:"
    echo "    caddy run --config ~/.sap-proxy/Caddyfile"
fi

echo ""

# Start the ABAP Accelerator if the container exists
if docker ps -a --format '{{.Names}}' | grep -q '^abap-accel$'; then
    echo "▶ Starting ABAP Accelerator MCP server..."
    docker start abap-accel
    echo "  Accelerator is running on http://localhost:8000/mcp"
    echo "  (If credentials expired, stop and run: docker start -ai abap-accel)"
fi

echo ""
echo "══════════════════════════════════════════════"
echo "  Waiting for SAP to finish starting..."
echo "  This usually takes 5–15 minutes."
echo ""
echo "  Fiori Launchpad (trusted HTTPS):"
echo "  https://vhcala4hci:50001/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html"
echo ""
echo "  MCP Server: http://localhost:8000/mcp"
echo ""
echo "  SAP GUI: vhcala4hci, instance 00, system A4H"
echo "  Login: DEVELOPER / ABAPtr2023#00 / client 001"
echo "══════════════════════════════════════════════"
SCRIPT
chmod +x ~/.sap-proxy/sap-start.sh
```

**Updated stop script** — stop the Accelerator before SAP:

```bash
cat > ~/.sap-proxy/sap-stop.sh << 'SCRIPT'
#!/bin/bash
echo "══════════════════════════════════════════════"
echo "  Stopping SAP ABAP Cloud Developer Trial"
echo "══════════════════════════════════════════════"
echo ""

# Stop the ABAP Accelerator first (instant)
if docker ps --format '{{.Names}}' | grep -q '^abap-accel$'; then
    echo "■ Stopping ABAP Accelerator..."
    docker stop abap-accel
    echo "  Accelerator stopped."
    echo ""
fi

# Stop Caddy (instant)
echo "■ Stopping Caddy HTTPS proxy..."
pkill -x caddy 2>/dev/null
echo "  Caddy stopped."
echo ""

# Stop SAP container gracefully (this takes a while)
echo "■ Stopping Docker container 'a4h' (graceful shutdown)..."
echo "  This can take several minutes — do NOT close the terminal."
docker stop -t 7200 a4h
echo "  Container stopped safely."

echo ""
echo "══════════════════════════════════════════════"
echo "  SAP is fully stopped. Safe to close Docker"
echo "  Desktop or shut down your Mac."
echo "══════════════════════════════════════════════"
SCRIPT
chmod +x ~/.sap-proxy/sap-stop.sh
```

**Updated status script** — add Accelerator status check:

```bash
cat > ~/.sap-proxy/sap-status.sh << 'SCRIPT'
#!/bin/bash
echo "── SAP Docker Container ──"
if docker ps --format '{{.Names}}' | grep -q '^a4h$'; then
    echo "  ✓ Container 'a4h' is RUNNING"
    docker exec a4h free -h 2>/dev/null | head -2
else
    echo "  ✗ Container 'a4h' is STOPPED"
fi
echo ""
echo "── Caddy HTTPS Proxy ──"
if pgrep -x caddy > /dev/null; then
    echo "  ✓ Caddy is RUNNING"
else
    echo "  ✗ Caddy is STOPPED"
fi
echo ""
echo "── ABAP Accelerator MCP Server ──"
if docker ps --format '{{.Names}}' | grep -q '^abap-accel$'; then
    echo "  ✓ Accelerator is RUNNING (http://localhost:8000/mcp)"
else
    echo "  ✗ Accelerator is STOPPED"
fi
SCRIPT
chmod +x ~/.sap-proxy/sap-status.sh
```

### 9.9 Port Summary After Setup

With both containers running, these are the ports in use on the Mac:

| Port | Service | Container |
|---|---|---|
| 3200 | SAP GUI (dispatcher) | a4h |
| 3300 | SAP Gateway | a4h |
| 8443 | SAP Cloud Connector | a4h |
| 30213 | SAP HANA SQL/MDX | a4h |
| 50000 | SAP HTTP (ICM) | a4h |
| 50001 | Caddy → trusted HTTPS | Caddy (host process) |
| 50002 | SAP HTTPS (ICM, remapped) | a4h |
| 8000 | ABAP Accelerator MCP | abap-accel |

### 9.10 Troubleshooting the Accelerator

**"Connection refused" or timeout when Accelerator tries to reach SAP:**

The SAP container must be fully started before the Accelerator can connect. If you started both simultaneously, the Accelerator may fail to reach SAP during its boot phase. Stop the Accelerator, wait for SAP's `*** Have fun! ***` message plus 5 minutes, then start the Accelerator again.

**SSL certificate errors (when using Option A with Caddy):**

If you see `CERTIFICATE_VERIFY_FAILED` or `Hostname mismatch`, check two things:

1. **The mkcert certificate must include `host.docker.internal`.** If you generated the certificate before Part 9, it may only cover `vhcala4hci`, `localhost`, and `127.0.0.1`. Regenerate it:
   ```bash
   cd ~/.sap-proxy
   mkcert vhcala4hci localhost 127.0.0.1 host.docker.internal
   ```
   Then update the Caddyfile to reference the new `+3` filenames and restart Caddy.

2. **The CA root certificate must be mounted into the Accelerator container.** Ensure your `docker run` command includes `-v "$(mkcert -CAROOT)/rootCA.pem":/app/certs/custom-ca.pem:ro` and `-e CUSTOM_CA_CERT_PATH=/app/certs/custom-ca.pem` (see step 9.4).

**Port 8000 conflict:**

If something else is already using port 8000 on your Mac, remap the Accelerator to a different host port:

```bash
docker run -it -p 9000:8000 \
  ...
  abap-accelerator-enterprise:latest
```

Then update your MCP config to use `http://localhost:9000/mcp`.

**Credentials expired or wrong:**

Credentials are stored in memory only and are lost when the container stops. On each `docker start -ai abap-accel`, you'll be prompted again. If the container was started in detached mode and credentials weren't entered, remove and recreate it:

```bash
docker rm abap-accel
# Then repeat the docker run command from 9.4
```

---

## Quick Reference Card

```bash
# ── DAILY WORKFLOW ──
~/.sap-proxy/sap-start.sh          # Start SAP + Caddy + Accelerator
~/.sap-proxy/sap-status.sh         # Check if everything is running
~/.sap-proxy/sap-stop.sh           # Stop everything gracefully

# Or if you set up the aliases (see Part 7.7):
sap-start
sap-status
sap-stop

# ── FIRST RUN: SAP CONTAINER (one time only) ──
docker run --stop-timeout 3600 -i --name a4h -h vhcala4hci \
  --mac-address 02:42:ac:11:00:11 \
  -p 3200:3200 -p 3300:3300 -p 8443:8443 \
  -p 30213:30213 -p 50000:50000 -p 50002:50001 \
  sapse/abap-cloud-developer-trial:2023 \
  -skip-limits-check -agree-to-sap-license

# ── FIRST RUN: ABAP ACCELERATOR (one time only) ──
docker run -it -p 8000:8000 \
  -v ~/abap-accelerator/sap-systems.yaml:/app/config/sap-systems.yaml:ro \
  -v "$(mkcert -CAROOT)/rootCA.pem":/app/certs/custom-ca.pem:ro \
  -e CREDENTIAL_PROVIDER=interactive-multi \
  -e ENABLE_PRINCIPAL_PROPAGATION=false \
  -e CUSTOM_CA_CERT_PATH=/app/certs/custom-ca.pem \
  --name abap-accel \
  abap-accelerator-enterprise:latest

# ── ACCELERATOR (subsequent runs) ──
docker start -ai abap-accel         # Interactive — prompts for credentials
docker stop abap-accel               # Stop the Accelerator

# ── INSTALL LICENSE ──
docker cp A4H.txt a4h:/opt/sap/ASABAP_license
docker exec -it a4h /usr/local/bin/asabap_license_update

# ── BACKUP ──
~/.sap-proxy/sap-stop.sh
docker commit a4h sap-trial-backup:latest

# ── SHELL INTO CONTAINER ──
docker exec -it a4h bash
```

**Credentials (2023 edition):**

| User | Password | Client |
|---|---|---|
| DEVELOPER | `ABAPtr2023#00` | 001 |
| SAP* | `ABAPtr2023#00` | 000 |
| DDIC | `ABAPtr2023#00` | 000 |

---

## Key Links

| Resource | URL |
|---|---|
| Docker Hub image | [sapse/abap-cloud-developer-trial](https://hub.docker.com/r/sapse/abap-cloud-developer-trial/tags) |
| SAP Developer License | [go.support.sap.com/minisap](https://go.support.sap.com/minisap/) |
| SAP GUI download | [developers.sap.com/trials-downloads](https://developers.sap.com/trials-downloads.html) |
| ABAP Accelerator (GitHub) | [aws-solutions-library-samples/guidance-for-deploying-sap-abap-accelerator-for-amazon-q-developer](https://github.com/aws-solutions-library-samples/guidance-for-deploying-sap-abap-accelerator-for-amazon-q-developer) |
| ABAP Accelerator Blog | [Introducing ABAP Accelerator](https://aws.amazon.com/blogs/awsforsap/introducing-abap-accelerator-for-ai-assisted-development) |
| FAQ & Docs (GitHub) | [SAP-docs/abap-platform-trial-image](https://github.com/SAP-docs/abap-platform-trial-image) |
| 2023 Announcement Blog | [ABAP Cloud Developer Trial 2023](https://community.sap.com/t5/technology-blog-posts-by-sap/abap-cloud-developer-trial-2023-available-now/ba-p/14057183) |
| Community Support | [SAP Community - ABAP Development](https://community.sap.com/t5/application-development-and-automation/ct-p/technology) (tag: `#abap_trial`) |