Tomcat AI Deployer for VS Code

中文文档

AI-assisted Tomcat control for VS Code: streaming log explanations, one-click deploys, and browser reloads.

Features

• Full Server Logs Monitoring
  Monitor All+ Tomcat logs in real-time with syntax highlighting

• Java Web Apps Support
  Detect and manage Java EE/Tomcat webapp projects, including multi-root workspace app discovery and deployment.

• Build Strategies
  Four build strategies Local, Maven, Gradle, and Eclipse to choose from

• AI Explanations (Streaming)
  WARN/ERROR logs are auto-explained via your configured AI provider, with live streaming output, local-endpoint fallback, and automatic navigation to the offending file/line.

• Save/Ctrl+S Deployment Automatically deploy your project every time you save a file or press Ctrl+S/Cmd+S

• Built-in Debugging
  Java-specific syntax coloring in output channel with organized error messages

• Browser Automation
  Automate browser testing across multiple browsers seamlessly.

• Localized UI (English/Chinese)
  Extension commands, status bar text, and prompts are localized with a new language switch that follows VS Code on first run.

• Multi-Project Workspace Awareness
  Detects multiple projects in the same workspace and handles per-folder webapp deployment and workspace-specific settings smartly.

• Instance Management UI and Settings Window
  Manage all Tomcat instances in one place: start, stop, kill, refresh, open in browser, and configure Tomcat/Java homes and HTTP ports from a unified view.

Installation

1. Open VS Code
2. Launch Extensions View (Ctrl+Shift+X)
3. Search for Al-rimi.tomcat
4. Click Install

Command line:

code --install-extension Al-rimi.tomcat

Usage

The Editor Button and Status Bar are only visible when the selected workspace folder contains a detected Java EE project (multi-root workspace support included).

• In multi-project workspaces, each folder is detected independently, and app commands are scoped to the active project.
• View UI convention now reflects the shared tree + per-project snippets in the same panel.

See the following detection criteria below for details.

public static isJavaEEProject(): boolean {
    const workspaceFolders = vscode.workspace.workspaceFolders;

    // Check 0: Workspace must be open
    if (!workspaceFolders) {
        return false;
    }

    const rootPath = workspaceFolders[0].uri.fsPath;
    const webInfPath = path.join(rootPath, 'src', 'main', 'webapp', 'WEB-INF');

    // Check 1: Look for WEB-INF directory in the standard structure
    if (fs.existsSync(webInfPath)) {
        return true;
    }

    // Check 2: Check for presence of deployment descriptor (web.xml)
    if (fs.existsSync(path.join(webInfPath, 'web.xml'))) {
        return true;
    }

    const pomPath = path.join(rootPath, 'pom.xml');

    // Check 3: Look for WAR packaging in Maven project
    if (
        fs.existsSync(pomPath) &&
        fs.readFileSync(pomPath, 'utf-8').includes('<packaging>war</packaging>')
    ) {
        return true;
    }

    const gradlePath = path.join(rootPath, 'build.gradle');

    // Check 4: Look for Java EE-related keywords in Gradle config
    if (
        fs.existsSync(gradlePath) &&
        fs.readFileSync(gradlePath, 'utf-8').match(/(tomcat|jakarta|javax\.ee)/i)
    ) {
        return true;
    }

    const targetPath = path.join(rootPath, 'target');

    // Check 5: Look for compiled artifacts (.war or .ear) in target folder
    if (
        fs.existsSync(targetPath) &&
        fs.readdirSync(targetPath).some(file => file.endsWith('.war') || file.endsWith('.ear'))
    ) {
        return true;
    }

    // If none match, project is not considered a Java EE project
    return false;
}

Instances & Apps View

The Instances View is now a full management center for instances and apps. It provides a real-time tree of running and saved Tomcat instances, plus app entries for deploy, run, refresh, and delete.

You can:

• start/stop/kill Tomcat instances
• manage Tomcat/Java homes, HTTP ports, and per-instance settings
• create new apps and scaffold templates from the + action
• deploy and run apps with one click
• delete deployed apps and clean project artifacts
• open deployed apps in browser and track PID/port/version/workspace

All controls are accessible from one place, with quick actions in the tree and context menu commands to keep workflow fast.

Editor Button

Click the Tomcat icon in the editor title bar to deploy your project.

Status Bar

Click the Tomcat status in the bottom bar to toggle auto deploy modes.

Configuration

Access via Ctrl+, → Search "Tomcat"

