Skip to content

docs: the standalone bw does not fit in /run/nodkey-setup on a small host #107

Closed

Description

@groupsky

What happened

docs/setup.md section 5, "Where bws and bw come from", downloads and unpacks the standalone bw in /run/nodkey-setup. On 2026-10-27, on a Debian 13 VPS with 1 GB RAM, unzip bw-linux-2026.9.1.zip bw failed there: not enough space.

/run is a tmpfs, and its size is a small part of the RAM (on Debian, 10 % by default: about 100 MB here). The zip is 45.6 MB, and the unpacked bw is larger, so the two do not fit there together. Any small broker host will meet this.

Section 3 made /run/nodkey-setup for plain keys and tokens, so that they never reach the disk. The bw and bws downloads hold no secret, so they do not need it.

Fix

  • In section 5, download and unpack bw and bws in a private directory on disk, for example install -d -m 0700 /root/bw-setup. Remove the directory after install.
  • Say in one sentence that /run/nodkey-setup is only for secrets (section 3), and why the downloads go elsewhere.
  • If the text suggests bw --version as a check: as root, it makes /root/.config/Bitwarden CLI with an empty data.json. It does no harm, but say to remove it, so that nobody logs in to Bitwarden as root on the broker host by mistake.

Done when

  • Section 5 unpacks bw and bws in a private directory on disk, and removes it after the install.
  • Section 3 or 5 says that /run/nodkey-setup is for secrets only.
  • The new steps are tried on a host, or in a container, where /run is limited to 100 MB.

Activity

  1. groupsky commented on Nov 9, 2026

    @groupsky
    ContributorAuthor

    Done in #161 (squash commit 60202fa).

    • Section 5 unpacks bw and bws in a private directory on disk, and removes it after the install: docs/setup.md, "Where bws and bw come from" now uses install -d -o root -g root -m 0700 /root/bw-setup and ends with cd / && rm -r /root/bw-setup.
    • Section 3 or 5 says that /run/nodkey-setup is for secrets only: both do. Section 3, "The user and the directories", says so; section 5 says why the downloads go elsewhere (the bw zip is about 46 MB, the unpacked bw about 140 MB).
    • The new steps are tried with /run limited to 100 MB: on 2026-11-09, in docker run --tmpfs /run:size=100m debian:13. The old steps failed with bw: write error (disk full?); the new steps installed bws 2.1.0 (checksum OK) and bw 2026.9.1, and removed /root/bw-setup. Details in the PR body.

    The guide does not suggest bw --version, so the note about /root/.config/Bitwarden CLI was not needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions