Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -415,6 +415,9 @@ jobs:
test "$(readlink /app)" = /etherpad-go
ls / > /dev/null
! command -v wget && ! command -v nc
test "$(id -u)" = 65532
touch /var/probe /data/probe
! touch /probe 2>/dev/null
'
- name: Create kind cluster
run: |
Expand Down
17 changes: 14 additions & 3 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -28,26 +28,37 @@ RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o app .

FROM alpine:3.24 AS busybox
# The shell's tools for looking around the container (issue 413), on
# purpose without network tools (wget, nc, ...): the server runs as root.
ARG SHELL_APPLETS="sh ls cat less head tail grep find vi env ps df du pwd echo test readlink mkdir cp mv rm chmod"
# purpose without network tools (wget, nc, ...).
ARG SHELL_APPLETS="sh ls cat less head tail grep find vi env ps df du pwd echo test readlink id touch mkdir cp mv rm chmod"
RUN apk add --no-cache busybox-static \
&& mkdir -p /rootfs/bin \
&& cp /bin/busybox.static /rootfs/bin/busybox \
&& for applet in $SHELL_APPLETS; do ln -s /bin/busybox /rootfs/bin/$applet; done \
&& ln -s /etherpad-go /rootfs/app
&& ln -s /etherpad-go /rootfs/app \
&& mkdir -p /writable/var /writable/data

FROM scratch AS runtime
EXPOSE 3000

ENV NODE_ENV=production
# The server runs as an unprivileged user. It writes to /var (the SQLite
# database var/etherpad.db and the update state) and to /data (settings.json
# saved in the admin UI); both belong to that user in the image. A volume
# or host directory mounted there must be writable for 65532: one from an
# image before this one belongs to root; hand it over once with
# docker run --rm -v <volume>:/var alpine chown -R 65532:65532 /var
# The root (assets, /APIKEY.txt, relative favicon paths) stays /.
ENV ETHERPAD_SETTINGS_PATH=/
ENV ETHERPAD_SETTINGS_FILE=/data/settings.json
# Named like in the README, and on PATH: `docker exec <container>
# etherpad-go config show`, or a shell (busybox) with `docker exec -it
# <container> sh` (busybox: sh, ls, cat, vi, ...). /app stays as a link for deployments that start /app.
COPY --from=backend /app/app /etherpad-go
COPY --from=busybox /rootfs /
COPY --from=busybox --chown=65532:65532 /writable/ /


COPY --from=cache /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENV PATH="/:/bin"
USER 65532:65532
ENTRYPOINT ["/etherpad-go"]
17 changes: 14 additions & 3 deletions Dockerfile.build
Original file line number Diff line number Diff line change
Expand Up @@ -21,26 +21,37 @@ RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags="-s -w

FROM alpine:3.24 AS busybox
# The shell's tools for looking around the container (issue 413), on
# purpose without network tools (wget, nc, ...): the server runs as root.
ARG SHELL_APPLETS="sh ls cat less head tail grep find vi env ps df du pwd echo test readlink mkdir cp mv rm chmod"
# purpose without network tools (wget, nc, ...).
ARG SHELL_APPLETS="sh ls cat less head tail grep find vi env ps df du pwd echo test readlink id touch mkdir cp mv rm chmod"
RUN apk add --no-cache busybox-static \
&& mkdir -p /rootfs/bin \
&& cp /bin/busybox.static /rootfs/bin/busybox \
&& for applet in $SHELL_APPLETS; do ln -s /bin/busybox /rootfs/bin/$applet; done \
&& ln -s /etherpad-go /rootfs/app
&& ln -s /etherpad-go /rootfs/app \
&& mkdir -p /writable/var /writable/data

FROM scratch AS runtime
EXPOSE 3000

ENV NODE_ENV=production
# The server runs as an unprivileged user. It writes to /var (the SQLite
# database var/etherpad.db and the update state) and to /data (settings.json
# saved in the admin UI); both belong to that user in the image. A volume
# or host directory mounted there must be writable for 65532: one from an
# image before this one belongs to root; hand it over once with
# docker run --rm -v <volume>:/var alpine chown -R 65532:65532 /var
# The root (assets, /APIKEY.txt, relative favicon paths) stays /.
ENV ETHERPAD_SETTINGS_PATH=/
ENV ETHERPAD_SETTINGS_FILE=/data/settings.json
# Named like in the README, and on PATH: `docker exec <container>
# etherpad-go config show`, or a shell (busybox) with `docker exec -it
# <container> sh` (busybox: sh, ls, cat, vi, ...). /app stays as a link for deployments that start /app.
COPY --from=backend /app/app /etherpad-go
COPY --from=busybox /rootfs /
COPY --from=busybox --chown=65532:65532 /writable/ /


