From 54f68cd939192168782789d20c828597637e8342 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 11:49:27 +0200 Subject: [PATCH 01/14] Update Linux docs for beta release --- README.md | 3 +- docs/linux.md | 130 +++++++++++++++++++++++++------------------------- 2 files changed, 67 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 4a3e3d6dbe..0ee97ac94e 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,13 @@ Spin up sites in seconds, sync with WordPress.com or Pressable, or import any Wo ## Get started -WordPress Studio is free to use for Mac and Windows. Simply download the app to start building and testing — no dependencies required. +WordPress Studio is free to use for Mac, Windows, and Linux (beta). Simply download the app to start building and testing — no dependencies required. [Download WordPress Studio](https://developer.wordpress.com/studio/) for: - macOS (Intel or Apple Silicon) - Windows +- Linux (beta) — [download the `.deb` from GitHub Releases](https://github.com/Automattic/studio/releases). See the [Linux guide](docs/linux.md) for install steps. ## Highlights diff --git a/docs/linux.md b/docs/linux.md index 5ca715deb1..a3bfe6059b 100644 --- a/docs/linux.md +++ b/docs/linux.md @@ -1,24 +1,57 @@ # Linux Guide -Studio for Linux is currently in an experimental phase. While official packages are not yet available, you can easily build and run Studio from source on most Linux distributions. +Studio is available for Linux as a beta release. Most users should install the published Debian package; developers can also build from source. -## Current Limitations +## Install Studio -Linux support comes with certain limitations: -- For systems using Wayland, you may need to set the `--enable-features=UseOzonePlatform --ozone-platform=wayland` flag when running the application. -- Some features may not work as expected on Linux due to platform-specific implementations. -- The auto-update feature is not currently supported on Linux builds. -- These instructions should work for most Linux distributions, but you may need to adjust them based on your specific setup or distribution. +Studio publishes `.deb` packages for x64 and ARM64 architectures, suitable for Debian, Ubuntu, and derivatives. + +1. Download the latest `.deb` for your architecture from the [Studio releases page](https://github.com/Automattic/studio/releases). + - `studio-x64-v.deb` for Intel/AMD 64-bit systems + - `studio-arm64-v.deb` for ARM 64-bit systems + +2. Install the package: + ```bash + sudo apt install ./studio-x64-v*.deb + ``` + +3. Launch Studio from your application menu, or run `studio` from a terminal. + +The package registers a `.desktop` entry, an icon, and the `wp-studio://` URL handler so OAuth redirects from WordPress.com return cleanly. + +## Updating + +Studio checks for updates automatically and surfaces a dialog with a Download button when a new version is available. Clicking Download opens your browser to fetch the latest `.deb`; install it with `sudo apt install ./.deb` to apply the update. + +You can also re-download the latest `.deb` from the [releases page](https://github.com/Automattic/studio/releases) at any time. + +## Known Limitations + +- For systems using Wayland, you may need to launch Studio with the `--enable-features=UseOzonePlatform --ozone-platform=wayland` flag. +- Some features may behave differently on Linux due to platform-specific implementations. +- Studio is in beta on Linux — please [open an issue](https://github.com/Automattic/studio/issues) if you hit problems. + +## Running with Wayland + +If you're using Wayland instead of X11, launch Studio with additional flags: + +```bash +studio --enable-features=UseOzonePlatform --ozone-platform=wayland +``` + +To persist the flags, copy `/usr/share/applications/studio.desktop` to `~/.local/share/applications/` and edit the `Exec=` line there. ## Building from Source +If you're contributing to Studio or running it on a distribution where the `.deb` doesn't work, you can build directly from the repository. + ### Prerequisites Ensure you have the following dependencies installed: -- [Node.js](https://nodejs.org/) - required JavaScript runtime environment -- [Python](https://www.python.org/) - required for building native dependencies -- [setuptools](https://pypi.org/project/setuptools/) - required for building native dependencies +- [Node.js](https://nodejs.org/) — required JavaScript runtime environment +- [Python](https://www.python.org/) — required for building native dependencies +- [setuptools](https://pypi.org/project/setuptools/) — required for building native dependencies Many contributors use [`nvm`](https://github.com/nvm-sh/nvm) to manage Node.js installations. @@ -40,12 +73,12 @@ Many contributors use [`nvm`](https://github.com/nvm-sh/nvm) to manage Node.js i ```bash npm run package ``` - - This will create an `out/` folder inside `apps/studio/`. + + This creates an `out/` folder inside `apps/studio/`. 4. **Locate the executable:** - - Navigate to the `apps/studio/out/Studio-linux-x64/` folder. Inside, you'll find a `studio` executable. + + Navigate to `apps/studio/out/Studio-linux-x64/`. Inside, you'll find a `studio` executable. 5. **Run Studio:** ```bash @@ -53,13 +86,13 @@ Many contributors use [`nvm`](https://github.com/nvm-sh/nvm) to manage Node.js i ./studio ``` -## Creating a Desktop Shortcut (Optional) +To build a `.deb` package instead of the unpackaged binary, run `npm run make:linux-x64` or `npm run make:linux-arm64`. The output lands in `apps/studio/out/make/deb//`. -For easier access, you can create a desktop entry file that will add Studio to your application launcher. +### Creating a Desktop Shortcut (source builds only) -### Steps +`.deb` installs register a desktop entry automatically. For source builds you can create one manually: -1. **Create a desktop file:** +1. **Create the file:** ```bash nano ~/.local/share/applications/studio.desktop ``` @@ -77,49 +110,33 @@ For easier access, you can create a desktop entry file that will add Studio to y Categories=Development; ``` -3. **Replace placeholders:** - - Replace `` with the actual absolute path to your cloned repository - - For example: `/home/username/projects/studio` +3. Replace `` with the actual absolute path to your cloned repository. -4. **Make the desktop file executable (if needed):** - ```bash - chmod +x ~/.local/share/applications/studio.desktop - ``` - -5. **Refresh your application menu:** - - Depending on your desktop environment, you may need to log out and back in, or run: +4. **Refresh your application menu:** ```bash update-desktop-database ~/.local/share/applications ``` -6. **Register Studio handler for `wp-studio://` links:** +5. **Register Studio as the `wp-studio://` handler:** ```bash xdg-mime default studio.desktop x-scheme-handler/wp-studio ``` Without this, browsers will still show "Open With… / No Apps Available" when WordPress.com OAuth redirects back to `wp-studio://`. -Studio should now appear in your application launcher and can handle `wp-studio://` protocol URLs. - -## Running with Wayland - -If you're using Wayland instead of X11, run Studio with additional flags: +### Updating a Source Build ```bash -./studio --enable-features=UseOzonePlatform --ozone-platform=wayland -``` - -You can add these flags to the `Exec` line in your desktop file if you created one: - -```ini -Exec=/apps/studio/out/Studio-linux-x64/studio --enable-features=UseOzonePlatform --ozone-platform=wayland %U +cd +git pull +npm install +npm run package ``` ## Troubleshooting -### Permission Issues +### Permission issues running a source build -If you encounter permission issues when running the executable, make sure it has execute permissions: +If you encounter permission issues when running `./studio` from a source build, make sure it has execute permissions: ```bash chmod +x apps/studio/out/Studio-linux-x64/studio @@ -138,9 +155,11 @@ sudo sysctl --system The setting survives reboots and `npm install` runs, so you only need to do this once per machine. -### Missing Dependencies +This only affects `npm start` during development; installed `.deb` packages ship a properly-configured SUID sandbox binary and are unaffected. + +### Missing system libraries (source builds) -If you encounter errors about missing libraries, you may need to install additional system dependencies. Common packages include: +`.deb` installs declare their system dependencies automatically. If you're running a source build and encounter errors about missing libraries, install the common dependencies: ```bash # Debian/Ubuntu @@ -153,25 +172,6 @@ sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils at-spi2-core util-linux libsecret ``` -## Updating Studio - -Since auto-updates are not supported on Linux builds, you'll need to manually update: - -1. Pull the latest changes from the repository: - ```bash - cd - git pull - ``` - -2. Reinstall dependencies and rebuild: - ```bash - npm install - npm run package - ``` - -The executable in `apps/studio/out/Studio-linux-x64/` will be updated with the new version. - ## Contributing If you encounter Linux-specific issues or have suggestions for improving Linux support, please [open an issue](https://github.com/Automattic/studio/issues) or submit a pull request. Your feedback helps improve Studio for all Linux users! - From ecf66320555199bebff7aea4ea7358070f36463d Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 11:52:09 +0200 Subject: [PATCH 02/14] Drop beta framing from Linux docs --- README.md | 4 ++-- docs/linux.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0ee97ac94e..1e36abba38 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,13 @@ Spin up sites in seconds, sync with WordPress.com or Pressable, or import any Wo ## Get started -WordPress Studio is free to use for Mac, Windows, and Linux (beta). Simply download the app to start building and testing — no dependencies required. +WordPress Studio is free to use for Mac, Windows, and Linux. Simply download the app to start building and testing — no dependencies required. [Download WordPress Studio](https://developer.wordpress.com/studio/) for: - macOS (Intel or Apple Silicon) - Windows -- Linux (beta) — [download the `.deb` from GitHub Releases](https://github.com/Automattic/studio/releases). See the [Linux guide](docs/linux.md) for install steps. +- Linux — [download the `.deb` from GitHub Releases](https://github.com/Automattic/studio/releases). See the [Linux guide](docs/linux.md) for install steps. ## Highlights diff --git a/docs/linux.md b/docs/linux.md index a3bfe6059b..7236aec283 100644 --- a/docs/linux.md +++ b/docs/linux.md @@ -1,6 +1,6 @@ # Linux Guide -Studio is available for Linux as a beta release. Most users should install the published Debian package; developers can also build from source. +Studio is available for Linux. Most users should install the published Debian package; developers can also build from source. ## Install Studio @@ -29,7 +29,7 @@ You can also re-download the latest `.deb` from the [releases page](https://gith - For systems using Wayland, you may need to launch Studio with the `--enable-features=UseOzonePlatform --ozone-platform=wayland` flag. - Some features may behave differently on Linux due to platform-specific implementations. -- Studio is in beta on Linux — please [open an issue](https://github.com/Automattic/studio/issues) if you hit problems. +- Please [open an issue](https://github.com/Automattic/studio/issues) if you hit problems. ## Running with Wayland From 1da3b53e0f80c1017e333f206566e91023f724b2 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 11:56:36 +0200 Subject: [PATCH 03/14] Drop obvious launch step and .desktop registration note --- docs/linux.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/linux.md b/docs/linux.md index 7236aec283..f7e9dc23a0 100644 --- a/docs/linux.md +++ b/docs/linux.md @@ -15,10 +15,6 @@ Studio publishes `.deb` packages for x64 and ARM64 architectures, suitable for D sudo apt install ./studio-x64-v*.deb ``` -3. Launch Studio from your application menu, or run `studio` from a terminal. - -The package registers a `.desktop` entry, an icon, and the `wp-studio://` URL handler so OAuth redirects from WordPress.com return cleanly. - ## Updating Studio checks for updates automatically and surfaces a dialog with a Download button when a new version is available. Clicking Download opens your browser to fetch the latest `.deb`; install it with `sudo apt install ./.deb` to apply the update. From b5c6c32b213e73c57fa4dffd873e196f891c6ebf Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:03:49 +0200 Subject: [PATCH 04/14] Drop outdated Wayland sections --- docs/linux.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/docs/linux.md b/docs/linux.md index f7e9dc23a0..a83e9c687d 100644 --- a/docs/linux.md +++ b/docs/linux.md @@ -21,22 +21,6 @@ Studio checks for updates automatically and surfaces a dialog with a Download bu You can also re-download the latest `.deb` from the [releases page](https://github.com/Automattic/studio/releases) at any time. -## Known Limitations - -- For systems using Wayland, you may need to launch Studio with the `--enable-features=UseOzonePlatform --ozone-platform=wayland` flag. -- Some features may behave differently on Linux due to platform-specific implementations. -- Please [open an issue](https://github.com/Automattic/studio/issues) if you hit problems. - -## Running with Wayland - -If you're using Wayland instead of X11, launch Studio with additional flags: - -```bash -studio --enable-features=UseOzonePlatform --ozone-platform=wayland -``` - -To persist the flags, copy `/usr/share/applications/studio.desktop` to `~/.local/share/applications/` and edit the `Exec=` line there. - ## Building from Source If you're contributing to Studio or running it on a distribution where the `.deb` doesn't work, you can build directly from the repository. From 5b3c24f322771eff8fca51f8155deab708b5cc73 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:08:19 +0200 Subject: [PATCH 05/14] Consolidate Linux docs into code-contributions.md and delete linux.md --- README.md | 2 +- docs/code-contributions.md | 72 +++++++++++++++-- docs/linux.md | 157 ------------------------------------- 3 files changed, 65 insertions(+), 166 deletions(-) delete mode 100644 docs/linux.md diff --git a/README.md b/README.md index 1e36abba38..e79c166b82 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ WordPress Studio is free to use for Mac, Windows, and Linux. Simply download the - macOS (Intel or Apple Silicon) - Windows -- Linux — [download the `.deb` from GitHub Releases](https://github.com/Automattic/studio/releases). See the [Linux guide](docs/linux.md) for install steps. +- Linux — [download the `.deb` from GitHub Releases](https://github.com/Automattic/studio/releases) (x64 or ARM64) and install with `sudo apt install ./studio-*.deb`. ## Highlights diff --git a/docs/code-contributions.md b/docs/code-contributions.md index 9b68913c85..b9ec459bb7 100644 --- a/docs/code-contributions.md +++ b/docs/code-contributions.md @@ -196,7 +196,7 @@ Then open `chrome://inspect` in a Chromium-based browser and click "inspect" nex ## Building Installers Once all required dependencies are installed, you can build installers for the app. -Installers can currently be built on Mac (Intel or Apple Silicon), Windows, and experimentally for Linux using the following commands: +Installers can be built on Mac (Intel or Apple Silicon), Windows, and Linux (x64 or ARM64) using the following commands: ```bash npm install @@ -207,22 +207,78 @@ After the build process completes, you can find the executables in the `out/` di ### Linux -Linux support is currently in an experimental phase. While official packages are not yet available, you can build Studio from source: +End users can install Studio from the published `.deb` packages on the [Studio releases page](https://github.com/Automattic/studio/releases). The instructions below cover building from source for development. + +To run the unpackaged app from a clone: ```bash +nvm use npm install npm run package ``` -After building, the executable will be located at `apps/studio/out/Studio-linux-x64/studio`. +The executable will be at `apps/studio/out/Studio-linux-/studio`. To produce a `.deb` package instead, run `npm run make:linux-x64` or `npm run make:linux-arm64`; output lands in `apps/studio/out/make/deb//`. + +#### Creating a Desktop Shortcut + +`.deb` installs register a desktop entry automatically. For source builds you can create one manually: + +```bash +nano ~/.local/share/applications/studio.desktop +``` + +Add the following, replacing `` with the actual path to your clone: + +```ini +[Desktop Entry] +Name=Studio by WordPress.com +Icon=/assets/studio-app-icon.png +Comment=Local WordPress development environment +Exec=/apps/studio/out/Studio-linux-x64/studio %U +Type=Application +Terminal=false +MimeType=x-scheme-handler/wp-studio; +Categories=Development; +``` + +Refresh the application menu and register Studio as the `wp-studio://` handler: + +```bash +update-desktop-database ~/.local/share/applications +xdg-mime default studio.desktop x-scheme-handler/wp-studio +``` + +Without the `xdg-mime` step, browsers will show "Open With… / No Apps Available" when WordPress.com OAuth redirects back to `wp-studio://`. -**Important considerations:** +#### Troubleshooting -- The auto-update feature is not currently supported on Linux builds. -- For Wayland systems, you may need to use additional flags when running the application. -- Some features may not work as expected due to platform-specific implementations. +If `./studio` fails with a permission error, ensure it has execute permissions: -For detailed instructions including how to create a desktop launcher, handle Wayland compatibility, and troubleshoot common issues, see the [**Linux Guide**](./linux.md). +```bash +chmod +x apps/studio/out/Studio-linux-x64/studio +``` + +On Ubuntu 24.04+ and other distributions that restrict unprivileged user namespaces via AppArmor, `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. Allow it persistently: + +```bash +echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf +sudo sysctl --system +``` + +The setting survives reboots and `npm install` runs, so you only need to do this once per machine. This only affects `npm start` during development; installed `.deb` packages ship a properly-configured SUID sandbox binary and are unaffected. + +If you encounter errors about missing libraries on a source build (`.deb` installs declare their dependencies automatically), install the common system packages: + +```bash +# Debian/Ubuntu +sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0 libuuid1 libsecret-1-0 + +# Fedora +sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core libuuid libsecret + +# Arch +sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils at-spi2-core util-linux libsecret +``` ## Localization diff --git a/docs/linux.md b/docs/linux.md deleted file mode 100644 index a83e9c687d..0000000000 --- a/docs/linux.md +++ /dev/null @@ -1,157 +0,0 @@ -# Linux Guide - -Studio is available for Linux. Most users should install the published Debian package; developers can also build from source. - -## Install Studio - -Studio publishes `.deb` packages for x64 and ARM64 architectures, suitable for Debian, Ubuntu, and derivatives. - -1. Download the latest `.deb` for your architecture from the [Studio releases page](https://github.com/Automattic/studio/releases). - - `studio-x64-v.deb` for Intel/AMD 64-bit systems - - `studio-arm64-v.deb` for ARM 64-bit systems - -2. Install the package: - ```bash - sudo apt install ./studio-x64-v*.deb - ``` - -## Updating - -Studio checks for updates automatically and surfaces a dialog with a Download button when a new version is available. Clicking Download opens your browser to fetch the latest `.deb`; install it with `sudo apt install ./.deb` to apply the update. - -You can also re-download the latest `.deb` from the [releases page](https://github.com/Automattic/studio/releases) at any time. - -## Building from Source - -If you're contributing to Studio or running it on a distribution where the `.deb` doesn't work, you can build directly from the repository. - -### Prerequisites - -Ensure you have the following dependencies installed: - -- [Node.js](https://nodejs.org/) — required JavaScript runtime environment -- [Python](https://www.python.org/) — required for building native dependencies -- [setuptools](https://pypi.org/project/setuptools/) — required for building native dependencies - -Many contributors use [`nvm`](https://github.com/nvm-sh/nvm) to manage Node.js installations. - -### Build Steps - -1. **Clone the repository:** - ```bash - git clone https://github.com/Automattic/studio.git - cd studio - ``` - -2. **Install dependencies:** - ```bash - nvm use - npm install - ``` - -3. **Build the application:** - ```bash - npm run package - ``` - - This creates an `out/` folder inside `apps/studio/`. - -4. **Locate the executable:** - - Navigate to `apps/studio/out/Studio-linux-x64/`. Inside, you'll find a `studio` executable. - -5. **Run Studio:** - ```bash - cd apps/studio/out/Studio-linux-x64 - ./studio - ``` - -To build a `.deb` package instead of the unpackaged binary, run `npm run make:linux-x64` or `npm run make:linux-arm64`. The output lands in `apps/studio/out/make/deb//`. - -### Creating a Desktop Shortcut (source builds only) - -`.deb` installs register a desktop entry automatically. For source builds you can create one manually: - -1. **Create the file:** - ```bash - nano ~/.local/share/applications/studio.desktop - ``` - -2. **Add the following content:** - ```ini - [Desktop Entry] - Name=Studio by WordPress.com - Icon=/assets/studio-app-icon.png - Comment=Local WordPress development environment - Exec=/apps/studio/out/Studio-linux-x64/studio %U - Type=Application - Terminal=false - MimeType=x-scheme-handler/wp-studio; - Categories=Development; - ``` - -3. Replace `` with the actual absolute path to your cloned repository. - -4. **Refresh your application menu:** - ```bash - update-desktop-database ~/.local/share/applications - ``` - -5. **Register Studio as the `wp-studio://` handler:** - ```bash - xdg-mime default studio.desktop x-scheme-handler/wp-studio - ``` - Without this, browsers will still show "Open With… / No Apps Available" when WordPress.com OAuth redirects back to `wp-studio://`. - -### Updating a Source Build - -```bash -cd -git pull -npm install -npm run package -``` - -## Troubleshooting - -### Permission issues running a source build - -If you encounter permission issues when running `./studio` from a source build, make sure it has execute permissions: - -```bash -chmod +x apps/studio/out/Studio-linux-x64/studio -``` - -### `npm start` fails with a Chrome sandbox error (Ubuntu 24.04+) - -On distributions that restrict unprivileged user namespaces via AppArmor (notably Ubuntu 24.04+), `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. - -Allow the user-namespace sandbox persistently: - -```bash -echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf -sudo sysctl --system -``` - -The setting survives reboots and `npm install` runs, so you only need to do this once per machine. - -This only affects `npm start` during development; installed `.deb` packages ship a properly-configured SUID sandbox binary and are unaffected. - -### Missing system libraries (source builds) - -`.deb` installs declare their system dependencies automatically. If you're running a source build and encounter errors about missing libraries, install the common dependencies: - -```bash -# Debian/Ubuntu -sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0 libuuid1 libsecret-1-0 - -# Fedora -sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core libuuid libsecret - -# Arch -sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils at-spi2-core util-linux libsecret -``` - -## Contributing - -If you encounter Linux-specific issues or have suggestions for improving Linux support, please [open an issue](https://github.com/Automattic/studio/issues) or submit a pull request. Your feedback helps improve Studio for all Linux users! From 69d811ebc5ed94b8f1221e1c1906b8e7f48e114b Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:10:40 +0200 Subject: [PATCH 06/14] Note Windows ARM64 alongside x64 in installer list --- docs/code-contributions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/code-contributions.md b/docs/code-contributions.md index b9ec459bb7..e2e7252d57 100644 --- a/docs/code-contributions.md +++ b/docs/code-contributions.md @@ -196,7 +196,7 @@ Then open `chrome://inspect` in a Chromium-based browser and click "inspect" nex ## Building Installers Once all required dependencies are installed, you can build installers for the app. -Installers can be built on Mac (Intel or Apple Silicon), Windows, and Linux (x64 or ARM64) using the following commands: +Installers can be built on Mac (Intel or Apple Silicon), Windows (x64 or ARM64), and Linux (x64 or ARM64) using the following commands: ```bash npm install From bc277c3dcd7188701a953453f4ae32c03986fe59 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:12:54 +0200 Subject: [PATCH 07/14] Drop redundant nvm use from Linux source-build steps --- docs/code-contributions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/code-contributions.md b/docs/code-contributions.md index e2e7252d57..606b9ded0f 100644 --- a/docs/code-contributions.md +++ b/docs/code-contributions.md @@ -212,7 +212,6 @@ End users can install Studio from the published `.deb` packages on the [Studio r To run the unpackaged app from a clone: ```bash -nvm use npm install npm run package ``` From aea31a82b0cbd4c979c03f295917a910405f8111 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:16:11 +0200 Subject: [PATCH 08/14] Trim Linux bullet in README to match Mac/Windows style --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e79c166b82..83486a58bd 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ WordPress Studio is free to use for Mac, Windows, and Linux. Simply download the - macOS (Intel or Apple Silicon) - Windows -- Linux — [download the `.deb` from GitHub Releases](https://github.com/Automattic/studio/releases) (x64 or ARM64) and install with `sudo apt install ./studio-*.deb`. +- Linux ## Highlights From caf24673b60ba824a6424b3f108d09ac782b818d Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:17:12 +0200 Subject: [PATCH 09/14] Note arch options for each platform in README download list --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 83486a58bd..f7b3e4b762 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ WordPress Studio is free to use for Mac, Windows, and Linux. Simply download the [Download WordPress Studio](https://developer.wordpress.com/studio/) for: - macOS (Intel or Apple Silicon) -- Windows -- Linux +- Windows (x64 or ARM64) +- Linux (x64 or ARM64) ## Highlights From 55f93808f90ac7443216d8956ff0818dab39127a Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:32:07 +0200 Subject: [PATCH 10/14] Drop end-user pointer from contributor doc's Linux section --- docs/code-contributions.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/code-contributions.md b/docs/code-contributions.md index 606b9ded0f..f5b6726f74 100644 --- a/docs/code-contributions.md +++ b/docs/code-contributions.md @@ -207,8 +207,6 @@ After the build process completes, you can find the executables in the `out/` di ### Linux -End users can install Studio from the published `.deb` packages on the [Studio releases page](https://github.com/Automattic/studio/releases). The instructions below cover building from source for development. - To run the unpackaged app from a clone: ```bash From 92b6f5b521910377a2406607e9546acdf53da430 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:38:52 +0200 Subject: [PATCH 11/14] Split wp-studio:// URL handler registration into its own section --- docs/code-contributions.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/code-contributions.md b/docs/code-contributions.md index f5b6726f74..6ecc30279b 100644 --- a/docs/code-contributions.md +++ b/docs/code-contributions.md @@ -238,14 +238,21 @@ MimeType=x-scheme-handler/wp-studio; Categories=Development; ``` -Refresh the application menu and register Studio as the `wp-studio://` handler: +After creating the file, refresh the application menu so the entry appears: ```bash update-desktop-database ~/.local/share/applications +``` + +#### Registering the `wp-studio://` URL handler + +When working on OAuth/login flows from a source build, register the binary as the `wp-studio://` handler so browser callbacks reach your dev build: + +```bash xdg-mime default studio.desktop x-scheme-handler/wp-studio ``` -Without the `xdg-mime` step, browsers will show "Open With… / No Apps Available" when WordPress.com OAuth redirects back to `wp-studio://`. +This depends on the `.desktop` file from the previous section. Without it, browsers will show "Open With… / No Apps Available" when WordPress.com OAuth redirects back, or hand the callback off to an installed `.deb` build (masking the bug you're trying to debug). #### Troubleshooting From 2f00f6ea7c426a7ed38298818dbce5558244ada9 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 12:43:02 +0200 Subject: [PATCH 12/14] Re-extract Linux contributor notes to docs/linux.md --- docs/code-contributions.md | 79 +----------------------------------- docs/linux.md | 82 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 78 deletions(-) create mode 100644 docs/linux.md diff --git a/docs/code-contributions.md b/docs/code-contributions.md index 6ecc30279b..bc655592e7 100644 --- a/docs/code-contributions.md +++ b/docs/code-contributions.md @@ -205,84 +205,7 @@ npm run make After the build process completes, you can find the executables in the `out/` directory. -### Linux - -To run the unpackaged app from a clone: - -```bash -npm install -npm run package -``` - -The executable will be at `apps/studio/out/Studio-linux-/studio`. To produce a `.deb` package instead, run `npm run make:linux-x64` or `npm run make:linux-arm64`; output lands in `apps/studio/out/make/deb//`. - -#### Creating a Desktop Shortcut - -`.deb` installs register a desktop entry automatically. For source builds you can create one manually: - -```bash -nano ~/.local/share/applications/studio.desktop -``` - -Add the following, replacing `` with the actual path to your clone: - -```ini -[Desktop Entry] -Name=Studio by WordPress.com -Icon=/assets/studio-app-icon.png -Comment=Local WordPress development environment -Exec=/apps/studio/out/Studio-linux-x64/studio %U -Type=Application -Terminal=false -MimeType=x-scheme-handler/wp-studio; -Categories=Development; -``` - -After creating the file, refresh the application menu so the entry appears: - -```bash -update-desktop-database ~/.local/share/applications -``` - -#### Registering the `wp-studio://` URL handler - -When working on OAuth/login flows from a source build, register the binary as the `wp-studio://` handler so browser callbacks reach your dev build: - -```bash -xdg-mime default studio.desktop x-scheme-handler/wp-studio -``` - -This depends on the `.desktop` file from the previous section. Without it, browsers will show "Open With… / No Apps Available" when WordPress.com OAuth redirects back, or hand the callback off to an installed `.deb` build (masking the bug you're trying to debug). - -#### Troubleshooting - -If `./studio` fails with a permission error, ensure it has execute permissions: - -```bash -chmod +x apps/studio/out/Studio-linux-x64/studio -``` - -On Ubuntu 24.04+ and other distributions that restrict unprivileged user namespaces via AppArmor, `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. Allow it persistently: - -```bash -echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf -sudo sysctl --system -``` - -The setting survives reboots and `npm install` runs, so you only need to do this once per machine. This only affects `npm start` during development; installed `.deb` packages ship a properly-configured SUID sandbox binary and are unaffected. - -If you encounter errors about missing libraries on a source build (`.deb` installs declare their dependencies automatically), install the common system packages: - -```bash -# Debian/Ubuntu -sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0 libuuid1 libsecret-1-0 - -# Fedora -sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core libuuid libsecret - -# Arch -sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils at-spi2-core util-linux libsecret -``` +Linux has additional source-build steps and platform-specific troubleshooting — see the [Linux notes](./linux.md). ## Localization diff --git a/docs/linux.md b/docs/linux.md new file mode 100644 index 0000000000..3fa14a0bc4 --- /dev/null +++ b/docs/linux.md @@ -0,0 +1,82 @@ +# Linux + +Linux-specific build steps and troubleshooting for contributors. See also [code-contributions.md](./code-contributions.md) for general setup. + +## Building from Source + +To run the unpackaged app from a clone: + +```bash +npm install +npm run package +``` + +The executable will be at `apps/studio/out/Studio-linux-/studio`. To produce a `.deb` package instead, run `npm run make:linux-x64` or `npm run make:linux-arm64`; output lands in `apps/studio/out/make/deb//`. + +## Creating a Desktop Shortcut + +`.deb` installs register a desktop entry automatically. For source builds you can create one manually: + +```bash +nano ~/.local/share/applications/studio.desktop +``` + +Add the following, replacing `` with the actual path to your clone: + +```ini +[Desktop Entry] +Name=Studio by WordPress.com +Icon=/assets/studio-app-icon.png +Comment=Local WordPress development environment +Exec=/apps/studio/out/Studio-linux-x64/studio %U +Type=Application +Terminal=false +MimeType=x-scheme-handler/wp-studio; +Categories=Development; +``` + +After creating the file, refresh the application menu so the entry appears: + +```bash +update-desktop-database ~/.local/share/applications +``` + +## Registering the `wp-studio://` URL handler + +When working on OAuth/login flows from a source build, register the binary as the `wp-studio://` handler so browser callbacks reach your dev build: + +```bash +xdg-mime default studio.desktop x-scheme-handler/wp-studio +``` + +This depends on the `.desktop` file from the previous section. Without it, browsers will show "Open With… / No Apps Available" when WordPress.com OAuth redirects back, or hand the callback off to an installed `.deb` build (masking the bug you're trying to debug). + +## Troubleshooting + +If `./studio` fails with a permission error, ensure it has execute permissions: + +```bash +chmod +x apps/studio/out/Studio-linux-x64/studio +``` + +On Ubuntu 24.04+ and other distributions that restrict unprivileged user namespaces via AppArmor, `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. Allow it persistently: + +```bash +echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf +sudo sysctl --system +``` + +The setting survives reboots and `npm install` runs, so you only need to do this once per machine. This only affects `npm start` during development; installed `.deb` packages ship a properly-configured SUID sandbox binary and are unaffected. + +If you encounter errors about missing libraries on a source build (`.deb` installs declare their dependencies automatically), install the common system packages: + +```bash +# Debian/Ubuntu +sudo apt-get install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0 libuuid1 libsecret-1-0 + +# Fedora +sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core libuuid libsecret + +# Arch +sudo pacman -S gtk3 libnotify nss libxss libxtst xdg-utils at-spi2-core util-linux libsecret +``` From 8d91f1fd457f9c23ebde671804e150e3a0da34a3 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger <25105483+ivan-ottinger@users.noreply.github.com> Date: Thu, 21 May 2026 13:10:10 +0200 Subject: [PATCH 13/14] Fix CoPilot review: icon path, arch placeholder, and bundle wording --- docs/linux.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/linux.md b/docs/linux.md index 3fa14a0bc4..7803859ab0 100644 --- a/docs/linux.md +++ b/docs/linux.md @@ -4,7 +4,7 @@ Linux-specific build steps and troubleshooting for contributors. See also [code- ## Building from Source -To run the unpackaged app from a clone: +To build a runnable app bundle from a clone: ```bash npm install @@ -21,14 +21,14 @@ The executable will be at `apps/studio/out/Studio-linux-/studio`. To produ nano ~/.local/share/applications/studio.desktop ``` -Add the following, replacing `` with the actual path to your clone: +Add the following, replacing `` with the actual path to your clone and `` with `x64` or `arm64` to match your build: ```ini [Desktop Entry] Name=Studio by WordPress.com -Icon=/assets/studio-app-icon.png +Icon=/apps/studio/assets/studio-app-icon.png Comment=Local WordPress development environment -Exec=/apps/studio/out/Studio-linux-x64/studio %U +Exec=/apps/studio/out/Studio-linux-/studio %U Type=Application Terminal=false MimeType=x-scheme-handler/wp-studio; @@ -56,7 +56,7 @@ This depends on the `.desktop` file from the previous section. Without it, brows If `./studio` fails with a permission error, ensure it has execute permissions: ```bash -chmod +x apps/studio/out/Studio-linux-x64/studio +chmod +x apps/studio/out/Studio-linux-/studio ``` On Ubuntu 24.04+ and other distributions that restrict unprivileged user namespaces via AppArmor, `npm start` may abort with `FATAL: ... The SUID sandbox helper binary was found, but is not configured correctly`. Electron falls back to its SUID sandbox because AppArmor blocks the user-namespace sandbox by default. Allow it persistently: From 5e008b572b4c24ed6eec96e1649c7aa30f6fb740 Mon Sep 17 00:00:00 2001 From: Ivan Ottinger Date: Thu, 21 May 2026 16:16:01 +0200 Subject: [PATCH 14/14] Rewrite section to mention arch autodetection Co-authored-by: Rahul Gavande --- docs/linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/linux.md b/docs/linux.md index 7803859ab0..280a03b095 100644 --- a/docs/linux.md +++ b/docs/linux.md @@ -11,7 +11,7 @@ npm install npm run package ``` -The executable will be at `apps/studio/out/Studio-linux-/studio`. To produce a `.deb` package instead, run `npm run make:linux-x64` or `npm run make:linux-arm64`; output lands in `apps/studio/out/make/deb//`. +The executable will be at `apps/studio/out/Studio-linux-/studio`. To produce a `.deb` package instead, run `npm run make` (auto-detects the host arch); output lands in `apps/studio/out/make/deb//`. To make arch specific build, use `npm run make:linux-x64` or `npm run make:linux-arm64 ## Creating a Desktop Shortcut