When to Use Manual Installation
Manual installation using a VSIX file is useful when:
- Your organization blocks VS Code Marketplace access
- You need to install a specific version
- You’re testing a pre-release version
- You’re in an air-gapped environment
- You want to distribute the extension internally
Obtaining the VSIX File
Download from Publisher
Contact BTSS Corp for the VSIX file:
Building from Source
If you have access to the source code:
# Clone the repository
git clone [repository-url]
cd koala-data-explorer-ext
# Install dependencies
npm install
# Build the extension
npm run vscode:prepublish
# Package the extension
npx vsce package
.vsix file in the project directory.
Installation Methods
Method 1: Using VS Code UI
- Open VS Code
- Go to Extensions view (
Ctrl+Shift+X)
- Click the … menu at the top of Extensions view
- Select Install from VSIX…
- Browse to your
.vsix file
- Select the file and click Install
- Reload VS Code when prompted
Method 2: Using Command Palette
- Open Command Palette (
Ctrl+Shift+P or Cmd+Shift+P)
- Type: Extensions: Install from VSIX…
- Select the command
- Browse to your
.vsix file
- Confirm installation
Method 3: Using Command Line
# Basic installation
code --install-extension koala-data-explorer-1.1.0.vsix
# Force installation (overwrites existing)
code --install-extension koala-data-explorer-1.1.0.vsix --force
# Install for VS Code Insiders
code-insiders --install-extension koala-data-explorer-1.1.0.vsix
Method 4: Manual Copy (Advanced)
For system-wide installation or automation:
# Windows
copy koala-data-explorer-1.1.0.vsix "%USERPROFILE%\.vscode\extensions\"
cd "%USERPROFILE%\.vscode\extensions\"
tar -xf koala-data-explorer-1.1.0.vsix
# macOS/Linux
cp koala-data-explorer-1.1.0.vsix ~/.vscode/extensions/
cd ~/.vscode/extensions/
unzip koala-data-explorer-1.1.0.vsix -d btss-corp.koala-data-explorer-1.1.0
Verification
After installation, verify the extension:
Check Extension List
- Open Extensions view (
Ctrl+Shift+X)
- Search for “Koala”
- Verify “Koala Data Explorer” appears with correct version
Test Command Availability
- Open Command Palette (
Ctrl+Shift+P)
- Type: “Koala”
- Verify you see “Koala Data Explorer: Open SQL Query Editor”
Check Installation Directory
# List installed extensions
code --list-extensions
# Should include:
# btss-corp.koala-data-explorer
Offline Installation
For completely offline environments:
1. Prepare Installation Package
On a machine with internet access:
# Download extension and dependencies
code --install-extension btss-corp.koala-data-explorer
cd ~/.vscode/extensions/
tar -czf koala-complete.tar.gz btss-corp.koala-data-explorer-*
2. Transfer and Install
On the offline machine:
# Extract to extensions folder
cd ~/.vscode/extensions/
tar -xzf koala-complete.tar.gz
# Restart VS Code
Managing Multiple Versions
Installing Specific Versions
Keep multiple VSIX files with version numbers:
koala-data-explorer-1.0.0.vsix
koala-data-explorer-1.0.1.vsix
koala-data-explorer-1.1.0.vsix
Switching Versions
- Uninstall current version
- Install desired version from VSIX
- Reload VS Code
Version Downgrade
# Uninstall current version
code --uninstall-extension btss-corp.koala-data-explorer
# Install older version
code --install-extension koala-data-explorer-1.0.0.vsix --force
Troubleshooting Manual Installation
VSIX File Not Recognized
If VS Code doesn’t recognize the VSIX file:
- Ensure file extension is
.vsix (not .zip)
- Check file isn’t corrupted (try re-downloading)
- Verify file permissions allow reading
Installation Permissions Error
On Windows:
# Run VS Code as Administrator
Start-Process code -Verb RunAs
# Fix permissions
chmod 644 koala-data-explorer-1.1.0.vsix
Extension Not Loading After Install
- Fully restart VS Code (not just reload)
- Check for conflicts with other extensions
- Review errors in Help → Toggle Developer Tools
- Clear extension cache:
rm -rf ~/.vscode/extensions/.obsolete
Dependency Issues
If the extension fails due to missing dependencies:
- Ensure VS Code version >= 1.74.0
- Install Visual C++ Redistributable (Windows)
- Check Node.js native modules are compatible
Deployment Automation
For IT Administrators
Deploy to multiple machines using scripts:
PowerShell (Windows):
# Deploy to all users
$vsixPath = "\\server\share\koala-data-explorer-1.1.0.vsix"
$users = Get-ChildItem "C:\Users" -Directory
foreach ($user in $users) {
$codePath = Join-Path $user.FullName ".vscode\extensions"
if (Test-Path $codePath) {
code --install-extension $vsixPath --force
}
}
#!/bin/bash
# Deploy to current user
VSIX_PATH="/path/to/koala-data-explorer-1.1.0.vsix"
for user in /home/*; do
if [ -d "$user/.vscode" ]; then
sudo -u $(basename "$user") code --install-extension "$VSIX_PATH"
fi
done
Using Configuration Management
Ansible Playbook:
- name: Install Koala Data Explorer
hosts: workstations
tasks:
- name: Copy VSIX file
copy:
src: koala-data-explorer-1.1.0.vsix
dest: /tmp/
- name: Install extension
shell: code --install-extension /tmp/koala-data-explorer-1.1.0.vsix
become_user: "{{ ansible_user }}"
Post-Installation Configuration
After manual installation:
- Verify Installation: Check extension appears in list
- Configure Settings: Adjust timeout, logging, etc.
- Set Up Connection: Add Oracle Fusion credentials
- Activate License: Enter license key if you have one
Security Considerations
When installing manually:
Only install VSIX files from trusted sources. Verify the publisher and file integrity before installation.
Verify File Integrity
Check SHA256 hash if provided:
# Windows
certutil -hashfile koala-data-explorer-1.1.0.vsix SHA256
# macOS/Linux
sha256sum koala-data-explorer-1.1.0.vsix
Scan for Malware
Run security scans before installation:
# Example with ClamAV
clamscan koala-data-explorer-1.1.0.vsix
Next Steps
After successful manual installation:
