Connecting JetBrains IDEs

Connect your JetBrains IDE (WebStorm, PhpStorm, etc.) to Workspace Manager workspaces for remote development using SSH-based deployment and remote interpreters.

Overview

JetBrains IDEs support remote development through SSH, allowing you to run your IDE locally while executing code and accessing files on remote workspaces. This provides a seamless development experience with full IDE features running against your remote workspace environment.

Prerequisites

• JetBrains IDE (2021.3 or later recommended)
• SSH access configured (see SSH documentation)
• Workspace running and accessible
• SSH key added to your WSM profile

Supported IDEs

All JetBrains IDEs with SSH deployment support can connect to Workspace Manager workspaces:

• WebStorm
• PhpStorm
• DataGrip

Configuration

JetBrains IDEs use SSH deployment to sync files between your local machine and remote workspace, while executing code remotely. This keeps your IDE running locally with full performance while leveraging the remote workspace environment.

Step 1: Configure the SSH Configuration

1. On your Workspace’s status page, expand the Connecting over SSH help panel. Find the Public SSH Access section, and note the SSH command, e.g. ssh cmcz32jqh000701y82yg2bo4t@wsm-ssh.example.com.
   • The part before @ is your workspace’s SSH username - cmcz32jqh000701y82yg2bo4t
   • The part after the @ is your workspace’s SSH hostname - wsm-ssh.example.com.
2. Open your JetBrains IDE
3. Go to Settings/Preferences → Tools → SSH Configurations
4. Click the + button to add a new SSH configuration
   • In the Host field, specify the SSH hostname found above (This will be the same for every workspace on your Workspace Manager server).
   • In the Username field, specify the workspace’s SSH username, found above.
   • In the Private key file field, specify the absolute path to the private key file on your system that corresponds to any of the public keys you’ve configured for your Workspace Manager profile. See SSH documentation for details.
   • If your private key is protected by a passphrase, enter it in the Passphrase field.
5. Click the Test Connection button to verify that the configuration is correct.

Step 2: Configure SSH Deployment

1. Open your JetBrains IDE
2. Go to Settings/Preferences → Build, Execution, Deployment → Deployment
3. Click the + button to add a new deployment configuration
4. Select SFTP as the type
5. Name your configuration (e.g., “My Workspace”)
6. Configure connectivity
   • Type: SFTP
   • SSH Configuration: The configuration you created in the previous step.
   • Root Path: Set to the root path of the application in the workspace, e.g. /home/web/project.
   • Web server URL: Set to the URL of your workspace.
7. Use the Test Connection button to ensure connectivity.

Step 3: Configure Path Mappings

In the Mappings tab:

1. Local path: Your project root directory (probably already populated)
2. Deployment path: The directory containing project files in the server, relative to the home directory (/home/web), not the absolute path (e.g., project, NOT /home/web/project).
3. Web path: /

Step 4: Configure Automatic Upload

To automatically sync files when you save:

1. Go to Settings/Preferences → Build, Execution, Deployment → Deployment → Options
2. Set Upload changed files automatically to the default server: On explicit save action
3. Optionally enable Upload external changes to sync files modified outside the IDE

Step 5: Start Developing

You’re now ready to develop remotely:

• Edit files locally - they’ll sync automatically
• Debugging works with remote processes using SSH port forwarding
• Terminal can connect to remote workspace

Deployment Tools

Manual Upload/Download

Right-click on files or folders:

• Deployment → Upload to [server name]
• Deployment → Download from [server name]
• Deployment → Sync with Deployed to [server name]

Compare with Remote

• Deployment → Compare with Deployed Version on [server name]
• View differences between local and remote files
• Merge changes as needed

Working with Remote Interpreters

Node.js (WebStorm)

Remote Node.js interpreter:

• Uses remote npm/yarn for package management
• Runs scripts defined in package.json remotely
• Debugs Node.js applications on workspace

PHP and Xdebug (PhpStorm)

PhpStorm can debug PHP applications running on remote workspaces using Xdebug over SSH port forwarding.

Prerequisites

• Xdebug installed and configured on the remote workspace
• SSH deployment configured (see steps above)
• Port forwarding enabled

Configure Xdebug on Remote Workspace

Ensure Xdebug is configured on your workspace. Add these settings to ~/html/.user.ini:

xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=1
xdebug.log=/home/web/logs/xdebug.log

The key is setting client_host to 127.0.0.1 since we’ll use SSH port forwarding.

.user.ini Location

The .user.ini file should be placed at ~/html/.user.ini on the remote workspace. This file allows per-directory PHP configuration without modifying the global php.ini.

Configure PhpStorm Debug Settings

1. Go to Settings → PHP → Debug
2. Set Debug port: 9003 (or your Xdebug port)
3. Enable Can accept external connections
4. Optionally disable Break at first line in PHP scripts for cleaner debugging

Configure Path Mappings

1. Go to Settings → PHP → Servers
2. Click + to add a new server
3. Set Name: Your workspace name
4. Set Host: Your workspace hostname
5. Enable Use path mappings
6. Map your local project root to the remote path (e.g., /home/developer/project)

Start Debugging

1. Open an SSH tunnel to forward the Xdebug port from the workspace back to your local machine:

   ssh -NR 9003:localhost:9003 cmcz32jqh000701y82yg2bo4t@wsm-ssh.example.com

   Keep this terminal open while debugging.