COPY --from=cache /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENV PATH="/:/bin"
USER 65532:65532
ENTRYPOINT ["/etherpad-go"]
53 changes: 41 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,13 +74,7 @@ Get a specific configuration value:
./etherpad-go config get <key>
```

In the Docker image the binary is `etherpad-go` on the `PATH`, and the image has a small shell
(busybox):

```bash
docker exec <container> etherpad-go config show
docker exec -it <container> sh
```
In the Docker image the same commands work through `docker exec` (see [Docker](#docker)).

For customization, copy:

Expand Down Expand Up @@ -145,19 +139,54 @@ Prebuilt images are available via GitHub Container Registry:
ghcr.io/ether/etherpad-go:<version>
```

To open a shell in a running container:
To open a shell in a running container (busybox: `ls`, `cat`, `less`, `grep`, `vi`, …, no
network tools):

```sh
docker exec -it etherpad_go sh
```

The configuration CLI is the image's `etherpad-go`, on the `PATH`:

```sh
docker exec etherpad_go etherpad-go config show
docker exec etherpad_go etherpad-go config get port
```

### Files and the user in the image

The server runs as the unprivileged user `65532`. It writes to two directories, which belong to
that user in the image:

| Directory | What | Mount a volume here for |
|---|---|---|
| `/var` | the SQLite database (`var/etherpad.db`, the default) and the update state | SQLite |
| `/data` | `settings.json` (`ETHERPAD_SETTINGS_FILE=/data/settings.json`), also as saved in the admin UI | settings |

The ownership in the image only covers the directories themselves and a named Docker volume
created from them. **A host directory you bind-mount at `/var` or `/data` keeps its own owner**
and must be writable for `65532`, or the server cannot open SQLite or save settings from the
admin UI:

```sh
docker exec -it etherpad_go /bin/sh
sudo chown -R 65532:65532 ./etherpad-data
```

The configuration CLI is available in the same image:
A `settings.json` mounted at `/settings.json` is still read, as long as `/data/settings.json` does
not exist. Settings saved in the admin UI go to `/data/settings.json`, which is then the one read.
`/APIKEY.txt` and relative favicon paths are still looked up in `/`. If a settings file exists
but cannot be read (no permission), the server does not start rather than fall back to the
defaults.

Upgrading from an image that ran as root: a volume on `/var` belongs to root, and the server
stops with `attempt to write a readonly database`. Hand it over once:

```sh
docker exec etherpad_go /app config show
docker exec etherpad_go /app config get port
docker run --rm -v <volume>:/var alpine chown -R 65532:65532 /var
```

With Postgres or MySQL and no volume, nothing changes.

### Several instances / Kubernetes