| Setting | Default | Description | | ----------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | tomcat.language | auto | Extension UI language (auto, en, zh-CN). On first run, auto follows VS Code's display language. | | tomcat.buildType | Local | Default build strategy for deployments (Local, Maven, Gradle, Eclipse) | | tomcat.autoDeployMode | Disable | Auto-deploy triggers (Disable, On Save, On Shortcut) | | tomcat.browser | Google Chrome | Browser for app launch & debug (Disable, Google Chrome, Microsoft Edge, Firefox, Safari, Brave, Opera) | | tomcat.port | 8080 | Tomcat server listen port (valid range: 1024-49151) | | tomcat.ports | [] | Saved HTTP ports for quick selection (array of numbers, preserved per workspace) | | tomcat.homes | [] | List of available Tomcat installation paths for multi-version management | | tomcat.javaHomes | [] | List of configured Java homes (array of strings); tomcat.javaHome is the active entry | | tomcat.base | | Path to `CATALINA_BASE` (conf/webapps/logs). Defaults to `tomcat.home` if not set. | | `tomcat.protectedWebApps` | `["ROOT", "docs", "examples", "manager", "host-manager"]` | List of protected web apps during cleanup operations | | `tomcat.logLevel` | `INFO` | Minimum log level to display (`DEBUG`, `INFO`, `SUCCESS`, `HTTP`, `APP`, `WARN`, `ERROR`) | | `tomcat.showTimestamp` | `true` | Whether to include timestamps in log messages | | `tomcat.autoReloadBrowser` | `true` | Whether to automatically reload the browser after deployment. Disable this option if having issues with the browser reloading. | | `tomcat.logEncoding` | `utf8` | Encoding for Tomcat logs (`utf8`, `ascii`, `utf-8`, `utf16le`, `utf-16le`, `ucs2`, `ucs-2`, `base64`, `base64url`, `latin1`, `binary`, `hex`) | | `tomcat.ai.provider` | `none` | AI provider for streaming explanations (`none`, `local`, `aliyun-dashscope`, `baichuan`, `zhipu`, `deepseek`, `custom`). | | `tomcat.ai.endpoint` | `http://127.0.0.1:11434/api/chat` | Full HTTP endpoint for AI chat/completions. | | `tomcat.ai.model` | `qwen2.5:7b` | Model identifier sent to the configured AI endpoint. | | `tomcat.ai.apiKey` | | Optional bearer token for hosted providers. | | tomcat.ai.localStartCommand | ollama serve | Command to launch the local AI service when the endpoint is unreachable. |

tomcat.home and tomcat.javaHome are now auto-detected and hidden from user settings. AI explanations are automatic for WARN/ERROR logs; local AI auto-starts only for localhost endpoints when unreachable.

Requirements

• Runtime:
  • JDK 11+
  • Apache Tomcat 9+
• Build Tools (optional):
  • Maven 3.6+ or Gradle 6.8+ (if using Maven or Gradle build types)

Developer Documentation

For technical implementation details and contribution guidelines, see:

• System Architecture
• Development Guide
• Testing Strategy

Known Issues

• Browser Compatibility for Auto-Reload

  Some browsers may not support automatic page reloading (click to expand)

  The extension uses the Chrome Debug Protocol (CDP) to reload pages after deployment. Currently supported browsers include:

  • Google Chrome
  • Microsoft Edge
  • Brave
  • Opera

  Unsupported Browsers:

  • Firefox
  • Safari

  These lack CDP support and will not auto-reload.

• Debug Mode Launch Failures

  Occasional issues launching browsers in debug mode (click to expand)

  Even supported browsers might fail to launch in debug mode due to system configurations. The extension uses this command template:

  start chrome.exe --remote-debugging-port=9222 http://localhost:8080/app-name
  

  Common solutions:

  1. Verify browser executable path in system PATH
  2. Ensure no other instances are using port 9222
  3. Update browser to latest version

  If issues persist, disable tomcat.autoReloadBrowser in settings.

What's New in 4.2.5

This release focuses on path handling, logging visibility, performance improvements, and localization enhancements.

• Path Handling: Fixed issues with Java/Tomcat installations in paths containing spaces (e.g., Program Files).
• Build Logging: Maven and other build tool output is now properly displayed in the VS Code output panel.
• Performance: Optimized configuration updates and tree view operations for better responsiveness.
• Java Home Management: Fixed removal of Java home entries to properly refresh the UI.
• Localization: Improved i18n system with build-time bundling, runtime fallback handling, and validation scripts.
• Reliability: Fixed extension activation issues caused by missing translation data in bundled builds.

See the full changelog for details.

License: MIT • 💖 Support: Star our GitHub Repo • VScode Marketplace