2. Click the Start Listening for PHP Debug Connections button (phone icon) in the toolbar
3. Set breakpoints in your PHP code
4. Trigger your PHP application (via browser, CLI, etc.)
5. PhpStorm will pause at your breakpoints

Troubleshooting Xdebug

Xdebug not connecting:

1. Verify port forwarding is active: ssh -R 9003:localhost:9003 wsm.my_workspace
2. Check Xdebug is loaded: ssh wsm.my_workspace "php -v" (should show Xdebug)
3. Verify Xdebug settings: ssh wsm.my_workspace "php -i | grep xdebug"
4. Check PhpStorm is listening (phone icon should be green)
5. Verify firewall isn’t blocking port 9003

Breakpoints not hit:

1. Verify path mappings are correct
2. Check that Xdebug client_host is set to 127.0.0.1
3. Ensure xdebug.start_with_request=yes is set
4. Try adding XDEBUG_SESSION=1 to your request

Connection timeout:

1. Check SSH tunnel is active
2. Verify remote Xdebug port matches local port (9003)
3. Test port forwarding: ssh -R 9003:localhost:9003 wsm.my_workspace "nc -zv 127.0.0.1 9003"

Other Languages

Similar remote interpreter/SDK configuration available for:

• Ruby (RubyMine)
• Go (GoLand)
• C/C++ (CLion)

Port Forwarding

JetBrains IDEs automatically handle port forwarding for remote development:

1. When you run a web server or service on the remote workspace
2. The IDE detects the port and offers to forward it
3. Click the notification to open in your local browser
4. Access remote services as if they were local

You can also manually configure port forwarding:

• Tools → Deployment → Configuration → SSH tab
• Add port forwarding rules as needed

See Port Forwarding documentation for more details.

File Sync Best Practices

• Enable automatic upload: Ensures remote files stay in sync
• Use explicit save: Prevents excessive sync operations
• Review sync conflicts: Check for conflicts before overwriting
• Sync before running: Ensure latest code is deployed before execution

Troubleshooting

Cannot Connect to Remote Host

Symptoms: Connection timeout or refused

Solutions:

1. Verify workspace is running in WSM dashboard
2. Test SSH connection from terminal: ssh wsm.my_workspace
3. Update SSH config: wsm-cli ssh config-update
4. Check firewall settings
5. Verify SSH key is added to WSM profile

Authentication Failed

Symptoms: Permission denied (publickey)

Solutions:

1. Verify SSH key path in IDE settings
2. Check key permissions: chmod 600 ~/.ssh/id_ed25519
3. Ensure key is added to WSM profile
4. Test key with: ssh -i ~/.ssh/id_ed25519 wsm.my_workspace
5. Check SSH agent is running: ssh-add -l

Files Not Syncing

Symptoms: Changes not appearing on remote workspace

Solutions:

1. Check automatic upload is enabled
2. Manually upload: Right-click → Deployment → Upload
3. Review excluded paths in deployment settings
4. Check deployment logs: Tools → Deployment → View Deployment Logs
5. Verify path mappings are correct

Port Forwarding Not Working

Symptoms: Cannot access remote web services

Solutions:

1. Verify service is running on remote workspace
2. Check port forwarding settings in deployment configuration
3. Manually add port forwarding rule
4. Test port forwarding from terminal: ssh -L 8080:localhost:8080 wsm.my_workspace
5. Check firewall rules on workspace

Gateway Connection Issues

Symptoms: Cannot establish connection

Solutions:

1. Ensure SSH connection works from terminal first
2. Verify workspace has sufficient resources
3. Check network connectivity and firewall settings

Slow Performance

Symptoms: IDE is sluggish, file operations are slow

Solutions:

1. Exclude large directories from sync (node_modules, build, etc.)
2. Use Gateway instead of file sync for large projects
3. Disable unnecessary plugins
4. Increase IDE memory: Help → Change Memory Settings
5. Check network latency to workspace

Host Key Verification Failed

Symptoms: Host key has changed warning

Solutions:

1. Remove old host key: ssh-keygen -R wsm.my_workspace
2. Reconnect and accept new host key
3. Update known_hosts file
4. Verify workspace hasn’t been recreated (new host key)

Advanced Configuration

Custom SSH Options

Add custom SSH options in deployment configuration:

1. Go to Settings → Deployment → Configuration
2. Select your deployment → SSH tab
3. Add custom SSH options as needed

Multiple Workspaces

Configure multiple deployment configurations for different workspaces:

1. Create separate deployment configurations for each workspace
2. Set one as default for automatic operations
3. Switch between configurations as needed
4. Use different run configurations for different workspaces

Shared Team Settings

Share deployment configurations with your team:

1. Export deployment settings: File → Manage IDE Settings → Export Settings
2. Commit .idea/deployment.xml to version control (remove sensitive data)
3. Team members import settings or check out from VCS

Related Documentation

• SSH Access - Configure SSH keys and connection
• Connecting Visual Studio Code - VS Code remote development
• Port Forwarding - Forward ports from workspaces
• File Sync with rsync - Alternative file synchronization

Additional Resources

• JetBrains Remote Development Documentation
• SSH Deployment Guide