Raven Scott
@@ -0,0 +1,248 @@
|
||||
# Installation
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Option A: Standalone Distributable (recommended)
|
||||
|
||||
Download a pre-built standalone binary from the [releases page](https://github.com/holesail/holesail-browser/releases). No runtime dependencies are required — the binary is fully self-contained.
|
||||
|
||||
### Option B: Build from Source
|
||||
|
||||
You need:
|
||||
|
||||
- **[Bare](https://github.com/nicolo-ribaudo/bare)** runtime (for running the native host via launcher script)
|
||||
- **Node.js** (for build and install scripts only, not used at runtime)
|
||||
|
||||
```bash
|
||||
# macOS / Linux (via npm)
|
||||
npm install -g bare
|
||||
|
||||
# Verify
|
||||
bare --version
|
||||
```
|
||||
|
||||
For Windows, download the Bare binary from the [Bare releases page](https://github.com/nicolo-ribaudo/bare/releases) and add it to your `PATH`.
|
||||
|
||||
---
|
||||
|
||||
## Install from Distributable Binary
|
||||
|
||||
1. Download the binary for your platform from the [releases page](https://github.com/holesail/holesail-browser/releases):
|
||||
- `holesail-browser-host-darwin-arm64.zip` — macOS Apple Silicon
|
||||
- `holesail-browser-host-darwin-x64.zip` — macOS Intel
|
||||
- `holesail-browser-host-linux-arm64.zip` — Linux ARM64
|
||||
- `holesail-browser-host-linux-x64.zip` — Linux x64
|
||||
- `holesail-browser-host-win32-x64.zip` — Windows x64
|
||||
|
||||
2. Extract the archive and place the binary in the `releases/` directory of the repository (or any permanent location).
|
||||
|
||||
3. Run the install script — it will detect the binary automatically:
|
||||
|
||||
```bash
|
||||
./scripts/install-host.sh # macOS / Linux
|
||||
.\scripts\install-host.ps1 # Windows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Install from Source
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
```bash
|
||||
git clone https://github.com/holesail/holesail-browser.git
|
||||
cd holesail-browser
|
||||
|
||||
# Install dependencies and build
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
The script:
|
||||
1. Runs `npm install` in the root and `native-host/` directories
|
||||
2. Builds the native host launcher script (`npm run build:host`)
|
||||
3. Registers the native messaging manifest at the correct system path
|
||||
4. Packages the extension as a `.zip` (Chrome) and `.xpi` (Firefox)
|
||||
|
||||
### Building Standalone Binaries
|
||||
|
||||
To build self-contained distributable binaries (no Bare runtime required on the target machine):
|
||||
|
||||
```bash
|
||||
npm run build:dist # Current platform only
|
||||
npm run build:dist:all # All platforms (mac + linux + windows)
|
||||
npm run build:dist:package # All platforms + zip archives for distribution
|
||||
```
|
||||
|
||||
Binaries are written to `releases/`. The install script automatically uses the distributable binary if one is present.
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
git clone https://github.com/holesail/holesail-browser.git
|
||||
cd holesail-browser
|
||||
.\scripts\install.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manual Steps
|
||||
|
||||
If you prefer to run steps individually:
|
||||
|
||||
```bash
|
||||
# 1. Install dependencies
|
||||
npm install
|
||||
cd native-host && npm install && cd ..
|
||||
|
||||
# 2. Build everything
|
||||
npm run build
|
||||
|
||||
# 3. Register the native messaging manifest
|
||||
./scripts/install-host.sh # macOS / Linux
|
||||
.\scripts\install-host.ps1 # Windows
|
||||
|
||||
# 4. Package the extension
|
||||
npm run pack
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Native Messaging Manifest
|
||||
|
||||
The file `com.holesail.browser.json` tells the browser where to find the native host binary and which extension IDs are allowed to connect to it.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "com.holesail.browser",
|
||||
"description": "Native messaging host for Holesail Browser extension (Bare runtime)",
|
||||
"path": "/absolute/path/to/native-host/holesail-browser-host",
|
||||
"type": "stdio",
|
||||
"allowed_origins": ["chrome-extension://YOUR_EXTENSION_ID/"],
|
||||
"allowed_extensions": ["[email protected]"]
|
||||
}
|
||||
```
|
||||
|
||||
The install script writes the absolute path and copies the manifest to the correct system location:
|
||||
|
||||
| Browser | Platform | Manifest location |
|
||||
|---------|----------|-------------------|
|
||||
| Chrome / Edge | macOS | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` |
|
||||
| Chrome / Edge | Linux | `~/.config/google-chrome/NativeMessagingHosts/` |
|
||||
| Chrome / Edge | Windows | Registry: `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.holesail.browser` |
|
||||
| Firefox | macOS | `~/Library/Application Support/Mozilla/NativeMessagingHosts/` |
|
||||
| Firefox | Linux | `~/.mozilla/native-messaging-hosts/` |
|
||||
| Firefox | Windows | Registry: `HKCU\Software\Mozilla\NativeMessagingHosts\com.holesail.browser` |
|
||||
|
||||
If you load the extension and get a different extension ID than the one in the manifest, update it:
|
||||
|
||||
```bash
|
||||
./scripts/update-native-manifest-extension-id.sh YOUR_EXTENSION_ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Loading the Extension
|
||||
|
||||
### Chrome / Edge
|
||||
|
||||
1. Open `chrome://extensions` (or `edge://extensions`)
|
||||
2. Enable **Developer mode** (toggle in the top-right)
|
||||
3. Click **Load unpacked**
|
||||
4. Select the `extension/` folder from the repository
|
||||
5. Note the **Extension ID** shown on the card — you may need it to update the native messaging manifest
|
||||
|
||||
### Firefox
|
||||
|
||||
1. Open `about:debugging#/runtime/this-firefox`
|
||||
2. Click **Load Temporary Add-on**
|
||||
3. Select `extension/manifest.json`
|
||||
|
||||
> **Note:** Firefox requires the extension to be re-loaded after each browser restart when loaded as a temporary add-on. For permanent installation, the extension must be signed by Mozilla or loaded via an enterprise policy.
|
||||
|
||||
---
|
||||
|
||||
## Installing the CA Certificate
|
||||
|
||||
Holesail Browser generates a local root CA (`Holesail Browser CA`) and uses it to sign a wildcard `*.hole.sail` certificate for the HTTPS proxy. Without installing this CA, the browser will show certificate errors when navigating to `*.hole.sail` sites.
|
||||
|
||||
### Via the Dashboard (recommended)
|
||||
|
||||
1. Click the Holesail Browser extension icon
|
||||
2. Go to **Proxy & CA**
|
||||
3. Click **Install CA**
|
||||
4. Follow the OS prompt (macOS will ask for your password)
|
||||
|
||||
### Manual Installation
|
||||
|
||||
The CA certificate is at `holesail-browser-certs/ca.cert.pem`.
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
sudo security add-trusted-cert -d -r trustRoot \
|
||||
-k /Library/Keychains/System.keychain \
|
||||
holesail-browser-certs/ca.cert.pem
|
||||
```
|
||||
|
||||
**Linux:**
|
||||
```bash
|
||||
sudo cp holesail-browser-certs/ca.cert.pem \
|
||||
/usr/local/share/ca-certificates/holesail-browser-ca.crt
|
||||
sudo update-ca-certificates
|
||||
```
|
||||
|
||||
**Windows (PowerShell as Administrator):**
|
||||
```powershell
|
||||
certutil -addstore -f "ROOT" holesail-browser-certs\ca.cert.pem
|
||||
```
|
||||
|
||||
> **Important:** After installing the CA, you must restart the browser for the change to take effect.
|
||||
|
||||
---
|
||||
|
||||
## Updating the Extension ID
|
||||
|
||||
When you load the extension in Chrome, it generates a deterministic extension ID from the public key in `manifest.json`. The `key` field in `manifest.json` is already set, so the ID should be stable across reloads.
|
||||
|
||||
If the ID changes (e.g. after re-generating the key), update the native messaging manifest:
|
||||
|
||||
```bash
|
||||
./scripts/update-native-manifest-extension-id.sh NEW_EXTENSION_ID
|
||||
```
|
||||
|
||||
For Firefox, the extension ID is set in `manifest.json` under `browser_specific_settings.gecko.id` and does not change.
|
||||
|
||||
---
|
||||
|
||||
## Verifying the Installation
|
||||
|
||||
1. Load the extension and click the icon — the Dashboard should open
|
||||
2. Check **Overview**: the host status should show **Connected**
|
||||
3. Go to **Proxy & CA**: the proxy status should show **Active** and the CA should show **Installed**
|
||||
4. Try navigating to a `*.hole.sail` hostname — it should load without certificate errors
|
||||
|
||||
---
|
||||
|
||||
## Uninstalling
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
./scripts/uninstall.sh
|
||||
|
||||
# Windows
|
||||
.\scripts\uninstall.ps1
|
||||
```
|
||||
|
||||
To remove the CA manually:
|
||||
|
||||
**macOS:** Open Keychain Access → System Roots → find `Holesail Browser CA` → delete it.
|
||||
|
||||
**Linux:**
|
||||
```bash
|
||||
sudo rm /usr/local/share/ca-certificates/holesail-browser-ca.crt
|
||||
sudo update-ca-certificates
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
certutil -delstore ROOT "Holesail Browser CA"
|
||||
```
|
||||
Reference in New Issue
Block a user