thibaud-lclr/api-client
1
0
Fork 0
Code Packages Activity Actions

docs(desktop): add minimum system requirements (#5096)

Browse source
This commit is contained in:
Shreyas 2025-05-26 12:22:21 +05:30 committed by GitHub
parent 656a15a983
commit 935bc10c0b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 99 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

155
packages/hoppscotch-desktop/README.md
View file

@ -19,25 +19,23 @@
![Hoppscotch Desktop App](connection-to-self-hosted-instance.png)
## Install Hoppscotch Desktop App
## Installation
1. [Download the latest version of Hoppscotch Desktop App](https://hoppscotch.com/download)
2. Open the downloaded file.
3. Follow the on-screen instructions to install Hoppscotch Desktop App.
4. Open Hoppscotch Desktop App.
## Access Hoppscotch
## Access Options
### Hoppscotch Cloud Edition for Individuals
Access Hoppscotch Cloud Edition from Hoppscotch Desktop App:
1. Open Hoppscotch Desktop App.
2. Click the Hoppscotch logo in the top-left corner.
3. Click "**HOPPSCOTCH CLOUD**".
4. Sign in with your Hoppscotch Cloud account to access your workspaces and collections.
### Hoppscotch Self-Hosted Edition for Community
### Self-Hosted Edition (Community and Enterprise)
> [!Note]
> To enable desktop app support for your self-hosted Hoppscotch instance, make sure to update the `WHITELISTED_ORIGINS` environment variable in your `.env` file with your deployment URL.
@ -47,57 +45,7 @@ Access Hoppscotch Cloud Edition from Hoppscotch Desktop App:
> WHITELISTED_ORIGINS=...existing_origins,app://hoppscotch_mydomain_com,http://app.hoppscotch_mydomain_com
> ```
Add your self-hosted Hoppscotch Community Edition instance to Hoppscotch Desktop App:
1. Open Hoppscotch Desktop App.
2. Click the Hoppscotch logo in the top-left corner.
3. Click "**Add an instance**".
4. Enter the URL of your self-hosted Hoppscotch instance.
5. Click "**Connect**".
> [!Tip]
> You can also self-host Hoppscotch Desktop App.
> 1. Install and generate the selfhost web app:
> ```bash
> cd ../hoppscotch-selfhost-web
> pnpm install
> pnpm generate
> ```
> 2. Build the webapp bundler:
> ```bash
> cd crates/webapp-bundler
> cargo build --release
> ```
> 3. Bundle the web app:
> ```bash
> cd target/release
> ./webapp-bundler --input [path-to-dist-directory] --output [path-to-hoppscotch-desktop]/bundle.zip --manifest [path-to-hoppscotch-desktop]/manifest.json
> ```
> 4. Run the Tauri development server:
> ```bash
> cd src-tauri
> pnpm tauri dev
> ```
> or the following for production build:
> ```bash
> cd src-tauri
> pnpm tauri dev
> ```
> [!Note]
> `[path-to-dist-directory]` should point to the `dist` directory created by the `pnpm generate` command in step 1.
### Hoppscotch Self-Hosted Edition for Enterprise
> [!Note]
> To enable desktop app support for your self-hosted Hoppscotch instance, make sure to update the `WHITELISTED_ORIGINS` environment variable in your `.env` file with your deployment URL.
>
> e.g. to allow connection to `https://hoppscotch.mydomain.com` you need to add `app://hoppscotch_mydomain_com` (MacOS, Linux) and `http://app.hoppscotch_mydomain_com` (Windows) to the `WHITELISTED_ORIGINS` environment variable.
> ```bash
> WHITELISTED_ORIGINS=...existing_origins,app://hoppscotch_mydomain_com,http://app.hoppscotch_mydomain_com
> ```
Add your self-hosted Hoppscotch Enterprise Edition instance to Hoppscotch Desktop App:
To connect to your self-hosted (community or enterprise) instance:
1. Open Hoppscotch Desktop App.
2. Click the Hoppscotch logo in the top-left corner.
@ -113,3 +61,98 @@ Add your self-hosted Hoppscotch Enterprise Edition instance to Hoppscotch Deskto
> ```
>
> Once the container is live, you can enter `[your-ip]:3200` or simply the base address of the instance if you are using [subpath access](https://docs.hoppscotch.io/guides/articles/self-host-hoppscotch-on-your-own-servers#4-subpath-access).
## Building and Self-Hosting Hoppscotch Desktop
You can also build Hoppscotch Desktop locally to self-host with on-prem infra:
1. Install and generate the selfhost web app:
```bash
cd ../hoppscotch-selfhost-web
pnpm install
pnpm generate
```
2. Build the `webapp-bundler`:
```bash
cd crates/webapp-bundler
cargo build --release
```
3. Bundle the web app:
```bash
cd target/release
./webapp-bundler --input [path-to-dist-directory] --output [path-to-hoppscotch-desktop]/bundle.zip --manifest [path-to-hoppscotch-desktop]/manifest.json
```
4. Run the development server:
```bash
cd hoppscotch-desktop
pnpm tauri dev
```
or the following for production build:
```bash
cd src-tauri
pnpm tauri dev
```
> [!Note]
> `[path-to-dist-directory]` should point to the `dist` directory created by the `pnpm generate` command in step 1.
## Minimum System Requirements
### Windows
- **OS Version**: Windows 10 1803+ or Windows 11
- **Architecture**: x64
### macOS
- **OS Version**: macOS 10.15 (Catalina) or later
- **Architecture**: Intel x64 or Apple Silicon (ARM64)
### Linux
- **Architecture**: x64
- **Recommended OS**: Ubuntu 24.04 or newer (or similar flavor of distros)
- **Minimum**: Systems with GLIBC 2.38+
#### Why Ubuntu 24.04-like flavors or newer?
Ubuntu 24.04-like flavors ships with the exact WebKit2GTK version (2.44.0-2) that is stable enough to correctly handle interaction between WebKit, UI libraries, Mesa drivers, and Wayland displays.[^1][^2][^3]
> [!IMPORTANT]
> There may be some display oddities on Wayland systems caused by the interaction between WebKit and the underlying graphics drivers.[^4][^5][^6]
>
> **Workaround**:
> ```bash
> WEBKIT_DISABLE_COMPOSITING_MODE=1 hoppscotch
> # or
> WEBKIT_DISABLE_DMABUF_RENDERER=1 hoppscotch
> # or both together
> ```
### Misc.
- **Older distributions**: The AppImage requires GLIBC 2.38+ [^1][^7]
- Users on older systems will see GLIBC version errors like "GLIBC_2.32' not found"[^8]
- **Tauri v2 dependency**: The desktop app requires libwebkit2gtk-4.1, which is only available by default in Ubuntu 22.04+ repositories[^9]
- **Build from source**: GitHub workflow for building from source[^10]
---
### Sources
[^1]: [WebKit version pinning and GLIBC explanation](https://github.com/hoppscotch/hoppscotch/issues/3543#issuecomment-2869628299) - Detailed explanation of why specific webkit2gtk 2.44.0-2 is used and GLIBC 2.38+ requirement
[^2]: [WebKit 2.44.0-2 selection rationale](https://github.com/hoppscotch/hoppscotch/issues/4880#issuecomment-2014063000) - Why this specific version provides the best balance for Wayland support
[^3]: [Ubuntu webkit2gtk package versions](https://packages.ubuntu.com/search?keywords=webkit2gtk&searchon=names) - Official Ubuntu package repositories showing version availability
[^4]: [EGL/Mesa/Wayland bug report](https://bugs.launchpad.net/ubuntu/+source/webkit2gtk/+bug/1966418) - Comprehensive bug report about webkit apps showing blank screens on Wayland
[^5]: [WebKit GTK Wayland compositing issue](https://bugs.webkit.org/show_bug.cgi?id=165246) - Upstream WebKit bug about compositing mode failures
[^6]: [Mesa issue with webkit2gtk](https://gitlab.freedesktop.org/mesa/mesa/-/issues/6236) - Mesa driver interaction with webkit2gtk causing EGL initialization failures
[^7]: [GLIBC compatibility matrix](https://github.com/hoppscotch/hoppscotch/issues/3543#issuecomment-1077225935) - User reports of specific GLIBC version errors
[^8]: [Specific GLIBC error examples](https://github.com/hoppscotch/hoppscotch/issues/3543#issuecomment-1329816314) - User reports showing exact GLIBC version error messages
[^9]: [Tauri v2 webkit requirements](https://github.com/tauri-apps/tauri/issues/8535#issuecomment-2162723242) - Tauri v2's dependency on libwebkit2gtk-4.1
[^10]: [Hoppscotch Desktop build workflow](https://github.com/hoppscotch/hoppscotch/blob/main/.github/workflows/build-hoppscotch-desktop.yml) - Official build workflow and instructions