From d7a3d0593de8d83d09a831d274e149ade5aff96d Mon Sep 17 00:00:00 2001 From: agrasth Date: Sat, 5 Jul 2025 05:19:51 +0530 Subject: [PATCH] Added documentations for vscode and Jetbrains --- SUMMARY.md | 3 + .../jfrog-cli/cli-for-ide-setup/README.md | 179 ++++++ .../cli-for-ide-setup/jetbrains-cli.md | 523 ++++++++++++++++++ .../jfrog-cli/cli-for-ide-setup/vscode-cli.md | 358 ++++++++++++ 4 files changed, 1063 insertions(+) create mode 100644 jfrog-applications/jfrog-cli/cli-for-ide-setup/README.md create mode 100644 jfrog-applications/jfrog-cli/cli-for-ide-setup/jetbrains-cli.md create mode 100644 jfrog-applications/jfrog-cli/cli-for-ide-setup/vscode-cli.md diff --git a/SUMMARY.md b/SUMMARY.md index ae3d95f0..46bb5dc9 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -41,6 +41,9 @@ * [Count Contributing Developers](jfrog-applications/jfrog-cli/cli-for-jfrog-security/how-tos/count-contributing-developers.md) * [CLI for JFrog Distribution](jfrog-applications/jfrog-cli/cli-for-jfrog-distribution.md) * [CLI for JFrog Cloud Transfer](jfrog-applications/jfrog-cli/cli-for-jfrog-cloud-transfer.md) + * [CLI for IDE Setup](jfrog-applications/jfrog-cli/cli-for-ide-setup/README.md) + * [VSCode CLI Configuration](jfrog-applications/jfrog-cli/cli-for-ide-setup/vscode-cli.md) + * [JetBrains CLI Configuration](jfrog-applications/jfrog-cli/cli-for-ide-setup/jetbrains-cli.md) * [CLI Command Summaries](jfrog-applications/jfrog-cli/cli-command-summaries.md) * [JFrog CLI Plugins](jfrog-applications/jfrog-cli/cli-plugins/README.md) * [JFrog CLI Plugins Developer Guide](jfrog-applications/jfrog-cli/cli-plugins/developer-guide.md) diff --git a/jfrog-applications/jfrog-cli/cli-for-ide-setup/README.md b/jfrog-applications/jfrog-cli/cli-for-ide-setup/README.md new file mode 100644 index 00000000..c4fe4815 --- /dev/null +++ b/jfrog-applications/jfrog-cli/cli-for-ide-setup/README.md @@ -0,0 +1,179 @@ +# CLI for IDE Setup + +![](../../../.gitbook/assets/cli-ide-header.png) + + +JFrog CLI provides powerful commands to configure IDEs to use JFrog Artifactory as the repository source for extensions, plugins, and packages, streamlining the setup process for development teams by allowing them to easily configure their IDEs to use private or curated repositories hosted in Artifactory. + +## Overview + +The CLI IDE setup commands automate the configuration of popular IDEs to point to JFrog Artifactory repositories instead of public repositories, which enables organizations to: + +- **Centralize IDE Extensions Management**: Host and manage IDE extensions and plugins in Artifactory +- **Ensure Security and Compliance**: Use curated, scanned, and approved extensions from private repositories +- **Enable Offline Development**: Work with locally cached extensions without internet dependency +- **Standardize Development Environment**: Ensure all team members use the same approved set of extensions + +## Supported IDEs + +| IDE | Configuration Type | Commands | Platform Support | +|-----|-------------------|----------|------------------| +| **Visual Studio Code** | Extensions Gallery | `jf vscode config`
`jf vscode install` | Windows, macOS, Linux | +| **JetBrains IDEs** | Plugin Repository | `jf jetbrains config` | Windows, macOS, Linux | + +### JetBrains IDEs Support + +The JetBrains configuration command supports all JetBrains IDEs: +- IntelliJ IDEA +- PyCharm +- WebStorm +- PhpStorm +- RubyMine +- CLion +- DataGrip +- GoLand +- Rider +- Android Studio +- AppCode +- RustRover +- Aqua + +## How It Works + +### VSCode Configuration +The VSCode commands modify the IDE's configuration to point to JFrog Artifactory for extension downloads: + +1. **Configuration**: Updates `product.json` to change the extensions gallery URL +2. **Installation**: Downloads and installs extensions directly from Artifactory repositories + +### JetBrains Configuration +The JetBrains command configures all detected JetBrains IDEs: + +1. **Auto-Detection**: Scans for installed JetBrains IDEs on the system +2. **Configuration**: Updates `idea.properties` files to use Artifactory plugin repositories +3. **Backup**: Creates automatic backups before making changes + +## Prerequisites + +### Repository Setup +Before using the CLI commands, ensure you have: + +1. **JFrog Artifactory** with appropriate repository types: + - **VSCode**: Virtual or Remote repository of type `Generic` configured for VSCode extensions + - **JetBrains**: Virtual or Remote repository of type `Generic` configured for JetBrains plugins + +2. **Repository Configuration** in Artifactory: + - VSCode extensions repository with appropriate layout + - JetBrains plugins repository with JetBrains plugin repository layout + +3. **Access Permissions**: Appropriate permissions to read from the configured repositories + +### System Requirements + +#### Platform-Specific Requirements + +**macOS & Linux:** +- `sudo` access may be required for system-installed IDEs +- Commands will prompt for elevated privileges when needed + +**Windows:** +- "Run as Administrator" may be required for system-installed IDEs +- PowerShell execution policy must allow script execution + +## Quick Start + +### VSCode Setup +```bash +# Configure VSCode to use Artifactory extensions repository +jf vscode config --repo=vscode-extensions --artifactory-url=https://mycompany.jfrog.io/ + +# Install an extension from the configured repository +jf vscode install --publisher=microsoft --extension-name=vscode-python --repo=vscode-extensions +``` + +### JetBrains Setup +```bash +# Configure all JetBrains IDEs to use Artifactory plugins repository +jf jetbrains config --repo=jetbrains-plugins --artifactory-url=https://mycompany.jfrog.io/ +``` + +## Advanced Configuration + +### Using Server Configurations +If you have JFrog CLI server configurations set up, you can omit the `--artifactory-url` parameter: + +```bash +# Configure with default server +jf vscode config --repo=vscode-extensions + +# Configure with specific server +jf c use my-artifactory-server +jf jetbrains config --repo=jetbrains-plugins +``` + +### Repository URL Formats + +The CLI automatically constructs the appropriate repository URLs: + +**VSCode Extensions:** +``` +https://[artifactory-url]/artifactory/api/vscodeextensions/[repo-key]/_apis/public/gallery +``` + +**JetBrains Plugins:** +``` +https://[artifactory-url]/artifactory/api/jetbrainsplugins/[repo-key] +``` + +## Backup and Recovery + +### Automatic Backups +Both commands create automatic backups before making changes: + +- **VSCode**: Backups stored in `~/.jfrog/backup/ide/vscode/` +- **JetBrains**: Backups stored in `~/.jfrog/backup/ide/jetbrains/` + +### Manual Recovery +If you need to restore original settings: + +1. Locate the backup files in the backup directories +2. Copy the backup files back to their original locations +3. Restart the affected IDE + +## Troubleshooting + +### Common Issues + +**Permission Denied:** +- Run the command with elevated privileges (`sudo` on macOS/Linux, "Run as Administrator" on Windows) + +**IDE Not Detected:** +- Ensure the IDE is installed in standard locations +- Check if the IDE is running and close it before configuration + +**Repository Not Accessible:** +- Verify repository exists and is accessible +- Check network connectivity to Artifactory +- Ensure proper authentication is configured + +### Manual Configuration +If automatic configuration fails, each command provides manual setup instructions in the error output. + +## Security Considerations + +### File Modifications +The CLI commands modify system-level IDE configuration files. Always: +- Review backup files before making changes +- Test changes in a development environment first +- Ensure you have proper backups of IDE configurations + +### Repository Access +- Use access tokens instead of username/password when possible +- Ensure repository permissions are properly configured +- Consider using repository scanning and policies for enhanced security + +## Examples and Use Cases + +For detailed examples and specific use cases, see: +- [VSCode CLI Configuration](vscode-cli.md) +- [JetBrains CLI Configuration](jetbrains-cli.md) \ No newline at end of file diff --git a/jfrog-applications/jfrog-cli/cli-for-ide-setup/jetbrains-cli.md b/jfrog-applications/jfrog-cli/cli-for-ide-setup/jetbrains-cli.md new file mode 100644 index 00000000..33015cb4 --- /dev/null +++ b/jfrog-applications/jfrog-cli/cli-for-ide-setup/jetbrains-cli.md @@ -0,0 +1,523 @@ +# JetBrains CLI Configuration + +The JFrog CLI JetBrains command provides automated configuration for all JetBrains IDEs to use JFrog Artifactory as the plugin repository source, which enables organizations to centrally manage, curate, and distribute JetBrains plugins through their private Artifactory repositories. + +## Command Overview + +| Command | Purpose | Description | +|---------|---------|-------------| +| `jf jetbrains config` | Configure JetBrains IDEs | Updates all detected JetBrains IDEs to use Artifactory plugin repository | + +## jf jetbrains config + +Configure all installed JetBrains IDEs to use JFrog Artifactory as the plugin repository source. + +### Syntax + +```bash +jf jetbrains config --repo= [command options] +``` + +### Command Arguments + +| Argument | Description | +|----------|-------------| +| `--repo` | **[Mandatory]** JetBrains plugins repository key in Artifactory | + +### Command Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--artifactory-url` | **[Optional]** Artifactory server URL. If not provided, the default server configuration is used. | Uses configured default server. | + +### Examples + +#### Example 1: Basic Configuration +Configure all JetBrains IDEs to use an Artifactory plugins repository: + +```bash +jf jetbrains config --repo=jetbrains-plugins --artifactory-url=https://mycompany.jfrog.io/ +``` + +#### Example 2: Using Default Server Configuration +If you have a default JFrog CLI server configuration: + +```bash +jf jetbrains config --repo=jetbrains-plugins +``` + +#### Example 3: Platform-Specific Usage + +**macOS:** +```bash +jf jetbrains config --repo=jetbrains-plugins --artifactory-url=https://mycompany.jfrog.io/ +``` + +**Windows:** +```bash +jf jetbrains config --repo=jetbrains-plugins --artifactory-url=https://mycompany.jfrog.io/ +``` + +**Linux:** +```bash +jf jetbrains config --repo=jetbrains-plugins --artifactory-url=https://mycompany.jfrog.io/ +``` + +### Supported JetBrains IDEs + +The command automatically detects and configures all installed JetBrains IDEs: + +| IDE | Product Code | Description | +|-----|--------------|-------------| +| **IntelliJ IDEA** | `IntelliJIdea` | Java/Kotlin/Scala development | +| **PyCharm** | `PyCharm` | Python development | +| **WebStorm** | `WebStorm` | JavaScript/TypeScript development | +| **PhpStorm** | `PhpStorm` | PHP development | +| **RubyMine** | `RubyMine` | Ruby development | +| **CLion** | `CLion` | C/C++ development | +| **DataGrip** | `DataGrip` | Database tools | +| **GoLand** | `GoLand` | Go development | +| **Rider** | `Rider` | .NET development | +| **Android Studio** | `AndroidStudio` | Android development | +| **AppCode** | `AppCode` | iOS/macOS development | +| **RustRover** | `RustRover` | Rust development | +| **Aqua** | `Aqua` | Test automation | + +### How It Works + +1. **Auto-Detection**: Scans system for installed JetBrains IDEs +2. **Configuration Discovery**: Locates configuration directories for each IDE +3. **Backup Creation**: Creates timestamped backups of `idea.properties` files +4. **Configuration Update**: Adds or updates `idea.plugins.host` property +5. **Verification**: Confirms changes were applied successfully + +### Configuration Details + +The command modifies the `idea.properties` file for each detected IDE: + +**Before Configuration:** +```properties +# Empty or existing properties +``` + +**After Configuration:** +```properties +# JFrog Artifactory plugins repository +idea.plugins.host=https://mycompany.jfrog.io/artifactory/api/jetbrainsplugins/jetbrains-plugins +``` + +### Repository URL Format + +The command constructs the plugin repository URL in the following format: + +``` +https://[artifactory-url]/artifactory/api/jetbrainsplugins/[repo-key] +``` + +### File Locations + +The command modifies `idea.properties` files in the following locations: + +#### macOS +``` +~/Library/Application Support/JetBrains/[IDE][VERSION]/idea.properties +``` + +**Examples:** +- `~/Library/Application Support/JetBrains/IntelliJIdea2023.3/idea.properties` +- `~/Library/Application Support/JetBrains/PyCharm2023.3/idea.properties` +- `~/Library/Application Support/JetBrains/WebStorm2023.3/idea.properties` + +#### Windows +``` +%APPDATA%\JetBrains\[IDE][VERSION]\idea.properties +``` + +**Examples:** +- `%APPDATA%\JetBrains\IntelliJIdea2023.3\idea.properties` +- `%APPDATA%\JetBrains\PyCharm2023.3\idea.properties` +- `%APPDATA%\JetBrains\WebStorm2023.3\idea.properties` + +#### Linux +``` +~/.config/JetBrains/[IDE][VERSION]/idea.properties +``` + +**Examples:** +- `~/.config/JetBrains/IntelliJIdea2023.3/idea.properties` +- `~/.config/JetBrains/PyCharm2023.3/idea.properties` +- `~/.config/JetBrains/WebStorm2023.3/idea.properties` + +**Legacy Location (older installations):** +``` +~/.JetBrains/[IDE][VERSION]/idea.properties +``` + +## Prerequisites + +### Repository Configuration +Ensure your Artifactory repository is properly configured: + +1. **Repository Type**: Generic repository +2. **Layout**: Default or custom layout supporting JetBrains plugins +3. **Repository Key**: Unique identifier for the repository +4. **Permissions**: Read access for users/groups that will download plugins + +### JetBrains IDE Installation +- At least one JetBrains IDE must be installed on the system +- IDEs should be installed in standard locations for auto-detection +- IDEs should be closed during configuration for best results + +## Platform-Specific Requirements + +### macOS +- **Permissions**: Generally no special permissions required +- **File Access**: Ensure the user has read/write access to `~/Library/Application Support/JetBrains/` +- **IDE Locations**: IDEs typically installed in `/Applications/` + +### Windows +- **Permissions**: Usually no elevated permissions required +- **File Access**: Ensure access to `%APPDATA%\JetBrains\` +- **IDE Locations**: IDEs typically installed in `%LOCALAPPDATA%\JetBrains\Toolbox\apps\` or `%PROGRAMFILES%\JetBrains\` + +### Linux +- **Permissions**: Generally no special permissions required +- **File Access**: Ensure access to `~/.config/JetBrains/` or `~/.JetBrains/` +- **IDE Locations**: Various locations including `/opt/`, `~/Applications/`, or snap packages + +## Command Output + +### Successful Execution +``` +$ jf jetbrains config --repo=jetbrains-plugins --artifactory-url=https://mycompany.jfrog.io/ + +[Info] Configuring JetBrains IDEs plugin repository... +[Info] Validating repository... +[Info] Repository validation successful +[Info] Found 3 JetBrains IDE installation(s): +[Info] IntelliJ IDEA 2023.3 +[Info] PyCharm 2023.3 +[Info] WebStorm 2023.3 +[Info] Configuring IntelliJ IDEA 2023.3... +[Info] Backup created at: ~/.jfrog/backup/ide/jetbrains/idea.properties.backup.20240105-143022 +[Info] Added idea.plugins.host property +[Info] IntelliJ IDEA 2023.3 configured successfully +[Info] Configuring PyCharm 2023.3... +[Info] Backup created at: ~/.jfrog/backup/ide/jetbrains/idea.properties.backup.20240105-143023 +[Info] Added idea.plugins.host property +[Info] PyCharm 2023.3 configured successfully +[Info] Configuring WebStorm 2023.3... +[Info] Backup created at: ~/.jfrog/backup/ide/jetbrains/idea.properties.backup.20240105-143024 +[Info] Updated existing idea.plugins.host property +[Info] WebStorm 2023.3 configured successfully +[Info] Successfully configured 3 out of 3 JetBrains IDE(s) +[Info] Repository URL: https://mycompany.jfrog.io/artifactory/api/jetbrainsplugins/jetbrains-plugins +[Info] Please restart your JetBrains IDEs to apply changes +``` + +### No IDEs Found +``` +$ jf jetbrains config --repo=jetbrains-plugins + +[Info] Configuring JetBrains IDEs plugin repository... +[Error] No JetBrains IDEs found + +Manual JetBrains IDE Setup Instructions: +======================================= + +1. Close all JetBrains IDEs + +2. Locate your IDE configuration directory: + ~/Library/Application Support/JetBrains/[IDE][VERSION]/idea.properties + + Examples: + • IntelliJ IDEA: IntelliJIdea2023.3/idea.properties + • PyCharm: PyCharm2023.3/idea.properties + • WebStorm: WebStorm2023.3/idea.properties + +3. Open or create the idea.properties file in a text editor + +4. Add or modify the following line: + idea.plugins.host=https://mycompany.jfrog.io/artifactory/api/jetbrainsplugins/jetbrains-plugins + +5. Save the file and restart your IDE + +Repository URL: https://mycompany.jfrog.io/artifactory/api/jetbrainsplugins/jetbrains-plugins + +Supported IDEs: IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, RubyMine, CLion, DataGrip, GoLand, Rider, Android Studio, AppCode, RustRover, Aqua +``` + +## Backup and Recovery + +### Automatic Backups +The command automatically creates timestamped backups before making changes: + +**Backup Location:** +``` +~/.jfrog/backup/ide/jetbrains/idea.properties.backup.[TIMESTAMP] +``` + +**Backup Filename Format:** +``` +idea.properties.backup.YYYYMMDD-HHMMSS +``` + +**Example:** +``` +~/.jfrog/backup/ide/jetbrains/idea.properties.backup.20240105-143022 +``` + +### Manual Recovery +To restore original settings: + +1. **Locate Backup**: Find the appropriate backup file in `~/.jfrog/backup/ide/jetbrains/` +2. **Identify Target**: Determine which IDE configuration to restore +3. **Copy Backup**: Copy the backup file to the original location +4. **Restart IDE**: Restart the affected IDE to apply changes + +**Recovery Example:** +```bash +# Restore IntelliJ IDEA configuration +cp ~/.jfrog/backup/ide/jetbrains/idea.properties.backup.20240105-143022 \ + ~/Library/Application\ Support/JetBrains/IntelliJIdea2023.3/idea.properties +``` + +### Backup Management +Clean up old backups periodically: + +```bash +# Remove backups older than 30 days +find ~/.jfrog/backup/ide/jetbrains/ -name "*.backup.*" -mtime +30 -delete +``` + +## Troubleshooting + +### Common Issues and Solutions + +#### No JetBrains IDEs Detected + +**Symptoms:** +``` +Error: no JetBrains IDEs found +``` + +**Possible Causes:** +- IDEs not installed in standard locations +- IDEs installed via snap packages (Linux) +- Non-standard installation directories + +**Solutions:** +1. **Verify Installation**: Ensure at least one JetBrains IDE is installed +2. **Check Locations**: Verify IDEs are in standard installation directories +3. **Manual Configuration**: Use the manual setup instructions provided in the error output +4. **Custom Installations**: For non-standard installations, manually create configuration directories + +#### Configuration Directory Not Accessible + +**Symptoms:** +``` +Error: failed to create config directory +``` + +**Solutions:** +1. **Check Permissions**: Ensure user has write access to configuration directories +2. **Create Directories**: Manually create missing configuration directories +3. **File System Issues**: Check for file system problems or disk space + +#### Repository Validation Fails + +**Symptoms:** +``` +Error: repository validation failed +``` + +**Solutions:** +1. **Check Repository**: Verify repository exists in Artifactory +2. **Verify URL**: Ensure Artifactory URL is correct and accessible +3. **Authentication**: Ensure proper authentication is configured +4. **Network**: Check network connectivity to Artifactory + +#### Backup Creation Fails + +**Symptoms:** +``` +Error: failed to create backup +``` + +**Solutions:** +1. **Disk Space**: Ensure sufficient disk space for backup files +2. **Permissions**: Check write permissions to backup directory +3. **Directory Structure**: Ensure backup directory structure exists + +### Manual Configuration + +If automatic configuration fails, you can manually configure each IDE: + +#### Step-by-Step Manual Setup + +1. **Close IDE**: Ensure the IDE is completely closed +2. **Locate Configuration**: Find the IDE's configuration directory +3. **Create/Edit Properties File**: Open or create `idea.properties` +4. **Add Plugin Host**: Add the repository URL +5. **Save and Restart**: Save the file and restart the IDE + +#### Manual Configuration Example + +**File Location (macOS):** +``` +~/Library/Application Support/JetBrains/IntelliJIdea2023.3/idea.properties +``` + +**File Content:** +```properties +# JFrog Artifactory plugins repository +idea.plugins.host=https://mycompany.jfrog.io/artifactory/api/jetbrainsplugins/jetbrains-plugins + +# Other existing properties... +``` + +#### Verification +After manual configuration: + +1. **Start IDE**: Launch the configured IDE +2. **Check Plugins**: Go to Settings → Plugins +3. **Verify Repository**: Ensure plugins are loaded from Artifactory +4. **Test Installation**: Try installing a plugin from the repository + +## Advanced Usage + +### Batch Configuration +Configure multiple systems using scripts: + +```bash +#!/bin/bash +# Configure JetBrains IDEs across multiple machines + +REPO="jetbrains-plugins" +ARTIFACTORY_URL="https://mycompany.jfrog.io/" + +echo "Configuring JetBrains IDEs..." +jf jetbrains config --repo="$REPO" --artifactory-url="$ARTIFACTORY_URL" + +if [ $? -eq 0 ]; then + echo "✓ JetBrains IDEs configured successfully" + echo "Please restart your IDEs to apply changes" +else + echo "✗ Configuration failed" + exit 1 +fi +``` + +### CI/CD Integration +Include in deployment or onboarding scripts: + +```yaml +# GitHub Actions example +- name: Configure JetBrains IDEs + run: | + jf jetbrains config --repo=jetbrains-plugins --artifactory-url=${{ secrets.ARTIFACTORY_URL }} + +- name: Verify Configuration + run: | + # Check if configuration was applied + if grep -q "idea.plugins.host.*artifactory" ~/.config/JetBrains/*/idea.properties; then + echo "✓ JetBrains IDEs configured for Artifactory" + else + echo "✗ Configuration verification failed" + exit 1 + fi +``` + +### Configuration Validation +Verify configuration across multiple IDEs: + +```bash +#!/bin/bash +# Validate JetBrains IDE configuration + +EXPECTED_HOST="mycompany.jfrog.io" +CONFIG_BASE="$HOME/.config/JetBrains" + +echo "Validating JetBrains IDE configurations..." + +for ide_dir in "$CONFIG_BASE"/*; do + if [ -d "$ide_dir" ]; then + ide_name=$(basename "$ide_dir") + properties_file="$ide_dir/idea.properties" + + if [ -f "$properties_file" ]; then + if grep -q "idea.plugins.host.*$EXPECTED_HOST" "$properties_file"; then + echo "✓ $ide_name: Configured for Artifactory" + else + echo "✗ $ide_name: Not configured or incorrect URL" + fi + else + echo "? $ide_name: No properties file found" + fi + fi +done +``` + +### Team Onboarding Script +Automate developer environment setup: + +```bash +#!/bin/bash +# Developer onboarding script + +echo "=== JetBrains IDE Setup ===" +echo "Configuring IDEs to use company plugin repository..." + +# Configure JetBrains IDEs +jf jetbrains config --repo=jetbrains-plugins + +if [ $? -eq 0 ]; then + echo "" + echo "✓ JetBrains IDEs configured successfully!" + echo "" + echo "Next steps:" + echo "1. Restart all JetBrains IDEs" + echo "2. Go to Settings → Plugins in your IDE" + echo "3. Install approved company plugins" + echo "4. Contact IT if you encounter issues" +else + echo "" + echo "✗ Configuration failed!" + echo "Please contact IT support for manual setup" +fi +``` + +## Best Practices + +### Repository Management +1. **Curated Plugins**: Only include approved and tested plugins +2. **Version Control**: Maintain specific plugin versions for stability +3. **Security Scanning**: Scan plugins for vulnerabilities before inclusion +4. **Documentation**: Document approved plugins and their purposes + +### Team Workflow +1. **Standardization**: Use consistent repository keys across the organization +2. **Communication**: Inform team when repository configuration changes +3. **Testing**: Test plugin updates in development environment first +4. **Rollback Plan**: Maintain ability to rollback to previous configurations + +### Security +1. **Access Control**: Implement proper repository permissions +2. **Authentication**: Use access tokens for CLI authentication +3. **Network Security**: Use HTTPS for all communications +4. **Audit Trail**: Monitor repository access and plugin downloads + +### Maintenance +1. **Regular Updates**: Keep plugin repositories updated +2. **Cleanup**: Remove old plugin versions periodically +3. **Monitoring**: Monitor repository usage and performance +4. **Backup Management**: Regularly clean up old configuration backups + +### Plugin Installation Workflow +After configuration, developers can install plugins through their IDE: + +1. **Open IDE**: Launch any configured JetBrains IDE +2. **Access Plugins**: Go to Settings → Plugins (or Preferences → Plugins on macOS) +3. **Browse Repository**: Browse available plugins from the Artifactory repository +4. **Install Plugins**: Install approved plugins directly from the IDE +5. **Restart if Required**: Restart IDE if prompted after plugin installation \ No newline at end of file diff --git a/jfrog-applications/jfrog-cli/cli-for-ide-setup/vscode-cli.md b/jfrog-applications/jfrog-cli/cli-for-ide-setup/vscode-cli.md new file mode 100644 index 00000000..9d9934cf --- /dev/null +++ b/jfrog-applications/jfrog-cli/cli-for-ide-setup/vscode-cli.md @@ -0,0 +1,358 @@ +# VSCode CLI Configuration + +The JFrog CLI VSCode commands provide seamless integration between Visual Studio Code and JFrog Artifactory, allowing you to configure VSCode to use Artifactory repositories for extension management and install extensions directly from your private repositories. + +## Commands Overview + +The VSCode CLI functionality includes two main commands: + +| Command | Purpose | Description | +|---------|---------|-------------| +| `jf vscode config` | Configure VSCode | Updates VSCode to use Artifactory extensions repository | +| `jf vscode install` | Install Extensions | Downloads and installs extensions from Artifactory | + +## jf vscode config + +Configure Visual Studio Code to use JFrog Artifactory as the extensions repository source. + +### Syntax + +```bash +jf vscode config --repo= [command options] +``` + +### Command Arguments + +| Argument | Description | +|----------|-------------| +| `--repo` | **[Mandatory]** VSCode extensions repository key in Artifactory | + +### Command Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--artifactory-url` | **[Optional]** Artifactory server URL. If not provided, uses default server configuration | Uses configured default server | + +### Examples + +#### Example 1: Basic Configuration +Configure VSCode to use an Artifactory extensions repository: + +```bash +jf vscode config --repo=vscode-extensions --artifactory-url=https://mycompany.jfrog.io/ +``` + +#### Example 2: Using Default Server Configuration +If you have a default JFrog CLI server configuration: + +```bash +jf vscode config --repo=vscode-extensions +``` + +#### Example 3: Platform-Specific Usage + +**macOS (with system-installed VSCode):** +```bash +sudo jf vscode config --repo=vscode-extensions --artifactory-url=https://mycompany.jfrog.io/ +``` + +**Windows (Run as Administrator):** +```bash +jf vscode config --repo=vscode-extensions --artifactory-url=https://mycompany.jfrog.io/ +``` + +**Linux:** +```bash +sudo jf vscode config --repo=vscode-extensions --artifactory-url=https://mycompany.jfrog.io/ +``` + +### How It Works + +1. **Detection**: Automatically detects VSCode installation location +2. **Backup**: Creates backup of original `product.json` file +3. **Modification**: Updates `extensionsGallery.serviceUrl` in `product.json` +4. **Verification**: Confirms the changes were applied successfully + +### Configuration Details + +The command modifies the `product.json` file to change the extensions gallery URL: + +**Before:** +```json +{ + "extensionsGallery": { + "serviceUrl": "https://marketplace.visualstudio.com/_apis/public/gallery" + } +} +``` + +**After:** +```json +{ + "extensionsGallery": { + "serviceUrl": "https://mycompany.jfrog.io/artifactory/api/vscodeextensions/vscode-extensions/_apis/public/gallery" + } +} +``` + +### File Locations + +The command modifies the following files based on your platform: + +| Platform | File Location | +|----------|---------------| +| **macOS** | `/Applications/Visual Studio Code.app/Contents/Resources/app/product.json` | +| **Windows** | `%LOCALAPPDATA%\Programs\Microsoft VS Code\resources\app\product.json` | +| **Linux** | `/usr/share/code/resources/app/product.json` | + +## jf vscode install + +Install VSCode extensions directly from JFrog Artifactory repositories. + +### Syntax + +```bash +jf vscode install --publisher= --extension-name= --repo= [command options] +``` + +### Command Arguments + +| Argument | Description | +|----------|-------------| +| `--publisher` | **[Mandatory]** Extension publisher name | +| `--extension-name` | **[Mandatory]** Extension name | +| `--repo` | **[Mandatory]** VSCode extensions repository key in Artifactory | + +### Command Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--version` | **[Optional]** Specific extension version to install | Latest version | +| `--artifactory-url` | **[Optional]** Artifactory server URL. If not provided, uses default server configuration | Uses configured default server | + +### Examples + +#### Example 1: Install Latest Extension +Install the latest version of the Python extension: + +```bash +jf vscode install --publisher=ms-python --extension-name=python --repo=vscode-extensions +``` + +#### Example 2: Install Specific Version +Install a specific version of an extension: + +```bash +jf vscode install --publisher=ms-python --extension-name=python --version=2023.12.0 --repo=vscode-extensions +``` + +#### Example 3: Install with Explicit Server URL +```bash +jf vscode install --publisher=microsoft --extension-name=vscode-typescript --repo=vscode-extensions --artifactory-url=https://mycompany.jfrog.io/ +``` + +### How It Works + +1. **Validation**: Verifies extension exists in the Artifactory repository +2. **Download**: Downloads extension package (.vsix) from Artifactory +3. **Installation**: Uses VSCode CLI to install the extension +4. **Cleanup**: Removes temporary files after installation + +### Extension URL Format + +The command constructs download URLs in the following format: + +**Latest Version:** +``` +https://[artifactory-url]/artifactory/api/vscodeextensions/[repo-key]/_apis/public/gallery/publishers/[publisher]/extensions/[extension-name]/latest/vspackage +``` + +**Specific Version:** +``` +https://[artifactory-url]/artifactory/api/vscodeextensions/[repo-key]/_apis/public/gallery/publishers/[publisher]/extensions/[extension-name]/[version]/vspackage +``` + +## Prerequisites + +### VSCode CLI Requirements +The `jf vscode install` command requires the VSCode CLI (`code` command) to be available in your system PATH. + +**Installation:** +1. Open VSCode +2. Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) +3. Type "Shell Command: Install 'code' command in PATH" +4. Select and execute the command + +### Repository Configuration +Ensure your Artifactory repository is properly configured: + +1. **Repository Type**: Generic repository +2. **Layout**: Default or custom layout supporting VSCode extensions +3. **Permissions**: Read access for users/groups that will install extensions + +## Platform-Specific Requirements + +### macOS +- **System Installation**: Requires `sudo` for modifications +- **User Installation**: No special permissions required if VSCode is installed in `~/Applications/` +- **File Permissions**: Ensure the user has read/write access to VSCode installation directory + +### Windows +- **System Installation**: Requires "Run as Administrator" +- **User Installation**: May require elevated permissions depending on installation location +- **PowerShell**: Ensure PowerShell execution policy allows script execution + +### Linux +- **System Installation**: Requires `sudo` for modifications in `/usr/share/code/` +- **Snap Installation**: May require special handling for snap-packaged VSCode +- **File Permissions**: Ensure proper permissions on configuration files + +## Troubleshooting + +### Common Issues and Solutions + +#### Permission Denied Errors + +**Symptoms:** +``` +Error: insufficient permissions to modify VSCode configuration +``` + +**Solutions:** +- **macOS/Linux**: Run with `sudo` +- **Windows**: Run Command Prompt/PowerShell as Administrator +- **Alternative**: Install VSCode in user directory instead of system directory + +#### VSCode Not Detected + +**Symptoms:** +``` +Error: VSCode installation not found in standard locations +``` + +**Solutions:** +1. Verify VSCode is installed +2. Check if VSCode is installed in non-standard location +3. Use manual configuration instructions provided in error output + +#### Extension Installation Fails + +**Symptoms:** +``` +Error: failed to install extension via VSCode CLI +``` + +**Solutions:** +1. Ensure VSCode CLI (`code` command) is installed and accessible +2. Verify extension exists in the Artifactory repository +3. Check network connectivity to Artifactory +4. Ensure proper authentication is configured + +#### Repository Access Issues + +**Symptoms:** +``` +Error: repository validation failed +``` + +**Solutions:** +1. Verify repository exists and is accessible +2. Check repository permissions +3. Ensure proper authentication (access token, username/password) +4. Verify network connectivity to Artifactory + +### Manual Configuration + +If automatic configuration fails, you can manually configure VSCode: + +1. **Locate product.json file** (see file locations table above) +2. **Create backup** of the original file +3. **Edit the file** to change `extensionsGallery.serviceUrl` +4. **Restart VSCode** to apply changes + +**Manual Configuration Example:** +```json +{ + "extensionsGallery": { + "serviceUrl": "https://your-artifactory.com/artifactory/api/vscodeextensions/your-repo/_apis/public/gallery", + "cacheUrl": "https://vscode.blob.core.windows.net/gallery/index", + "itemUrl": "https://marketplace.visualstudio.com/items" + } +} +``` + +## Advanced Usage + +### Batch Extension Installation +Install multiple extensions using a script: + +```bash +#!/bin/bash +REPO="vscode-extensions" +ARTIFACTORY_URL="https://mycompany.jfrog.io/" + +# Array of extensions to install +extensions=( + "ms-python:python" + "ms-vscode:vscode-typescript" + "ms-dotnettools:csharp" + "golang:go" +) + +for ext in "${extensions[@]}"; do + IFS=':' read -r publisher name <<< "$ext" + echo "Installing $publisher.$name..." + jf vscode install --publisher="$publisher" --extension-name="$name" --repo="$REPO" --artifactory-url="$ARTIFACTORY_URL" +done +``` + +### CI/CD Integration +Configure VSCode in CI/CD environments: + +```yaml +# GitHub Actions example +- name: Configure VSCode for Artifactory + run: | + sudo jf vscode config --repo=vscode-extensions --artifactory-url=${{ secrets.ARTIFACTORY_URL }} + +- name: Install Required Extensions + run: | + jf vscode install --publisher=ms-python --extension-name=python --repo=vscode-extensions +``` + +### Validation Scripts +Verify VSCode configuration: + +```bash +#!/bin/bash +# Check if VSCode is configured to use Artifactory +PRODUCT_JSON="/Applications/Visual Studio Code.app/Contents/Resources/app/product.json" +EXPECTED_URL="your-artifactory.com" + +if grep -q "$EXPECTED_URL" "$PRODUCT_JSON"; then + echo "✓ VSCode is configured to use Artifactory" +else + echo "✗ VSCode is not configured for Artifactory" + exit 1 +fi +``` + +## Best Practices + +### Security +1. **Use Access Tokens**: Prefer access tokens over username/password +2. **Repository Permissions**: Configure least-privilege access to repositories +3. **Network Security**: Use HTTPS for all Artifactory communications +4. **Backup Configurations**: Always maintain backups of IDE configurations + +### Team Workflow +1. **Standardization**: Use the same repository keys across the team +2. **Documentation**: Document required extensions and versions +3. **Automation**: Include IDE configuration in onboarding scripts +4. **Testing**: Test configuration changes in development environment first + +### Repository Management +1. **Curation**: Only include approved and scanned extensions +2. **Versioning**: Maintain specific versions for production environments +3. **Cleanup**: Regularly clean up old extension versions +4. **Monitoring**: Monitor repository usage and access patterns \ No newline at end of file