mirror of
https://github.com/aaddrick/claude-desktop-debian.git
synced 2026-05-17 00:26:21 +03:00
3b86003a6b
Re-add the exact Electron version pin that #586 had, hoisted to a named local in scripts/setup/dependencies.sh so the next bump is intentional. Upstream Claude Desktop's app.asar binds to a specific V8/NAPI ABI, Chromium pairing, and node-pty native surface; running a different Electron major against it is unsupported and was the reproducibility hole left when this PR dropped the ^41 pin. Also: - Wrap node fetch-electron-binary.js in a 2-attempt retry so a transient 503 from electron's CDN doesn't red the whole build. - Whitelist supported archs (x64, arm64, armv7l, ia32) with an actionable error in fetch-electron-binary.js, instead of 404'ing on electron's release server for exotic-arch hosts. - Document ELECTRON_MIRROR / ELECTRON_CUSTOM_DIR in docs/BUILDING.md and clarify that ELECTRON_CACHE is NOT honored by @electron/get (the original PR body's claim was wrong). Refs #584. Addresses self-review feedback on #587. Co-Authored-By: Claude <claude@anthropic.com>
155 lines
5.7 KiB
Markdown
155 lines
5.7 KiB
Markdown
[< Back to README](../README.md)
|
|
|
|
# Building from Source
|
|
|
|
## Prerequisites
|
|
|
|
- Linux distribution (Debian/Ubuntu, Fedora/RHEL, or other)
|
|
- Git
|
|
- Basic build tools (automatically installed by the script)
|
|
|
|
## Build Instructions
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/aaddrick/claude-desktop-debian.git
|
|
cd claude-desktop-debian
|
|
|
|
# Build with auto-detected format (based on your distro)
|
|
./build.sh
|
|
|
|
# Or specify a format explicitly:
|
|
./build.sh --build deb # Debian/Ubuntu .deb package
|
|
./build.sh --build rpm # Fedora/RHEL .rpm package
|
|
./build.sh --build appimage # Distribution-agnostic AppImage
|
|
./build.sh --build nix # Nix derivation (patch only, used by flake)
|
|
|
|
# Build with custom options
|
|
./build.sh --build deb --clean no # Keep intermediate files
|
|
|
|
# Build using a locally downloaded installer
|
|
# (useful when the bundled download URL is outdated)
|
|
./build.sh --exe /path/to/Claude-Setup.exe
|
|
```
|
|
|
|
The build script automatically detects your distribution and selects the appropriate package format:
|
|
| Distribution | Default Format | Package Manager |
|
|
|--------------|----------------|-----------------|
|
|
| Debian, Ubuntu, Mint | `.deb` | apt |
|
|
| Fedora, RHEL, CentOS | `.rpm` | dnf |
|
|
| NixOS | `nix` | nix |
|
|
| Arch Linux | `.AppImage` (via AUR) | yay/paru |
|
|
| Other | `.AppImage` | - |
|
|
|
|
## Build Environment Variables
|
|
|
|
The build pulls the Electron prebuilt binary from `github.com/electron/electron/releases` via `@electron/get`. Two upstream environment variables let you redirect that fetch:
|
|
|
|
- `ELECTRON_MIRROR` — base URL to fetch Electron releases from instead of GitHub. Useful for mirrors or local proxies. Example: `ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/`.
|
|
- `ELECTRON_CUSTOM_DIR` — overrides the path segment after the mirror. Defaults to `v{version}`.
|
|
|
|
The cache location is fixed at `~/.cache/electron/` (resolved by `@electron/get` via `envPaths`) and is reused across builds. `ELECTRON_CACHE` is **not** read by `@electron/get` — set `ELECTRON_MIRROR` if you need to avoid the public CDN.
|
|
|
|
The pinned Electron version lives in `scripts/setup/dependencies.sh` (`electron_version`) and must match `build-reference/app-extracted/package.json` — the upstream Claude Desktop `app.asar` is built against a specific Electron major and running a different one is unsupported.
|
|
|
|
## Installing the Built Package
|
|
|
|
### For .deb packages (Debian/Ubuntu)
|
|
|
|
```bash
|
|
sudo apt install ./claude-desktop_VERSION_ARCHITECTURE.deb
|
|
# Or: sudo dpkg -i ./claude-desktop_VERSION_ARCHITECTURE.deb
|
|
|
|
# If you encounter dependency issues:
|
|
sudo apt --fix-broken install
|
|
```
|
|
|
|
### For .rpm packages (Fedora/RHEL)
|
|
|
|
```bash
|
|
sudo dnf install ./claude-desktop-VERSION-1.ARCH.rpm
|
|
# Or: sudo rpm -i ./claude-desktop-VERSION-1.ARCH.rpm
|
|
```
|
|
|
|
### For AppImages
|
|
|
|
```bash
|
|
# Make executable
|
|
chmod +x ./claude-desktop-*.AppImage
|
|
|
|
# Run directly
|
|
./claude-desktop-*.AppImage
|
|
|
|
# Or integrate with your system using Gear Lever
|
|
```
|
|
|
|
**Note:** AppImage login requires proper desktop integration. Use [Gear Lever](https://flathub.org/apps/it.mijorus.gearlever) or manually install the provided `.desktop` file to `~/.local/share/applications/`.
|
|
|
|
**Automatic Updates:** AppImages downloaded from GitHub releases include embedded update information and work seamlessly with Gear Lever for automatic updates. Locally-built AppImages can be manually configured for updates in Gear Lever.
|
|
|
|
### For NixOS
|
|
|
|
The repository includes a Nix flake. Build and install directly:
|
|
|
|
```bash
|
|
# Build the package
|
|
nix build .#claude-desktop
|
|
|
|
# Build the FHS-wrapped variant (for MCP server support)
|
|
nix build .#claude-desktop-fhs
|
|
|
|
# Run without installing
|
|
nix run .#claude-desktop
|
|
```
|
|
|
|
For declarative NixOS installation, see the [README](../README.md#using-nix-flake-nixos).
|
|
|
|
## Technical Details
|
|
|
|
### How It Works
|
|
|
|
Claude Desktop is an Electron application distributed for Windows. This project:
|
|
|
|
1. Downloads the official Windows installer
|
|
2. Extracts application resources
|
|
3. Replaces Windows-specific native modules with Linux-compatible implementations
|
|
4. Repackages as one of:
|
|
- **Debian package (.deb)**: For Debian, Ubuntu, and derivatives
|
|
- **RPM package (.rpm)**: For Fedora, RHEL, CentOS, and derivatives
|
|
- **AppImage**: Portable, distribution-agnostic executable
|
|
- **Nix package**: For NixOS, via the included flake
|
|
|
|
### Build Process
|
|
|
|
The build script (`build.sh`) handles:
|
|
- Dependency checking and installation
|
|
- Resource extraction from Windows installer
|
|
- Icon processing for Linux desktop standards
|
|
- Native module replacement
|
|
- Package generation based on selected format
|
|
|
|
### Automated Version Detection
|
|
|
|
A GitHub Actions workflow runs daily to check for new Claude Desktop releases:
|
|
|
|
1. Uses Playwright to resolve Anthropic's Cloudflare-protected download redirects
|
|
2. Compares resolved URLs with those in `scripts/setup/detect-host.sh`
|
|
3. If a new version is detected:
|
|
- Updates `scripts/setup/detect-host.sh` with new download URLs
|
|
- Updates `nix/claude-desktop.nix` with new version, URLs, and SRI hashes
|
|
- Creates a new release tag
|
|
- Triggers automated builds for both architectures
|
|
|
|
This ensures the repository stays up-to-date with official releases automatically.
|
|
|
|
### Manual Updates
|
|
|
|
If you need to build with a specific version before the automation catches it:
|
|
|
|
1. **Use a local installer**: Download the latest installer from [claude.ai/download](https://claude.ai/download) and build with:
|
|
```bash
|
|
./build.sh --exe /path/to/Claude-Setup.exe
|
|
```
|
|
|
|
2. **Update the URL**: Modify the `claude_download_url` assignments in `scripts/setup/detect-host.sh` (inside the `detect_architecture` case statement).
|