snxraven/holesail-browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
e6658d4421b86bc6fea1a525c31a6e1f7a0a9632
holesail-browser/docs/INSTALLATION.md
T
Raven Scott e391d82316
CI / Build & Test (push) Successful in 2m50s
Details
feat(pwa): add PWA install support and update installation docs 
Add manifest.webmanifest to the dashboard so Chrome can install it as
a standalone app via the browser menu. Register the manifest in
web_accessible_resources and link it from dashboard.html. Add a
dedicated PWA install section to docs/INSTALLATION.md covering install
steps, uninstall, and the requirement that the extension remains
installed.
2026-03-01 01:36:37 -05:00

272 lines
11 KiB
Markdown
Raw Blame History

# Installation
## Quick install
### macOS / Linux
```bash
curl -fsSL https://git.ssh.surf/snxraven/holesail-browser/raw/branch/main/scripts/web-installer.sh | bash
```
### Windows (PowerShell)
```powershell
irm https://git.ssh.surf/snxraven/holesail-browser/raw/branch/main/scripts/install.ps1 | iex
```
Or download `install.ps1` from the [latest release](https://git.ssh.surf/snxraven/holesail-browser/releases/tag/latest-main) and run it from PowerShell.
---
## What the installer does
### macOS / Linux (`install.sh`)
1. Detects your OS and architecture (`darwin`/`linux`, `x64`/`arm64`)
2. **Preserves existing user data** — if a previous installation is found, `holesail-browser-storage/` (state, settings, backups) and `holesail-browser-certs/` (CA key and certificates) are copied to a temporary location before anything is removed
3. Kills any running `holesail-browser-host` process
4. Removes the previous installation directory and old native messaging manifests
5. Downloads `holesail-browser-host-<platform>-<arch>.zip` from the latest release
6. Extracts the binary to `~/.holesail-browser/holesail-browser-host`
7. **Restores user data** — the preserved storage and certs directories are copied back, so all tunnels, connections, settings, and certificates survive the upgrade
8. **macOS only:** removes Gatekeeper quarantine, ad-hoc signs the binary, pre-runs it to extract `.bare` native addons, then signs all extracted addons
9. **Removes old extension files** — any existing `Holesail-Browser-*.zip` and `Holesail-Browser-*.xpi` files in `~/Downloads` are deleted before downloading the new version
10. Downloads `Holesail-Browser-1.0.0.zip` and `Holesail-Browser-1.0.0.xpi` to `~/Downloads`
11. Writes the native messaging manifest to all browser locations
### Windows (`install.ps1`)
1. **Preserves existing user data** — if a previous installation is found, `holesail-browser-storage\` and `holesail-browser-certs\` are copied to a temporary location in `%TEMP%`
2. Kills any running `holesail-browser-host.exe` process
3. Removes the previous installation directory and old registry keys
4. Downloads `holesail-browser-host-win32-x64.zip` and extracts the `.exe`
5. **Restores user data** — the preserved directories are copied back into the new installation
6. **Removes old extension files** — any existing `Holesail-Browser-*.zip` and `Holesail-Browser-*.xpi` files in `%USERPROFILE%\Downloads` are deleted before downloading the new version
7. Downloads `Holesail-Browser-1.0.0.zip` and `Holesail-Browser-1.0.0.xpi` to `%USERPROFILE%\Downloads`
8. Writes the native messaging manifest JSON and creates registry keys for Chrome, Chromium, and Firefox
### What is preserved across upgrades
| Directory | Contents |
|-----------|----------|
| `holesail-browser-storage/` | `state.json` (all virtual hosts, tunnels, SSH/RDP connections, settings), backup archives |
| `holesail-browser-certs/` | Root CA key and certificate, all wildcard domain certs (one per custom TLD parent, e.g. `wildcard.hole.sail/`, `wildcard.my.internal/`) |
The binary itself is always replaced with the new version. If this is a fresh install (no previous `~/.holesail-browser/` directory), the preserve/restore steps are skipped.
---
## Native messaging manifest locations
The installer writes the manifest to all of these locations automatically:
### macOS
| Browser | Path |
|---------|------|
| Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.holesail.browser.json` |
| Chromium | `~/Library/Application Support/Chromium/NativeMessagingHosts/com.holesail.browser.json` |
| Firefox | `~/Library/Application Support/Mozilla/NativeMessagingHosts/com.holesail.browser.json` |
### Linux
| Browser | Path |
|---------|------|
| Chrome | `~/.config/google-chrome/NativeMessagingHosts/com.holesail.browser.json` |
| Chromium | `~/.config/chromium/NativeMessagingHosts/com.holesail.browser.json` |
| Firefox | `~/.mozilla/native-messaging-hosts/com.holesail.browser.json` |
### Windows
Registry keys under `HKCU\Software\`:
- `Google\Chrome\NativeMessagingHosts\com.holesail.browser`
- `Chromium\NativeMessagingHosts\com.holesail.browser`
- `Mozilla\NativeMessagingHosts\com.holesail.browser`
Each key's default value points to the manifest JSON file at `%LOCALAPPDATA%\holesail-browser\com.holesail.browser.json`.
---
## Loading the extension
### Chrome / Edge
1. Open `chrome://extensions`
2. Enable **Developer mode** (toggle in the top right)
3. Drag `~/Downloads/Holesail-Browser-1.0.0.zip` onto the extensions page
*(or click **Load unpacked** and select the extracted folder)*
### Firefox (regular)
Firefox requires extensions to be signed by Mozilla for permanent installation via `about:addons`. Use the temporary add-on loader instead:
1. Open `about:debugging`
2. Click **This Firefox**
3. Click **Load Temporary Add-on...**
4. Select `~/Downloads/Holesail-Browser-1.0.0.zip` (or any file inside the extracted folder)
> Temporary add-ons are removed when Firefox restarts — you will need to reload it each session.
### Firefox Developer Edition / Nightly (permanent, unsigned)
Developer Edition and Nightly allow disabling Mozilla's signature requirement:
1. Open `about:config` → search for `xpinstall.signatures.required` → set it to `false`
2. Open `about:addons` → gear icon → **Install Add-on From File**
3. Select `~/Downloads/Holesail-Browser-1.0.0.xpi`
### Firefox (permanent, signed via AMO)
For a permanent install in regular Firefox without any workarounds, the extension must be submitted to [addons.mozilla.org](https://addons.mozilla.org) (AMO) and signed by Mozilla. Once signed, the `.xpi` can be installed permanently in any Firefox version via `about:addons`.
The signing process:
1. Create an account at [addons.mozilla.org](https://addons.mozilla.org/developers/)
2. Submit the `.xpi` for review (self-hosted distribution is available — full AMO listing is not required)
3. Mozilla signs and returns the `.xpi`
4. Distribute the signed `.xpi` — users can install it via `about:addons` without any config changes
Self-hosted signing (without a public AMO listing) is available via the [AMO Developer Hub](https://addons.mozilla.org/developers/) under **Submit a New Add-on** → **On your own**.
---
## Installing the dashboard as a standalone app (PWA)
The dashboard supports being installed as a standalone desktop app via Chrome's PWA install feature. This opens the dashboard in its own OS window without any browser chrome (no address bar, tabs, or toolbar).
**Requirements:** The Holesail Browser extension must already be installed. The PWA is a launcher only — all functionality still runs through the extension and native host.
### How to install
1. Open the dashboard (click the Holesail icon in the toolbar, or press `Alt+Shift+H`)
2. In Chrome, open the browser menu (**⋮** top right) → **Save and share** → **Install page as app**
3. Confirm the install prompt — the dashboard will appear in your OS app launcher and dock
Once installed, you can open Holesail directly from your desktop without opening a browser tab first.
### Uninstalling the PWA
In Chrome, go to `chrome://apps`, right-click **Holesail Browser**, and select **Remove from Chrome**. This removes the standalone app shortcut but does not affect the extension itself.
> **Note:** The PWA requires the extension to remain installed. If you uninstall the extension, the installed app will no longer function.
---
## First-time setup
After loading the extension:
1. Click the Holesail Browser icon in the toolbar to open the dashboard
2. Go to **Proxy & CA** → click **Install Root CA**
3. **Fully quit and reopen Chrome** (Cmd+Q on macOS, Alt+F4 on Windows) for the CA trust to take effect
4. Go to **Virtual Hosts** → add a hostname (e.g. `myapp.hole.sail`) and its `hs://` key
5. Navigate to `https://myapp.hole.sail/`
> The root CA must be installed and Chrome must be restarted before `*.hole.sail` sites will load without a certificate warning. The CA is installed silently to your user keychain — no admin password is required on macOS.
---
## Updating the extension ID
The native messaging manifest contains an `allowed_origins` field with the extension's Chrome ID. If you load the extension from a different source (e.g. a locally built zip), the ID may differ.
To update it, run:
```bash
# macOS / Linux
bash scripts/update-native-manifest-extension-id.sh <new-extension-id>
# Windows
.\scripts\update-native-manifest-extension-id.ps1 <new-extension-id>
```
Or edit the manifest JSON files directly and replace the `chrome-extension://...` value in `allowed_origins`.
---
## Uninstalling
### macOS / Linux
```bash
pkill -f holesail-browser-host 2>/dev/null || true
rm -rf ~/.holesail-browser
# Remove native messaging manifests
rm -f ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.holesail.browser.json
rm -f ~/Library/Application\ Support/Chromium/NativeMessagingHosts/com.holesail.browser.json
rm -f ~/Library/Application\ Support/Mozilla/NativeMessagingHosts/com.holesail.browser.json
# Remove CA from keychain (macOS)
security delete-certificate -c "Holesail Browser CA" ~/Library/Keychains/login.keychain-db 2>/dev/null || true
```
### Windows
```powershell
Stop-Process -Name holesail-browser-host -Force -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\holesail-browser"
Remove-Item -Path "HKCU:\Software\Google\Chrome\NativeMessagingHosts\com.holesail.browser" -ErrorAction SilentlyContinue
Remove-Item -Path "HKCU:\Software\Chromium\NativeMessagingHosts\com.holesail.browser" -ErrorAction SilentlyContinue
Remove-Item -Path "HKCU:\Software\Mozilla\NativeMessagingHosts\com.holesail.browser" -ErrorAction SilentlyContinue
```
Then remove the extension from `chrome://extensions`.
---
## Building from source
### Prerequisites
- [Node.js](https://nodejs.org/) 18+
- [Bare](https://github.com/holepunchto/bare) runtime (for running the native host in development)
- npm
### Steps
```bash
git clone https://git.ssh.surf/snxraven/holesail-browser
cd holesail-browser
# Install root dependencies
npm install
# Install native host dependencies
cd native-host && npm install && cd ..
# Build extension (.zip + .xpi)
npm run pack
# Build native host binary for current platform
npm run build:dist
# Build for all platforms
npm run build:dist:all
```
Built artifacts:
- `releases/Holesail-Browser-*.zip` — Chrome extension
- `releases/Holesail-Browser-*.xpi` — Firefox extension
- `releases/<platform>-<arch>/holesail-browser-host[.exe]` — native host binary
### Running in development
```bash
# Run the native host directly with Bare
cd native-host
bare index.mjs
```
Load the `extension/` directory as an unpacked extension in Chrome.
---
## Environment variables
| Variable | Description |
|----------|-------------|
| `HOLESAIL_DEBUG=1` | Enable verbose debug logging in the native host |
| `HOLESAIL_BROWSER_STORAGE=<path>` | Override the storage directory (default: next to binary) |
| `HOLESAIL_BROWSER_CERTS=<path>` | Override the certs directory (default: next to binary) |
| `BRIDGE_SWARM_LOG=<path>` | Override the log file path |
Reference in New Issue View Git Blame Copy Permalink