sap-cap-debugger

v1.0.4

Published

3 months ago

NPX tool for remote debugging SAP CAP applications on Cloud Foundry

0High
0Medium
0Low

hatrigt

sap cap cloud-application-programming debugging remote-debugging cloud-foundry btp nodejs debugger npx

SAP CAP Remote Debugger

Professional NPX tool for remote debugging SAP CAP applications on Cloud Foundry

A production-ready solution for debugging SAP Cloud Application Programming (CAP) applications deployed on SAP Business Technology Platform (BTP) Cloud Foundry. This tool simplifies remote debugging setup with automatic port assignment, multi-app support, and direct DevTools integration.

💡 Command Names: You can use either npx sap-cap-debugger or cds-debug (if installed globally). Both commands work identically throughout this documentation.

🚀 Quick Start

# Debug an application (interactive selection if no name provided)
npx sap-cap-debugger my-cap-app

# Or install globally
npm install -g sap-cap-debugger
cds-debug my-cap-app

✨ Features

🎯 One-Command Setup - Complete remote debugging setup with a single command
🚀 Multi-App Support - Debug multiple applications simultaneously with different ports
🔌 Auto Port Assignment - Automatically assigns available ports for each app
🧹 Smart Cleanup - Interactive cleanup for specific apps or all sessions
📊 Status Monitoring - Real-time status checking with active/inactive session indicators
🔧 Multiple Debuggers - Support for Chrome DevTools, VS Code, or both
📱 Interactive Mode - Interactive app selection when no app name is provided
⚡ Production-Ready - Proper error handling, logging, and session management

📋 Prerequisites

Node.js 14.0.0 or higher
Cloud Foundry CLI installed and configured
SAP CAP application deployed on Cloud Foundry
SSH access enabled for your Cloud Foundry space

🛠️ Installation

Option 1: NPX (Recommended)

Run directly without installation:

npx sap-cap-debugger my-app-name

Option 2: Global Installation

npm install -g sap-cap-debugger

# Use either command name
cds-debug my-app-name
# or
npx sap-cap-debugger my-app-name

Option 3: Local Installation

npm install --save-dev sap-cap-debugger
npx sap-cap-debugger my-app-name

📖 Usage

Basic Commands

# Debug an application (interactive selection if no name provided)
npx sap-cap-debugger
cds-debug

# Debug specific application
npx sap-cap-debugger my-cap-app
cds-debug my-cap-app

# Debug with custom port
npx sap-cap-debugger my-app --port 9230
cds-debug my-app --port 9230

# Debug with VS Code debugger
npx sap-cap-debugger my-app --debugger vscode
cds-debug my-app --debugger vscode

# Check debugging status
npx sap-cap-debugger status
cds-debug status

# Clean up debugging sessions
npx sap-cap-debugger cleanup
cds-debug cleanup

# List available applications
npx sap-cap-debugger apps
cds-debug apps

# Show help
npx sap-cap-debugger --help
cds-debug --help

Command Options

| Option | Description | Default | |--------|-------------|---------| | --port, -p | Debug port number | Auto-assigned (9229+) | | --debugger, -d | Debugger type | chrome | | --verbose, -v | Enable verbose logging | false | | --help, -h | Display help for command | - |

Debugger Types: chrome, vscode, both

Examples

# Debug with Chrome DevTools (default)
npx sap-cap-debugger collaboration-srv

# Debug with VS Code
npx sap-cap-debugger collaboration-srv --debugger vscode

# Debug with both debuggers
npx sap-cap-debugger collaboration-srv --debugger both

# Debug with custom port
npx sap-cap-debugger collaboration-srv --port 9230

# Verbose output
npx sap-cap-debugger collaboration-srv --verbose

# Interactive app selection
npx sap-cap-debugger

🚀 Multi-App Debugging

The tool supports debugging multiple applications simultaneously:

Each app gets its own local port (auto-assigned starting from 9229)
Each app has its own SSH tunnel to its container
Each app's inspector runs on port 9229 in its own container
Chrome DevTools opens directly to the correct debugging session for each app

Example:

# Start debugging first app
npx sap-cap-debugger app1-srv

# Start debugging second app (gets port 9230 automatically)
npx sap-cap-debugger app2-srv

# Check status of all sessions
npx sap-cap-debugger status

🔧 VS Code Configuration

