WORKBENCH

4 min read

The Dolt Workbench is a modern, open-source SQL workbench that works with any MySQL and PostgreSQL compatible database, including version controlled databases like Dolt and DoltgreSQL. We successfully built the Dolt Workbench for Mac and Windows, but Linux users kept asking: “When will you support Linux?” This was particularly important for our users in data science and DevOps where Linux is the primary development environment. While electro-builder streamlined macOS/Windows packaging, Linux required some nuanced adjustments. Today’s blog will walk you through how we built the electron app for Linux.

Choosing the package format#

Getting desktop apps to work smoothly across Linux systems is complex. Unlike Windows or macOS where there’s one standard way to install software, Linux has many different versions (like Ubuntu, Fedora, etc). Each has its own software installation format, required components, and setup process. This diversity makes creating one “works everywhere” solution challenging. We evaluated three packaging formats to ensure broad compatibility:

Format	Pros	Cons
AppImage	Single-file, distro-agnostic	Sandboxing challenges
Flatpak	Strong sandboxing	Complex manifest setup
Snap	Auto-updates	Requires Snap Store

We chose AppImage for its simplicity and broad compatibility across distributions. Unlike Snap or Flatpak, it doesn’t require a centralized store or runtime dependencies.

Linux Build Configuration#

Building on our experience creating the Mac and Windows versions, we reused most of our electron-builder configuration. The Linux build required these key adjustments in electron-builder.yaml:

Target Specification & Architecture Support, while macOS uses universal binaries, Linux requires explicit architecture separation.

linux:
  icon: build/linux/icon.png
  category: "Development"
  target:
    - target: "AppImage"
      arch: ["x64", "arm64"]
  artifactName: "${productName}-linux-${arch}.${ext}"
  executableName: "dolt-workbench"
  synopsis: "SQL workbench for MySQL and PostgreSQL"

Linux filesystems are case-sensitive.

extraFiles:
  - from: "build/linux/dolt-${arch}"
    to: resources/dolt # ← lowercase 'resources' crucial for Linux

Storing User Data#

If you haven’t seen the announcement, the Dolt Workbench now ships with a built in Dolt server. So the Workbench bundles a Dolt binary, and you are able to start a local Dolt server from inside the Workbench. We store local databases in platform-specific user data directories:

app.getPath("userData"); // Default for macOS/Windows

Getting this to work on Linux requires additional configuration.

Linux’s XDG Compliance#

While app.getPath("userData") works seamlessly for macOS/Windows, it returns ~/.config/your-app-name on Linux systems. This aligns with XDG’s configuration directory specification but isn’t suitable for large database files.

The XDG standard directories include:

~/.config → For configuration files (small data)
~/.local/share → For application state (large datasets)

Our cross-platform solution handles this by implementing conditional path logic that respects platform conventions while providing a consistent developer experience:

function getDatabasesPath() {
  if (isProd) {
    const dbRoot =
      process.platform === "linux"
        ? path.join(app.getPath("home"), ".local", "share", app.getName())
        : app.getPath("userData");

    return path.join(dbRoot, "databases");
  }
  return devPath;
}

Chromium’s /dev/shm limitation#

Electron apps on Linux may crash due to shared memory limitations in /dev/shm, particularly in VM environments. If you encounter:

FATAL:platform_shared_memory_region_posix.cc(219) # permission error

Adding this line tells Chromium to use /tmp instead of /dev/shm to avoid crashes:

if (process.platform === "linux") {
  app.commandLine.appendSwitch("disable-dev-shm-usage");
}

Running the AppImage#

Running desktop apps on different Linux platforms might require different steps. There can be subtle differences in how these apps are installed and run. We’ve tested the Workbench Linux builds on Ubuntu 22.04 and NixOS 23.11.

Ubuntu Systems#

When running ./Dolt-Workbench-linux-arm64.AppImage, you might see:

The SUID sandbox helper binary was found, but is not configured correctly.

This is due to Ubuntu’s AppImage policies. Try one of these solutions:

Lift restrictions temporarily (lasts until reboot):

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

Run with sandbox disabled (required each launch):

./Dolt-Workbench-linux-arm64.AppImage --no-sandbox

NixOS Systems#

Make the AppImage executable:

chmod +x Dolt-Workbench-linux-arm64.AppImage

Use appimage-run to run the app:

nix-shell -p appimage-run
appimage-run ./Dolt-Workbench-linux-arm64.AppImage

Community Contribution Spotlight#

Dolt community member Joop Kiefte created a seamless NixOS integration using this AppImage guide:

{ pkgs, ... }: let
  pname = "dolt-workbench";
  version = "0.3.20";

  src = pkgs.fetchurl {
    url = "https://github.com/dolthub/dolt-workbench/releases/download/v0.3.20/Dolt-Workbench-linux-x86_64.AppImage";
    hash = "sha256-Tgbg2wrfEwyZvdySj0/wlN4y4Pz/94boeCPk0OS34kA=";
  };
in
pkgs.appimageTools.wrapType2 {
  inherit pname version src;

  extraInstallCommands = ''
    # Desktop integration fixes
    install -m 444 -D ${appimageContents}/${pname}.desktop -t $out/share/applications
    substituteInPlace $out/share/applications/${pname}.desktop \
      --replace 'Exec=AppRun' 'Exec=${pname}'
  '';

  extraBwrapArgs = [ "--bind-try /etc/nixos/ /etc/nixos/" ]; # NixOS-specific binding
}

Check out our available packages here:

AUR: dolt-workbench-appimage
Nixpkg: PR #410265 (vote to accelerate review!)

Wrapping up#

The Dolt Workbench is now truly cross-platform! 🎉 Let us know how it works for you! Share your feedback on Discord or file an issue on GitHub.

Blog

Building a Linux Electron App