> ## Documentation Index
> Fetch the complete documentation index at: https://docs.btsscorp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual Installation

> Install Koala Data Explorer from a VSIX file

## 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:

* **Support Portal**: [Submit a request](https://btsscorp.freshdesk.com/support/tickets/new) (recommended)
* **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) (alternative)
* **Subject**: Request Koala Data Explorer VSIX
* Specify the version you need

### Building from Source

If you have access to the source code:

```bash theme={null}
# 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
```

This creates a `.vsix` file in the project directory.

## Installation Methods

### Method 1: Using VS Code UI

1. Open VS Code
2. Go to Extensions view (`Ctrl+Shift+X`)
3. Click the **...** menu at the top of Extensions view
4. Select **Install from VSIX...**
5. Browse to your `.vsix` file
6. Select the file and click **Install**
7. Reload VS Code when prompted

### Method 2: Using Command Palette

1. Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
2. Type: **Extensions: Install from VSIX...**
3. Select the command
4. Browse to your `.vsix` file
5. Confirm installation

### Method 3: Using Command Line

```bash theme={null}
# 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:

```bash theme={null}
# 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

1. Open Extensions view (`Ctrl+Shift+X`)
2. Search for "Koala"
3. Verify "Koala Data Explorer" appears with correct version

### Test Command Availability

1. Open Command Palette (`Ctrl+Shift+P`)
2. Type: "Koala"
3. Verify you see **"Koala Data Explorer: Open SQL Query Editor"**

### Check Installation Directory

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

1. Uninstall current version
2. Install desired version from VSIX
3. Reload VS Code

### Version Downgrade

```bash theme={null}
# 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:

```powershell theme={null}
# Run VS Code as Administrator
Start-Process code -Verb RunAs
```

On macOS/Linux:

```bash theme={null}
# Fix permissions
chmod 644 koala-data-explorer-1.1.0.vsix
```

### Extension Not Loading After Install

1. Fully restart VS Code (not just reload)
2. Check for conflicts with other extensions
3. Review errors in Help → Toggle Developer Tools
4. Clear extension cache:
   ```bash theme={null}
   rm -rf ~/.vscode/extensions/.obsolete
   ```

### Dependency Issues

If the extension fails due to missing dependencies:

1. Ensure VS Code version >= 1.74.0
2. Install Visual C++ Redistributable (Windows)
3. Check Node.js native modules are compatible

## Deployment Automation

### For IT Administrators

Deploy to multiple machines using scripts:

**PowerShell (Windows)**:

```powershell theme={null}
# 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
    }
}
```

**Bash (macOS/Linux)**:

```bash theme={null}
#!/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**:

```yaml theme={null}
- 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:

1. **Verify Installation**: Check extension appears in list
2. **Configure Settings**: Adjust timeout, logging, etc.
3. **Set Up Connection**: Add Oracle Fusion credentials
4. **Activate License**: Enter license key if you have one

## Security Considerations

When installing manually:

<Warning>
  Only install VSIX files from trusted sources. Verify the publisher and file integrity before installation.
</Warning>

### Verify File Integrity

Check SHA256 hash if provided:

```bash theme={null}
# 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:

```bash theme={null}
# Example with ClamAV
clamscan koala-data-explorer-1.1.0.vsix
```

## Next Steps

After successful manual installation:

<CardGroup cols={2}>
  <Card title="First Connection" icon="plug" href="/koala/installation/first-connection">
    Set up your Oracle Fusion connection
  </Card>

  <Card title="Configuration" icon="gear" href="/koala/config/extension-settings">
    Configure extension settings
  </Card>

  <Card title="License Activation" icon="key" href="/koala/licensing/activating-license">
    Activate your license
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/koala/troubleshooting/connection-issues">
    Resolve common issues
  </Card>
</CardGroup>