For VS Code debugging, ensure your .vscode/launch.json contains:

{
  "version": "1.0.0",
  "configurations": [
    {
      "name": "Debug CAP App Remote",
      "type": "node",
      "request": "attach",
      "address": "127.0.0.1",
      "port": 9229,
      "restart": true,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/home/vcap/app",
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}

Note: Update the port value if you're using a custom port or debugging multiple apps.

🎯 How It Works

The tool uses the kill -USR1 approach to enable the Node.js inspector on an already running process, which bypasses networking issues that occur with direct SSH tunneling.

Process Flow

Prerequisites Check - Verifies CF CLI and required tools
App Verification - Checks app status and starts if needed
SSH Setup - Enables SSH access for the application (if not already enabled)
Port Assignment - Automatically assigns an available port (or uses specified port)
Process Detection - Finds the Node.js process PID in the app container
Tunnel Creation - Creates SSH tunnel forwarding local port → remote port 9229
Debug Enablement - Enables debugging with kill -USR1 (always uses port 9229 on remote)
DevTools Launch - Fetches inspector URL and opens Chrome DevTools directly
Session Management - Tracks and manages multiple debugging sessions

🔍 Status Monitoring

Check the status of all debugging sessions:

npx sap-cap-debugger status
cds-debug status

The status command displays:

🟢 Active sessions - Sessions with active SSH tunnels
🔴 Inactive sessions - Stale sessions that can be cleaned up
Port numbers, Node.js PIDs, and session start times

🧹 Cleanup

Clean up debugging sessions interactively:

# Interactive cleanup (select specific sessions or all)
npx sap-cap-debugger cleanup
cds-debug cleanup

# Clean up specific app
npx sap-cap-debugger cleanup my-app-name
cds-debug cleanup my-app-name

The cleanup command:

Shows active and inactive sessions
Allows selection of specific sessions or all
Kills SSH tunnel processes
Frees up debugging ports
Removes session records

🚨 Troubleshooting

SSH Tunnel Connection Refused

# Check if the application is running
npx sap-cap-debugger status

# Check application logs
cf logs my-app-name --recent

# Try again
npx sap-cap-debugger my-app-name

Application Not Starting

# Check application logs
cf logs my-app-name --recent

# Verify Node.js path
cf ssh my-app-name -c "which node"

# Check application structure
cf ssh my-app-name -c "ls -la /home/vcap/app"

Debugger Not Connecting

# Verify SSH tunnel
npx sap-cap-debugger status

# Check if process is still running
cf ssh my-app-name -c "ps aux | grep node"

# Clean up and retry
npx sap-cap-debugger cleanup
npx sap-cap-debugger my-app-name

Manual Debugging Steps

If the automated setup fails, use the manual command:

npx sap-cap-debugger manual my-app-name

This will show step-by-step manual instructions.

🏗️ Development

Building from Source

# Clone the repository
git clone https://github.com/HatriGt/sap-cap-debugger.git
cd sap-cap-debugger

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

Project Structure

src/
├── bin/
│   └── cap-debug.ts          # CLI entry point
├── lib/
│   ├── cap-debugger.ts       # Main debugger class
│   ├── cloudfoundry.ts       # CF operations
│   ├── port-manager.ts       # Port management
│   ├── ssh-tunnel.ts         # SSH tunnel management
│   └── debugger-launcher.ts  # Debugger launching
├── utils/
│   ├── logger.ts             # Logging utilities
│   └── command.ts            # Command execution
└── types/
    └── index.ts              # TypeScript types

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork and clone the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test: npm test && npm run lint
Commit your changes: git commit -m "feat: Add amazing feature"
Push to the branch: git push origin feature/amazing-feature
Create a Pull Request

Commit Convention

We follow Conventional Commits:

feat: - New features
fix: - Bug fixes
docs: - Documentation changes
style: - Code style changes
refactor: - Code refactoring
test: - Adding or updating tests
chore: - Maintenance tasks

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Based on the SAP Community Blog approach
Inspired by the SAP Cloud SDK remote debugging guide
Built for the SAP CAP community

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

🔗 Related Projects

Note: This tool works with SAP CAP applications of all versions (v7, v8, and later). While CAP v8+ includes the built-in cds debug command, this tool provides additional features like multi-app debugging, automatic port assignment, and direct DevTools integration that may be useful for advanced debugging scenarios.