Install Gophenberg on a Linux server

.github/workflows/ci.yml

@@ -302,6 +302,36 @@ jobs:
             openssl pkeyutl -verify -pubin -inkey throwaway.pub.pem -rawin -in digest.bin -sigfile sig.bin
           done
 
+  server-install:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 26
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+      - run: shellcheck test/installer/scenarios.sh
+      - name: Install, update, roll back, uninstall and install Gophenberg again on this runner
+        run: bash test/installer/scenarios.sh run
+      - name: Gather the journals, the update state and the install record
+        if: failure() || cancelled()
+        run: bash test/installer/scenarios.sh logs "$RUNNER_TEMP/server-install-logs"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: failure() || cancelled()
+        with:
+          name: server-install-logs
+          path: ${{ runner.temp }}/server-install-logs/
+          retention-days: 1
+
   image-check:
     runs-on: ubuntu-latest
     timeout-minutes: 15

docs/src/content/docs/self-hosting/configuration.md

@@ -8,9 +8,9 @@ Gophenberg is configured entirely through environment variables. A
 environment variables win over it. Every command reads the same
 settings, the `.env` file included, so `migrate` or an account
 command run beside the server finds the database the server uses.
-The one exception is `server:install`, which reads
-[the server settings](#the-server-settings) and takes none of its
-settings from a `.env` file.
+The two exceptions are `server:install` and `server:uninstall`, which
+read [the server settings](#the-server-settings) and take none of
+their settings from a `.env` file.
 
 Every value is trimmed of the spaces around it. A padded value works
 as if it had none, and a value made only of spaces counts as unset,
@@ -95,7 +95,7 @@ so it takes the default.
 | `GOPHENBERG_UPDATE_BACKUPS_KEEP` | No | `3` | How many database backups the `backups` folder of the install root keeps |
 | `GOPHENBERG_PG_DUMP_BIN` | No | `pg_dump` | The `pg_dump` an update backs up the database with, a name found on the path or a full path. Its major version must be at least the server's |
 | `GOPHENBERG_UPDATE_ATTEMPTS` | No | `3` | How many times the build an update switched to may try to start. The next start goes back to the build before it, or stays down when the update raised the minimum version and its new build reached the database |
-| `GOPHENBERG_UPDATE_VERIFY_TIMEOUT` | No | `1m` | How long the first start of a new build has to check itself: the server listens, then `/admin/` and `/api/locale` answer 200 and `/` answers below 500 over loopback |
+| `GOPHENBERG_UPDATE_VERIFY_TIMEOUT` | No | `1m` | How long the first start of a new build has to check itself: the server listens, then `/admin/` and `/api/locale` answer 200 and `/` answers below 500 over loopback. `server:install` reads its own from [the server settings](#the-server-settings) |
 | `GOPHENBERG_UPDATE_VERSIONS_KEEP` | No | `2` | How many of the newest builds the `versions` folder keeps once a new build passes its check. The builds the `current` and `previous` links name always stay |
 | `GOPHENBERG_FEED_TITLE` | No | `Gophenberg` | The RSS channel title |
 | `GOPHENBERG_FEED_ITEMS` | No | `20` | How many posts the RSS feed carries |
@@ -569,7 +569,7 @@ first of these that gives it a value:
 | `GOPHENBERG_INSTALL_ROOT` | `/opt/gophenberg` | The install root, an absolute path of letters, digits, dots, hyphens, underscores and slashes alone |
 | `GOPHENBERG_PUBLIC_URL` | | `https://` and the domain the site answers at, with nothing after it. Every run needs it, from `-domain`, the environment or `server.env` |
 | `GOPHENBERG_ADDR` | `127.0.0.1:8081` | The address the site listens on. It must be a loopback address with a port, since Caddy, or your own web server, runs on the same server and forwards to it. Its port must not be 5432, PostgreSQL's, or with Caddy 80 or 443 |
-| `GOPHENBERG_INSTALL_WEB_SERVER` | `caddy` | The web server in front of the site, from the `-web-server` flag. `caddy` has the install set Caddy up, and `none` keeps a web server of your own, see [with your own web server](/self-hosting/commands/#with-your-own-web-server). A later run keeps it. It stops when a flag or the environment asks for the other one, and when the line says `none` on a server the install set Caddy up on |
+| `GOPHENBERG_INSTALL_WEB_SERVER` | `caddy` | The web server in front of the site, from the `-web-server` flag. `caddy` has the install set Caddy up, and `none` keeps a web server of your own, see [with your own web server](/self-hosting/commands/#with-your-own-web-server). A later run keeps it. It stops when a flag or the environment asks for the other one, and when the line says `none` while Gophenberg's Caddy site is still there, see [moving to your own web server](/self-hosting/commands/#moving-to-your-own-web-server) |
 | `GOPHENBERG_INSTALL_CERTIFICATE_EMAIL` | The `-admin-email` flag | The email Caddy gives Let's Encrypt for the HTTPS certificate, one plain address with no braces. Empty leaves it out, and `localhost` never uses it |
 | `GOPHENBERG_SERVICE_RESTART_DELAY` | `5s` | How long systemd waits before it starts the site again, `RestartSec` of the site's unit, in whole seconds |
 | `GOPHENBERG_SERVICE_START_LIMIT_INTERVAL` | `300s` | The window systemd counts the site's starts in, `StartLimitIntervalSec` of the site's unit, in whole seconds |
@@ -583,6 +583,7 @@ first of these that gives it a value:
 | `GOPHENBERG_INSTALL_DOMAIN_CHECK_TIMEOUT` | `10s` | How long the domain check waits for each fetch of its token |
 | `GOPHENBERG_INSTALL_HTTPS_WAIT` | `2m` | How long the HTTPS step waits for `https://<domain>/admin/` to answer |
 | `GOPHENBERG_INSTALL_POLL_INTERVAL` | `1s` | The pause between two tries in each wait of the steps |
+| `GOPHENBERG_UPDATE_VERIFY_TIMEOUT` | `1m` | How long the step that starts the site waits for its first start to pass the same check an update's first start does. Updates take theirs from the site's `.env` |
 
 With `GOPHENBERG_INSTALL_WEB_SERVER=none`, the run uses neither the
 certificate email, `GOPHENBERG_MAINTENANCE_RETRY_AFTER`,
@@ -602,6 +603,10 @@ gophenberg: GOPHENBERG_ADDR: must be a loopback address with a port, such as 127
 in its environment, the run stops, since the install sets up a
 PostgreSQL of its own.
 
+[`server:uninstall`](/self-hosting/commands/#serveruninstall) reads
+only `server.env` and the defaults, so nothing in its environment
+changes what it removes.
+
 ### The server.env file
 
 `/etc/gophenberg/server.env` holds the settings `server:install` acts
@@ -630,17 +635,17 @@ the file keeps what you wrote:
 
 - A line you changed keeps your value, and a line missing from the
   file gets its default. A `GOPHENBERG_INSTALL_WEB_SERVER` line changed
-  to `none` on a server the install set Caddy up on stops the run, as
-  the install record shows.
+  to `none` stops the run while Gophenberg's Caddy site is still there.
 - A flag or an environment value given on that run replaces its line,
   except `GOPHENBERG_INSTALL_WEB_SERVER`, where asking for the other
-  web server stops the run.
+  web server stops the run. So does asking for another
+  `GOPHENBERG_INSTALL_ROOT`.
 - A line you added, such as `GOPHENBERG_INSTALL_DISK_FLOOR_MB=2048`,
   is read and kept, after the eleven lines above in the order of the
   names. A comment is not kept.
-- The last six settings of the table, from
+- The last seven settings of the table, from
   `GOPHENBERG_INSTALL_MEMORY_FLOOR_MB` to
-  `GOPHENBERG_INSTALL_POLL_INTERVAL`, are not among the eleven lines.
+  `GOPHENBERG_UPDATE_VERIFY_TIMEOUT`, are not among the eleven lines.
   Given only in the environment, one is used for that run but not
   written into the file.
 
@@ -673,6 +678,8 @@ GOPHENBERG_DATABASE_WAIT=60s
 - `GOPHENBERG_DATABASE_WAIT` keeps the value the site's `.env` holds,
   and `60s` while it holds none. Every other line is kept, after
   these, in the order of the names. A comment is not kept.
+- A dry run prints each kept line as its name and `(kept as it is)`.
+  The file keeps the value.
 
 `server:install` takes none of its own settings from this file, since
 the site's own user can write it, so a `GOPHENBERG_INSTALL_ROOT` line
@@ -687,8 +694,9 @@ could not read stops the run, naming the file:
 gophenberg: /opt/gophenberg/.env: GOPHENBERG_SHUTDOWN_GRACE: must be a duration like 30s, got "soon"
 ```
 
-A dry run prints the file to your terminal, so the run also stops on
-a file that could reach the terminal or hold the run instead:
+A dry run still prints the name of every line to your terminal, so
+the run also stops on a file that could reach the terminal or hold
+the run instead:
 
 - a line whose name or value holds a control character other than a
   tab, such as the escape character, or a byte that is not UTF-8

docs/src/content/docs/self-hosting/updates-and-backups.md

@@ -812,9 +812,10 @@ have fixed what failed, run:
 /opt/gophenberg/current/gophenberg update:apply -to 1.4.1 -retry
 ```
 
-Under systemd, a service that stops at exit code 76 can start a
-rollback unit, which runs `update:rollback -after-failure` and then
-starts the service again, see
+Under systemd, once systemd gave up restarting the site, a rollback
+unit runs `update:rollback -after-failure` and then starts the
+service again. A start that failed its check with exit code 76 and a
+build that keeps crashing both count, see
 [update:rollback](/self-hosting/commands/#updaterollback). To take
 back an update that passed its check, run `update:rollback` and
 restart Gophenberg. It refuses that version from then on too.

internal/app/core_updates.go

@@ -181,9 +181,7 @@ func rolledBack(settings updater.Settings, env gonsole.Env, afterFailure bool) (
 	if !afterFailure {
 		return updater.Rollback(settings)
 	}
-	return updater.RollbackAfterFailure(settings, updater.Failure{
-		ServiceResult: env.Getenv("MONITOR_SERVICE_RESULT"), ExitStatus: env.Getenv("MONITOR_EXIT_STATUS"),
-	})
+	return updater.RollbackAfterFailure(settings, updater.Failure{ServiceResult: env.Getenv("MONITOR_SERVICE_RESULT")})
 }
 
 // updateStatusCommand returns the command that shows the builds of a server install, its last update and backups.

internal/app/program_test.go

@@ -16,8 +16,8 @@ import (
 var listedCommands = []string{
 	"check", "help", "list", "migrate", "seed", "serve", "version",
 	"account:create-admin", "account:disable", "account:enable", "account:grant-role", "account:list",
-	"account:records", "account:role", "server:install", "update:apply", "update:check", "update:rollback",
-	"update:status",
+	"account:records", "account:role", "server:install", "server:uninstall", "update:apply", "update:check",
+	"update:rollback", "update:status",
 }
 
 func TestProgramListsEveryCommandWhenNoneIsNamed(t *testing.T) {
@@ -53,6 +53,8 @@ func TestProgramListsEveryCommandWhenNoneIsNamed(t *testing.T) {
 		"  account:role          set one account's role",
 		" server",
 		"  server:install        install Gophenberg on this Linux server with PostgreSQL, Caddy and a systemd service",
+		"  server:uninstall      remove what server:install set up on this server, keeping the site's data unless " +
+			"-delete-data",
 		" update",
 		"  update:apply          update this server install to a newer Gophenberg, then ask for a restart",
 		"  update:check          check the update site for a newer Gophenberg and keep what it found",

internal/app/server_commands.go

@@ -27,9 +27,28 @@ func serverCommands(machine installer.Machine) []gonsole.Command {
 		Summary: "install Gophenberg on this Linux server with PostgreSQL, Caddy and a systemd service",
 		Flags:   installFlags,
 		Run:     runInstall(machine),
+	}, {
+		Name:    serverNamespace + "uninstall",
+		Summary: "remove what server:install set up on this server, keeping the site's data unless -delete-data",
+		Flags:   uninstallFlags,
+		Writes:  true,
+		Run:     runUninstall(machine),
 	}}
 }
 
+// uninstallFlags declares the flags of server:uninstall.
+func uninstallFlags(fs *flag.FlagSet) {
+	fs.Bool("delete-data", false, "also drop the database and its role, and remove the install root, "+
+		"/etc/gophenberg/server.env and the system user gophenberg")
+}
+
+// runUninstall returns the run of server:uninstall on machine.
+func runUninstall(machine installer.Machine) func(context.Context, gonsole.Call) error {
+	return func(ctx context.Context, call gonsole.Call) error {
+		return installer.Uninstall(ctx, machine, call, call.Flags["delete-data"] == "true")
+	}
+}
+
 // installFlags declares the flags of server:install.
 func installFlags(fs *flag.FlagSet) {
 	fs.String("domain", "",

internal/app/server_commands_test.go

@@ -6,13 +6,16 @@ import (
 	"bytes"
 	"errors"
 	"flag"
+	"io/fs"
 	"maps"
 	"os"
 	"os/exec"
+	"os/user"
 	"path/filepath"
 	"slices"
 	"strconv"
 	"strings"
+	"syscall"
 	"testing"
 	"time"
 
@@ -83,6 +86,110 @@ func TestServerInstallOffersEveryFlagOfTheInstallLine(t *testing.T) {
 	}
 }
 
+func TestServerUninstallOffersDeleteDataAndYes(t *testing.T) {
+	t.Parallel()
+
+	got := testkit.Run(t, Program(testkit.Getenv(nil), noPlugins), "", "help", "server:uninstall")
+
+	want := strings.Join([]string{
+		"remove what server:install set up on this server, keeping the site's data unless -delete-data",
+		"",
+		"Usage:",
+		"  gophenberg server:uninstall [flags]",
+		"",
+		"Flags:",
+		"  -delete-data",
+		"    \talso drop the database and its role, and remove the install root, /etc/gophenberg/server.env and the " +
+			"system user gophenberg",
+		"  -yes",
+		"    \tapply the change, a dry run without it",
+		"",
+	}, "\n")
+	if got.Code != gonsole.ExitDone || got.Stdout != want {
+		t.Errorf("help server:uninstall = %d, stdout %q, want 0 and\n%s", got.Code, got.Stdout, want)
+	}
+	if got.Stderr != "" {
+		t.Errorf("help server:uninstall noted %q, want nothing", got.Stderr)
+	}
+}
+
+// rootOwned describes a file as root's, whatever user the test runs as.
+type rootOwned struct{ fs.FileInfo }
+
+// Sys returns the system description of the file with root as its owner.
+func (i rootOwned) Sys() any {
+	stat := *i.FileInfo.Sys().(*syscall.Stat_t)
+	stat.Uid = 0
+	return &stat
+}
+
+// lstatAsRoot describes the file at path as os.Lstat does, with root as its owner.
+func lstatAsRoot(path string) (fs.FileInfo, error) {
+	info, err := os.Lstat(path)
+	if err != nil {
+		return nil, err
+	}
+	return rootOwned{info}, nil
+}
+
+// recordedMachine returns a server root runs on whose install record names the PostgreSQL it installed and the user.
+func recordedMachine(t *testing.T) installer.Machine {
+	t.Helper()
+	root := t.TempDir()
+	folder := filepath.Join(root, "var/lib/gophenberg-installer")
+	if err := os.MkdirAll(folder, 0o700); err != nil {
+		t.Fatalf("making the installer's folder: %v", err)
+	}
+	record := []byte(`{"installer": "0.19.0", "installed": ["postgresql"]}` + "\n")
+	if err := os.WriteFile(filepath.Join(folder, "install.json"), record, 0o600); err != nil {
+		t.Fatalf("writing the install record: %v", err)
+	}
+	return installer.Machine{
+		Root: root, Lstat: lstatAsRoot, Euid: func() int { return 0 },
+		LookupUser: func(name string) (*user.User, error) { return &user.User{Username: name}, nil },
+	}
+}
+
+func TestServerUninstallListsWhatItKeepsAndEndsWithTheDryRunLineWithoutYes(t *testing.T) {
+	t.Parallel()
+
+	got := testkit.Run(t, onMachine(nil, recordedMachine(t)), "", "server:uninstall")
+
+	want := "server:uninstall finds nothing left to remove.\nserver:uninstall keeps:\n  the system user gophenberg\n" +
+		"  /var/lib/gophenberg-installer/install.json, so a later install picks up what is kept\n" +
+		"  the packages server:install installed, which sudo apt-get purge postgresql removes\n"
+	if got.Code != gonsole.ExitDone || got.Stdout != want {
+		t.Errorf("server:uninstall = %d, stdout %q, stderr %q, want 0 and\n%s", got.Code, got.Stdout, got.Stderr, want)
+	}
+	if line := "gophenberg: dry run, nothing changed, pass -yes to apply\n"; got.Stderr != line {
+		t.Errorf("server:uninstall noted %q, want gonsole's dry run line %q", got.Stderr, line)
+	}
+}
+
+func TestServerUninstallHandsDeleteDataToTheUninstall(t *testing.T) {
+	t.Parallel()
+
+	got := testkit.Run(t, onMachine(nil, recordedMachine(t)), "", "server:uninstall", "-delete-data")
+
+	want := "server:uninstall removes:\n  the system user gophenberg\nserver:uninstall keeps:\n"
+	if got.Code != gonsole.ExitDone || !strings.HasPrefix(got.Stdout, want) {
+		t.Errorf("server:uninstall -delete-data = %d, stdout %q, stderr %q, want 0 and the user removed", got.Code,
+			got.Stdout, got.Stderr)
+	}
+}
+
+func TestServerUninstallRefusesAPlainUser(t *testing.T) {
+	t.Parallel()
+
+	machine := recordedMachine(t)
+	machine.Euid = func() int { return 1000 }
+
+	got := testkit.Run(t, onMachine(nil, machine), "", "server:uninstall", "-yes")
+
+	wantAnswer(t, got, gonsole.ExitFailed,
+		"gophenberg: server:uninstall must run as root, such as with sudo, so nothing was changed")
+}
+
 func TestServerInstallHandsTheInstallerEveryFlagTheLineSets(t *testing.T) {
 	t.Parallel()
 
@@ -124,9 +231,9 @@ func TestServerInstallRefusesAnInstallRootThatIsNotAbsolute(t *testing.T) {
 	t.Parallel()
 
 	env := map[string]string{"GOPHENBERG_INSTALL_ROOT": "planted/root"}
+	machine := installer.Machine{Root: t.TempDir(), Lstat: lstatAsRoot, Euid: func() int { return 0 }}
 
-	got := testkit.Run(t, onMachine(env, installer.Machine{Root: t.TempDir()}), "", "server:install", "-dry-run",
-		"-domain", "example.com")
+	got := testkit.Run(t, onMachine(env, machine), "", "server:install", "-dry-run", "-domain", "example.com")
 
 	wantAnswer(t, got, gonsole.ExitFailed,
 		`gophenberg: GOPHENBERG_INSTALL_ROOT: must be an absolute path, got "planted/root"`)
@@ -230,6 +337,9 @@ func TestOnlyTheServerCommandsLeaveTheDotEnvFileUnread(t *testing.T) {
 
 func TestMainBinaryLeavesTheDotEnvFileUnreadForTheServerCommands(t *testing.T) {
 	t.Parallel()
+	if os.Geteuid() == 0 {
+		t.Skip("running as root, which takes server:install past its root check onto the real server")
+	}
 
 	binary, env := testkit.CoverBinary(t, "GOPHENBERG_", "gophenberg")
 	folder := t.TempDir()
@@ -238,14 +348,13 @@ func TestMainBinaryLeavesTheDotEnvFileUnreadForTheServerCommands(t *testing.T) {
 		t.Fatalf("writing the .env file: %v", err)
 	}
 
-	install, code := stderrOf(t, binary, append(slices.Clone(env), "GOPHENBERG_INSTALL_MEMORY_FLOOR_MB=0"), folder,
-		"server:install", "-dry-run", "-domain", "example.com")
+	install, code := stderrOf(t, binary, env, folder, "server:install", "-dry-run", "-domain", "example.com")
 	status, _ := stderrOf(t, binary, env, folder, "update:status")
 
-	want := "gophenberg: GOPHENBERG_INSTALL_MEMORY_FLOOR_MB: must stand above zero, got \"0\"\n"
+	want := "gophenberg: server:install must run as root, such as with sudo, so nothing was changed\n"
 	if install != want || code != gonsole.ExitFailed {
-		t.Errorf("server:install = %d, printing %q, want %d and only the memory floor of its environment %q, the "+
-			".env file never read", code, install, gonsole.ExitFailed, want)
+		t.Errorf("server:install = %d, printing %q, want %d and only the root line %q, nothing of the .env file",
+			code, install, gonsole.ExitFailed, want)
 	}
 	if want := `GOPHENBERG_INSTALL_ROOT: must be an absolute path, got "planted/root"`; !strings.Contains(status, want) {
 		t.Errorf("update:status printed %q, want the .env file read and %q", status, want)