Headless Linux

Diagnose startup

Use this appendix only if normal Coinbase startup fails on a Linux server without a graphical session. Although awal is a CLI, it starts an Electron application that needs a display and a working sandbox.

Run as your normal user, without sudo. Inspect the error before reinstalling packages.

Shell

wallet_dir="${XDG_DATA_HOME:-$HOME/.local/share}/awal-nodejs/server"
STARTED_BY_CLI=true WALLET_STANDALONE=true \
  "$wallet_dir/node_modules/.bin/electron" "$wallet_dir/bundle-electron.js"

Expected result

Identify a missing display or an AppArmor user-namespace denial before applying the corresponding remedy. Other errors need their own diagnosis.

Supply a virtual display

If the host has no display, install Xvfb and xauth once. Xvfb supplies an invisible display; a physical GPU is not required.

Shell

sudo apt-get update &&
sudo apt-get install --no-install-recommends xvfb xauth

Expected result

The packages install successfully. Stop on an installation error.

Check AppArmor

Apply an AppArmor exception only after confirming an Electron user-namespace denial. Ask your administrator if you do not manage the host.

Shell

sudo journalctl -k -b --no-pager \
  --grep='apparmor="DENIED".*(userns|electron)' -n 20

Expected result

Look for a matching AppArmor denial. Do not add an exception solely because the wallet failed to start.

Permit the wallet sandbox

An administrator can add a profile for the exact Electron executable. This grants user-namespace access to code run through that binary; it is not a full confinement policy.

If a profile already exists, ask the administrator to review it rather than add another. Otherwise run this as the wallet user; sudo only writes and loads the system profile. Keep Electron's sandbox enabled.

Shell

wallet_dir="${XDG_DATA_HOME:-$HOME/.local/share}/awal-nodejs/server"
wallet_electron="$wallet_dir/node_modules/electron/dist/electron"
if [ -x "$wallet_electron" ]; then
  sudo sh -c 'set -C; cat > /etc/apparmor.d/awal-wallet-electron' <<EOF &&
abi <abi/4.0>,

profile awal-wallet-electron "$wallet_electron" flags=(default_allow) {
  userns,
}
EOF
  sudo apparmor_parser -a /etc/apparmor.d/awal-wallet-electron
else
  printf 'Wallet Electron executable not found: %s\n' "$wallet_electron" >&2
fi

Expected result

Successful loading is normally silent. Stop on errors. To remove this exception later, stop the wallet, unload the profile with sudo apparmor_parser -R /etc/apparmor.d/awal-wallet-electron, then have the administrator remove that file.

Keep Terminal 1 running

Run without sudo and leave Terminal 1 open while using the wallet. This starts no permanent service and does not configure startup after reboot.

Shell

wallet_dir="${XDG_DATA_HOME:-$HOME/.local/share}/awal-nodejs/server"
xvfb-run -a -s '-screen 0 1280x720x24 -nolisten tcp' \
  env STARTED_BY_CLI=true WALLET_STANDALONE=true \
  "$wallet_dir/node_modules/.bin/electron" "$wallet_dir/bundle-electron.js"

Expected result

The wallet application stays running. A GPU-process message alone is not proof of failure; verify CLI status from Terminal 2.

Continue in Terminal 2

Open another terminal on the same host as the same user. Use Terminal 2 for login, funding and purchase while Terminal 1 remains running.

Electron on headless systems · Ubuntu user-namespace profiles

Shell

npx [email protected] status

Expected result

Status reports Running. Return to email sign-in. If startup exits or status fails, inspect the startup error before continuing.