With PostgreSQL or MySQL, several Etherpad-Go instances can share one database
Expand Down
11 changes: 8 additions & 3 deletions lib/settings/Settings.go
Original file line number Diff line number Diff line change
Expand Up @@ -433,7 +433,11 @@ type Settings struct {
Plugins map[string]PluginSettings `json:"plugins" mapstructure:"plugins"`

// Untracked fields
Root string `json:"-"`
Root string `json:"-"`
// SettingsFile is the settings.json read at start ("" for none) and
// SettingsSaveFile the one the admin UI saves to (settingsFiles).
SettingsFile string `json:"-" mapstructure:"-"`
SettingsSaveFile string `json:"-" mapstructure:"-"`
GitVersion string `json:"-"`
RandomVersionString string `json:"-"`
}
Expand Down Expand Up @@ -490,7 +494,7 @@ type Options struct {
func InitSettings(logger *zap.SugaredLogger) {
var pathToRoot string

var envPathToSettings = os.Getenv("ETHERPAD_SETTINGS_PATH")
var envPathToSettings = os.Getenv(SettingsPathEnv)
if envPathToSettings != "" {
pathToRoot = envPathToSettings
}
Expand All @@ -515,7 +519,8 @@ func InitSettings(logger *zap.SugaredLogger) {

setting, err := ReadConfig()
if err != nil {
logger.Errorf("Error during reading the config " + err.Error())
// Never start on defaults instead: they do not require a login.
logger.Fatalf("Error during reading the config: %v", err)
return
}

Expand Down
12 changes: 11 additions & 1 deletion lib/settings/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,14 @@ func HandleConfigCommand(logger *zap.SugaredLogger) {
ApplyRegistryDefaults()
switch os.Args[2] {
case "show":
InitSettings(logger)
readConfigForCLI()
configShow()
case "dump":
configDump()
case "env":
configEnv()
case "get":
readConfigForCLI()
configGet(os.Args[3:])
case "init":
configInit()
Expand All @@ -36,6 +37,15 @@ func HandleConfigCommand(logger *zap.SugaredLogger) {
os.Exit(0)
}

// readConfigForCLI loads the settings like the server, without its setup
// (no database directory is created).
func readConfigForCLI() {
if _, err := ReadConfig(); err != nil {
fmt.Fprintln(os.Stderr, "Error reading the config:", err)
os.Exit(1)
}
}

func configShow() {
fmt.Printf(
"%-35s %-35s %-20s %-20s %s\n",
Expand Down
52 changes: 52 additions & 0 deletions lib/settings/settingsfile.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
package settings

import (
"errors"
"fmt"
"os"
)

const (
// SettingsPathEnv is the server's root: assets, APIKEY.txt and relative
// favicon paths are looked up there.
SettingsPathEnv = "ETHERPAD_SETTINGS_PATH"
// SettingsFileEnv is the settings.json to read and to save from the
// admin UI (the Docker image: /data/settings.json, which its
// unprivileged user can write). Unset: settings.json in the working
// directory.
SettingsFileEnv = "ETHERPAD_SETTINGS_FILE"
)

const workingDirSettings = "settings.json"

// settingsFiles are the settings.json the server reads ("" when there is
// none) and the one the admin UI saves to. Reading and saving go by the
// same rule:
//
// - ETHERPAD_SETTINGS_FILE set: that file; while it does not exist yet,
// settings.json in the working directory is read (a file mounted at
// /settings.json keeps working) and the first save creates it;
// - otherwise settings.json in the working directory, for both.
//
// Only a missing file counts as missing: any other error (no permission,
// say) is returned, so the server does not start on defaults, without the
// authentication its settings ask for.
func settingsFiles() (read, save string, err error) {
save = workingDirSettings
if f := os.Getenv(SettingsFileEnv); f != "" {
save = f
}
for _, candidate := range []string{save, workingDirSettings} {
_, statErr := os.Stat(candidate)
if statErr == nil {
return candidate, save, nil
}
if !errors.Is(statErr, os.ErrNotExist) {
return "", save, fmt.Errorf("settings file %s: %w", candidate, statErr)
}
if candidate == workingDirSettings {
break
}
}
return "", save, nil
}
80 changes: 80 additions & 0 deletions lib/settings/settingsfile_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
package settings

import (
"os"
"path/filepath"
"testing"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func TestSettingsFiles(t *testing.T) {
wd := t.TempDir()
t.Chdir(wd)
file := filepath.Join(t.TempDir(), "settings.json")

read, save, err := settingsFiles()
require.NoError(t, err)
assert.Equal(t, "", read, "none yet")
assert.Equal(t, "settings.json", save, "unset: the working directory")

require.NoError(t, os.WriteFile("settings.json", []byte("{}"), 0o644))
read, save, err = settingsFiles()
require.NoError(t, err)
assert.Equal(t, "settings.json", read)
assert.Equal(t, "settings.json", save, "read and saved in the same place")

// ETHERPAD_SETTINGS_FILE not there yet: the working directory's file is
// read (one mounted at /settings.json), the first save creates it.
t.Setenv(SettingsFileEnv, file)
read, save, err = settingsFiles()
require.NoError(t, err)
assert.Equal(t, "settings.json", read)
assert.Equal(t, file, save)

require.NoError(t, os.WriteFile(file, []byte("{}"), 0o644))
read, save, err = settingsFiles()
require.NoError(t, err)
assert.Equal(t, file, read)
assert.Equal(t, file, save)

// ETHERPAD_SETTINGS_PATH (the root for assets, APIKEY.txt and the
// favicon) has no say in where settings.json is.
t.Setenv(SettingsPathEnv, t.TempDir())
read, _, err = settingsFiles()
require.NoError(t, err)
assert.Equal(t, file, read)
}

// A settings file that is there but cannot be reached must stop the
// start: falling back to defaults would drop requireAuthentication.
func TestSettingsFilesRefusesUnreadable(t *testing.T) {
if os.Geteuid() == 0 {
t.Skip("root reads every directory")
}
t.Chdir(t.TempDir())
locked := t.TempDir()
require.NoError(t, os.WriteFile(filepath.Join(locked, "settings.json"), []byte(`{"requireAuthentication": true}`), 0o644))
require.NoError(t, os.Chmod(locked, 0o000))
t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
t.Setenv(SettingsFileEnv, filepath.Join(locked, "settings.json"))

_, _, err := settingsFiles()
assert.ErrorIs(t, err, os.ErrPermission)
_, err = ReadConfig()
assert.Error(t, err)
}

func TestReadConfigReadsTheSettingsFile(t *testing.T) {
t.Chdir(t.TempDir())
file := filepath.Join(t.TempDir(), "settings.json")
t.Setenv(SettingsFileEnv, file)
require.NoError(t, os.WriteFile(file,
[]byte(`{ "title": "From the settings file", /* comment */ }`), 0o644))
s, err := ReadConfig()
require.NoError(t, err)
assert.Equal(t, "From the settings file", s.Title)
assert.Equal(t, file, s.SettingsFile)
assert.Equal(t, file, s.SettingsSaveFile)
}
Loading
Loading