Skip to content

feat(docker): run the server as an unprivileged user - #513

Merged
SamTV12345 merged 2 commits into
fix/docker-binary-namefrom
feat/docker-nonroot
Nov 15, 2026
Merged

SamTV12345 merged 2 commits into
fix/docker-binary-namefrom
feat/docker-nonroot

Conversation

@SamTV12345

Copy link
Copy Markdown
Member

Builds on #512 (base fix/docker-binary-name). Once #512 is merged, this PR moves to main.

The image ran the server as root. It now runs as the unprivileged user 65532:65532.

Where the server writes

Directory What Owner
/var SQLite (var/etherpad.db, the default) and the update state, as before 65532
/data settings.json (ETHERPAD_SETTINGS_PATH=/data), also as saved in the admin UI 65532

/ is no longer writable for the server.

Settings

  • settings.json is read from ETHERPAD_SETTINGS_PATH when a file exists there. Otherwise it is read from the working directory, as before, so a file mounted at /settings.json keeps working.
  • The admin UI shows the file the server read and saves into ETHERPAD_SETTINGS_PATH. Before, it could read and write a different file from the one the server started with.
  • config get now loads the settings like config show. Before, it only showed defaults and environment variables, although the README offers it for looking up a value (Terminal #413).
  • The updater already detects containers and never self-updates there. No change is needed for that.

Breaking for SQLite with a /var volume

An existing volume belongs to root, and the server stops with attempt to write a readonly database. The README shows the one-time fix:

docker run --rm -v <volume>:/var alpine chown -R 65532:65532 /var

With Postgres or MySQL and no volume, nothing changes. Please mention this in the release notes.

Tests

  • The kubernetes job:
    • runs the pods with runAsNonRoot: true, allowPrivilegeEscalation: false and all capabilities dropped;
    • checks that the image runs as uid 65532;
    • checks that /var and /data are writable and / is not.
  • New tests lib/settings/settingsfile_test.go and TestReadConfigReadsTheSettingsPath.
  • Locally, all Go tests passed on Memory, SQLite, Postgres and MariaDB.
  • Locally, the image (runtime stage) was run through these cases:
    • the server starts with SQLite in /var (HTTP 200);
    • a file mounted at /settings.json is read;
    • /data/settings.json takes precedence over it;
    • saving into /data works as the user;
    • an old root-owned /var volume fails with the error above and runs after the chown.

Generated by Claude Code

The image ran the server as root. It now runs as 65532:65532, which owns
the two directories the server writes to:

- /var: the SQLite database (var/etherpad.db) and the update state, as
  before;
- /data: settings.json (ETHERPAD_SETTINGS_PATH=/data), also as saved in
  the admin UI. / is not writable for the user any more.

settings.json is read from ETHERPAD_SETTINGS_PATH when that holds one,
otherwise from the working directory as before, so a file mounted at
/settings.json keeps working. The admin UI reads the same file the
server read and saves into ETHERPAD_SETTINGS_PATH (before, it could read
and write another file than the one the server started with).
`config get` loads the settings like `config show`, instead of showing
defaults only.

A /var volume from an older image belongs to root; the README shows the
one-time chown. The kubernetes job runs the pods with runAsNonRoot and
checks the user and the writable directories.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012RMvvMtnCwj6ycD9fwLYVu
@qodo-code-review

Copy link
Copy Markdown

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

@qodo-free-for-open-source-projects

Copy link
Copy Markdown

PR Summary by Qodo

Run Docker images as a non-root user with writable data directories

✨ Enhancement 🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 40+ Minutes

Grey Divider

AI Description

• Run the container as UID 65532, with writable /var and /data directories instead of a writable
 root filesystem.
• Align server, admin UI, and config get behavior around the selected settings file.
• Test non-root operation and document the required ownership migration for existing /var volumes.
Diagram

graph TD
  Image["Runtime image"] --> Server["UID 65532 server"] --> Resolver["Settings selection"] --> Data[("/data settings")]
  Server --> Var[("/var storage")]
  Resolver --> Legacy["/settings.json fallback"]
  Admin["Admin UI"] --> Resolver
  Admin --> Data
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Chown volumes at container startup
  • ➕ Could migrate existing root-owned volumes automatically.
  • ➖ Requires startup privileges, conflicting with runAsNonRoot and the non-root image goal.
2. Rely on Kubernetes volume ownership controls
  • ➕ Can address volume permissions in supported Kubernetes deployments.
  • ➖ Does not cover plain Docker deployments or all volume drivers.

Recommendation: Keep the image-owned directories and non-root runtime. Document the one-time ownership fix for existing /var volumes rather than reintroducing startup privileges; call out this breaking migration in release notes.

Files changed (11) +142 / -32

Enhancement (4) +60 / -10
DockerfileRun the runtime image as UID 65532 +12/-4

Run the runtime image as UID 65532

• Creates owned '/var' and '/data' directories, defaults the settings path to '/data', and switches the runtime user to 65532:65532. Adds shell applets used by the image checks.

Dockerfile

Dockerfile.buildApply non-root ownership to the release image +12/-4

Apply non-root ownership to the release image

• Mirrors the writable-directory ownership, settings path, runtime user, and shell applets in the multi-platform build.

Dockerfile.build

settingsfile.goCentralize settings read and write paths +33/-0

Centralize settings read and write paths

• Adds helpers that prefer 'settings.json' in the configured directory when it exists, otherwise read from the working directory. Writes target the configured directory when one is set.

lib/settings/settingsfile.go

viper.goRead settings from the selected file +3/-2

Read settings from the selected file

• Uses the shared path-selection helper when loading configuration and includes the selected path in preprocessing errors.

lib/settings/viper.go

Bug fix (2) +3 / -9
cli.goLoad file settings for config get +1/-0

Load file settings for config get

• Initializes settings before 'config get', so it reports configured values rather than only defaults and environment values.

lib/settings/cli.go

AdminMessageHandler.goAlign admin settings reads and saves +2/-9

Align admin settings reads and saves

• Reads through the shared settings-selection helper and saves to its configured write destination. Removes the handler's separate path-building function.

lib/ws/AdminMessageHandler.go

Refactor (1) +1 / -1
Settings.goUse the shared settings-path environment constant +1/-1

Use the shared settings-path environment constant

• Replaces the inline environment-variable name used during settings initialization with the shared constant.

lib/settings/Settings.go

Tests (3) +49 / -0
build.ymlVerify runtime UID and writable paths +3/-0

Verify runtime UID and writable paths

• The image smoke test checks UID 65532, confirms '/var' and '/data' are writable, and verifies that the filesystem root is not.

.github/workflows/build.yml

settingsfile_test.goTest settings precedence and configured-path reads +41/-0

Test settings precedence and configured-path reads

• Covers working-directory fallback, configured-directory precedence, write destinations, and 'ReadConfig' loading a settings file from the environment-selected directory.

lib/settings/settingsfile_test.go

manifests.yamlEnforce non-root Kubernetes execution +5/-0

Enforce non-root Kubernetes execution

• Requires a non-root container, disables privilege escalation, and drops all capabilities in the test deployment.

test/kubernetes/manifests.yaml

Documentation (1) +29 / -12
README.mdDocument non-root storage and volume migration +29/-12

Document non-root storage and volume migration

• Explains the image's writable directories and settings-file precedence. Documents the one-time chown required for older root-owned '/var' volumes and updates Docker CLI examples.

README.md

@qodo-free-for-open-source-projects

qodo-free-for-open-source-projects Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Action required

1. Pads can open without login ✓ Resolved
Description
SettingsFile treats every failed os.Stat on /data/settings.json as absence and falls back to
the working-directory file, even when the failure is a permission error. If a mounted /data
directory blocks traversal by user 65532 and no /settings.json exists, startup uses defaults,
including requireAuthentication: false; an existing writable SQLite database can then be served
without its configured login requirement.


Remediation recommended

2. Admin edits can save to the wrong file ✓ Resolved
Description
ReadConfig selects the working-directory file when ETHERPAD_SETTINGS_PATH is unset, but the
admin handler now reads through SettingsFile(retrievedSettings.Root) and still saves through
SettingsWriteFile(retrievedSettings.Root), where Root can be the executable directory. When
those directories differ, the UI can display the active working-directory settings, save its edits
under the executable directory, and subsequently display that saved file even though a restart still
loads the unchanged working-directory file.

3. Mounted legacy API keys stop importing ✓ Resolved
Description
Changing ETHERPAD_SETTINGS_PATH from / to /data also changes Settings.Root, which
initLegacyAPI uses for the default legacy key-file lookup and serveFavicon uses to resolve
relative favicon paths. Deployments with an unimported key mounted at /APIKEY.txt or a relative
favicon mounted under the former root now look under /data instead, preventing clients using that
key from authenticating and causing the favicon handler to serve the bundled icon.

4. Mounted settings cannot be saved ✓ Resolved
Description
Image-layer ownership of /data does not apply to a host directory bind-mounted over it, while
writeFileAtomic needs to create a temporary file in that directory. If an operator uses the
documented /data settings mount with a readable but root-owned, non-writable host directory, the
server loads its settings but every admin save fails under user 65532.

View medium (1)
5. Configuration queries can create files ✓ Resolved
Description
The new InitSettings call makes config get run database-directory initialization before printing
a value. With the default var/etherpad.db path, a query can create var in the working directory
or panic if that directory cannot be created, although querying a value needs no database files.

Grey Divider

Tip of the day
💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Review fixes for the unprivileged image:

- ETHERPAD_SETTINGS_FILE names settings.json (the image:
  /data/settings.json); ETHERPAD_SETTINGS_PATH stays the root (/ in the
  image), so /APIKEY.txt and relative favicon paths resolve as before.
- The read and save locations are settled once at start (Settings.
  SettingsFile/SettingsSaveFile) and used by the start and the admin UI
  alike: the UI no longer shows one file and saves another, e.g. next to
  the executable, that the next start does not read.
- Only a missing settings.json counts as missing. A file that is there but
  cannot be reached (no permission) stops the start, instead of starting
  on defaults without the configured requireAuthentication; so does a
  settings.json that does not parse (before, the server went on with
  empty settings).
- config get/show read the settings without the server's setup, so a
  query creates no database directory.
- README: a host directory bind-mounted at /var or /data keeps its owner
  and must be writable for 65532.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012RMvvMtnCwj6ycD9fwLYVu
@SamTV12345
SamTV12345 merged commit 037c4c5 into fix/docker-binary-name Nov 15, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant