Skip to content

Updates and backups

Two operational jobs: keeping Gophenberg current, and being able to put it back after something goes wrong.

These steps update the Docker image. A server install that runs the binary itself updates with one command, see updating a server install.

Your compose file pins an exact version, so nothing updates behind your back:

Terminal window
# 1. edit compose.yaml: change both image tags to the new version
docker compose pull
docker compose run --rm -T gophenberg check
docker compose up -d

check reads your settings with the new version while the old one still serves, and names the ones it refuses, see what stops startup. It never connects to the database, so a problem there, such as the role the site logs in as, shows only when the server starts. Migrations run automatically when the new version starts, and docker compose run --rm -T gophenberg migrate applies them without starting the server. Two copies that migrate at once never apply the same migration twice, the second waits for the first and then finds nothing left to do. While Gophenberg is below 1.0, read the release notes first, since a release can change behavior.

Updating to 0.20.1 from an earlier 0.20 release runs no migration, changes no setting and needs no theme rebuild. Its Updates screen says the site stays down only when a new version fails after it reaches the database, and how to bring it back. On a server install, run the install line again for its new installer, which sets up newer Ubuntu and Debian releases and names what each step runs. Rolling back within 0.20 deletes nothing.

Updating to 0.20 from the release before it runs no migration. The database stays as that release left it, so its image still starts on it. The first start only adds a few rows. One is the oldest version allowed to run on the database, and that is the release before this one, so its image still starts, see going back to an older version. Back up the database before the first start on this release, as before any update.

This release serves every theme kit the release before it serves, so no theme needs rebuilding. It also runs themes built on @gophenberg/astro 0.16.0, which the release before this one turns away with kit_unsupported. That kit renames the type of one image size from MediaRendition to MediaSubSize, so a theme that imports MediaRendition has to import MediaSubSize instead once it moves to that kit.

Before you update, check these three, since each one can stop the server at start:

  • The role the site logs in as. The server now stops when it logs in to PostgreSQL as postgres, as the compose file from the Install page of the release before this one does, or as any other role that can reach the database server, see the PostgreSQL server. In the same edit as the image tag, add the database-owner service from Install, make gophenberg depend on it as that file does, and point GOPHENBERG_DATABASE_URL at the new role, see moving a site off postgres. To update first and move later, set GOPHENBERG_SUPERUSER_POLICY=warn, which logs a warning and serves. check cannot see the role.
  • GOPHENBERG_WEB_DIR. The admin is now built into the binary, and the image no longer holds /web. A compose file or .env that sets GOPHENBERG_WEB_DIR=/web, as the image of the release before this one did, now stops the server, so delete that line. check names it.
  • PORT. A site that sets neither GOPHENBERG_ADDR nor GOPHENBERG_SOCKET now listens on every interface at PORT when its environment exports one. The release before this one ignored PORT and kept to localhost:8081. A PORT that is not a whole number from 1 to 65535 stops the server. Set GOPHENBERG_ADDR to keep the old address. The image sets GOPHENBERG_ADDR, so a Docker site is not touched. See listening on a small host.

Some things work differently after this update:

  • PostgreSQL 14 and older now stop serve, migrate and every command that migrates, with a message naming the version found. A site on the release before this one already runs 15 or newer, since its migrations need it.

  • serve now waits up to 60 seconds for a PostgreSQL that is not up yet, where it stopped at once. A wrong password, a missing role or a missing database still stop it at once. See a database that starts late.

  • The site now asks https://updates.gophenberg.org for a newer Gophenberg twice a day, as the cron job core/update-check. It sends nothing about the site but its version, and installs nothing. A site with no internet access logs cron job failed at Warn with job=core/update-check at every check, so set GOPHENBERG_UPDATE_CHECKS=false there. The admin role now sees an Updates screen, and a line above every admin screen while a newer version waits. See how a site hears of a new version.

  • A site can now be installed on a Linux server with one command, and an administrator updates such an install from the admin or with update:apply. A Docker site keeps updating by hand, as above. See Install on a Linux server.

  • A binary you build yourself serves the admin only when you copy the admin build into internal/webui/dist and build with -tags embedweb, as make build-release and the Dockerfile do. A plain go build serves a placeholder page in its place, unless GOPHENBERG_WEB_DIR names an admin build. A GOPHENBERG_WEB_DIR that still names the admin built for the release before this one serves that old admin, so build the admin again or unset it. Building from source needs Go 1.27.3.

  • Thirty-three settings are new, beside PORT, and none is required. Most of them tune the update checks and the updates of a server install. A value out of range or outside its list stops startup, so run check with your settings first. See configuration.

  • On PostgreSQL, GOPHENBERG_DATABASE_MAX_CONNS now caps the site’s one database pool. Left unset, the pool keeps the size it had, the larger of 4 and the number of CPUs. GOPHENBERG_DATABASE_URL takes no pool_ setting, and the PostgreSQL address lists every form it may not hold. Run check with the new image before you update. It names the setting and the reason without connecting, and it now stops at every pool_ setting and names it. For example:

    gophenberg: GOPHENBERG_DATABASE_URL: dbkit: refused database address: a ? or # comes before an @ ahead of the first /, write ? as %3F, # as %23 and @ as %40

    These forms already stopped migrate and serve before this update, so no running site holds them: any pool_ setting, such as pool_max_conns, whatever its value, an @ inside the user name or the password, a space inside a value, a % that starts no % code, %00, and a pair after the ? with no = or with two.

    These forms worked before and now stop the server, so change them first. The likeliest come first:

    • A ?, a # or another sign in the password or the user name, such as ^ or ". Only an unaccented letter, a digit, a semicolon and the signs -._:~!$&'()*+,=% may stay as they are.
    • A key set twice, such as sslmode=disable twice. dbname and database count as one key.
    • A space at the start or end of a value, such as application_name= site.
    • A # or a control character, such as a tab, anywhere else.
    • A + or a semicolon after the ?.
    • ssl in place of sslmode.
    • A host list with an empty host, or with a port on some hosts only.
    • A database name that starts with /.
    • A backslash in a connection string written as key=value pairs.

    The PostgreSQL address says how to write each one, mostly as its % code, such as %23 for # and %3F for ?. The release before this one reads the changed address too, so change the address first and update after.

    The update keeps every table and row. The core migrations keep their record in the same goose_db_version table, so none of them runs a second time.

  • On PostgreSQL, account:records -json now gives each time in UTC, as the text output already does. When the PostgreSQL driver, pgx, cannot read the address in GOPHENBERG_DATABASE_URL, account:list and account:records now stop with this one line, which holds no part of the address and no longer repeats the driver’s own text:

    gophenberg: postgres: open the database: pgx cannot parse the address or one of its settings

    The other account commands check the address first and name the setting, as they did before.

    Errors from the command records now name their step after postgres:, such as postgres: check the records: when account:records or a -yes -as command cannot reach the database. A failed records step of migrate now reads migrate records: postgres: apply the records schema: followed by dbkit’s own text. Update any script or alert that matches the old wording.

  • On a SQLite file, every account command and every plugin command that names a capability now run as on PostgreSQL, and the accounts and their records are kept in the file. The release before this one stops each of them with the account commands: error. serve and seed -yes still stop, and their error no longer names accounts. A plugin can read account names on SQLite too, see reading account names.

  • On a SQLite file, two migrate runs started at the same moment on a new file no longer stop with the database is busy. Opening the file while another connection holds it locked now waits up to GOPHENBERG_SQLITE_BUSY_TIMEOUT, as a write already did, and tries the lock again every GOPHENBERG_SQLITE_BUSY_POLL, a new setting, 10ms unless set. Every other wait tries the lock again on SQLite’s own schedule, as before. A wait now ends as soon as its command stops, such as on Ctrl-C. The release before this one waited out the whole busy timeout. Two steps still run to the end, so they can wait up to the busy timeout after Ctrl-C: storing the record of a change an account command applied, and saving what update:check found.

  • A confirmation message now shows the whole name of an item, as WordPress does. GOPHENBERG_TOAST_NAME_LENGTH no longer does anything and can go from your settings, and /api/settings no longer serves toast_name_length. GOPHENBERG_TOAST_ACTION_DURATION, a new setting, 10s unless set, times a message with a button, which only a plugin raises today. See the admin lists.

  • The users API refuses an account write in WordPress’s two ways. A write on an account whose role carries a capability the reader’s role lacks answers user_not_editable. Giving a role the reader may not give, or enabling an account whose role nothing declares, answers role_not_grantable. The release before this one answered role_beyond_reach for both. Each account /api/users lists now carries editable, true when the reader may change it. A program that reads those codes needs updating.

  • GOPHENBERG_DEFAULT_ROLE, a new setting, member unless set, names the role the Add User screen starts on, as WordPress’s New User Default Role does. A role neither the core nor a plugin declares stops the server at start. Each account /api/users lists now carries avatar, the same picture the author column draws, and none while GOPHENBERG_AVATARS is off. See configuration.

  • The Users screen is now a list like the posts list. It searches, filters by role and status, sorts, pages and acts on several ticked accounts at once, and the address of the screen keeps all of it. Each row shows the account’s avatar and how many posts it wrote. A row you may not change shows no actions, and a refused change says why in a message at the bottom of the screen. Add User now starts on GOPHENBERG_DEFAULT_ROLE, so on member unless you set it, where it started on author. A member cannot enter the admin, so set it to author to keep the old start. See managing accounts.

  • A JPEG that arrives sideways is now kept as you sent it, with its orientation tag and the details the camera wrote into it, such as where the photo was taken, as WordPress keeps it. Its full size is an upright copy named with -rotated, or the -scaled copy when the photo is larger than 2560 pixels, and a post shows that copy. Pictures already in the library stay as they were.

  • GOPHENBERG_MEDIA_MAX_MEGAPIXELS, a new setting, 80 unless set, is the most pixels a picture or one frame of a GIF may hold, in millions. A site that leaves it unset refuses the same pictures as before. See configuration.

  • GOPHENBERG_MAX_PROCS and GOPHENBERG_MEMORY_LIMIT_MB, new settings and neither required, hand Go its processor and memory limits once .env has loaded. Each only ever lowers what Go holds, and a value out of range stops check and serve. See memory and processors on a small host.

  • GIF uploads now work. The release before this one refused them with image_unreadable.

  • The built-in site now answers each post, page and listing at one address. A trailing slash, repeated slashes, page 1, a page number with leading zeros and a post or page asked for with a page number, such as /hello-world/page/2, now get a 301 to the plain address, with the query kept. A theme answers these addresses itself. See what the binary serves where.

  • A new slug keeps its underscores, drops signs such as & and ° without a break and writes × as x, so Q&A gives qa and 2×4 gives 2x4. Spaces, dots and slashes become hyphens. Words in scripts such as Hindi, Tamil and Thai stay whole. An uploaded file name loses its accents, so Café Ærø.jpg is stored as cafe-aero.jpg. Saved slugs and stored files keep their names. A new or changed route word can no longer be page, since /page/2 is the second page of the front page.

  • The media library and the content types list are now WordPress lists, like the posts list. A media block’s Media Library button opens the Select Media dialog, which uploads too and keeps what you tick across pages. See media.

  • GET /api/content/counts is gone, since no screen reads it, so a script that called it needs updating.

  • On a site that builds its own plugins, the plugin ids about, update, server, plugin, theme, setup, build and health are now reserved, and a plugin’s admin screens move to newer packages. The Go SDK has not changed. Admin screens for plugins lists every step to move a plugin.

Updating from further back also runs the migrations of every release you skip, so read each of their notes. Coming from six releases back or older, write any @ inside the password in GOPHENBERG_DATABASE_URL as %40, or the server does not start. The %40 form works on those releases too, so change the address first and update after.

Coming from two releases back or older, the update also runs the two migrations the release before this one added. The first gives every content type a short description, and the one of Posts reads Manage the posts on this site. The second adds an empty table for the cron jobs. The admin then opens only for a role carrying access_admin, so run account:list first and give a role to each account that holds none, see upgrading a site. Some API routes answer capability_missing where those releases answered role_insufficient. A stop takes up to 25 seconds, so set stop_grace_period above that. The sweep of expired sessions is a cron job, so on a host that stops a quiet site, set GOPHENBERG_CRON_SECRET and a host cron, and update any alert that watched for reap expired sessions. The admin writes dates, times and numbers in the format of GOPHENBERG_FORMAT_LOCALE, es-ES unless set. On a site that builds its own plugins, a plugin requires the SDK module alone, and a plugin role meant for the admin needs access_admin.

Coming from three releases back or older, the update also runs the migration that two releases back added. It adds the gonsole schema, which keeps a record of each account change applied with -as, so the database account needs the right to create a schema. A run with no command lists the commands instead of serving, so a setup that passes the image its own arguments, or runs the binary itself, has to name serve first. createadmin is now account:create-admin, and grantrole is now account:grant-role. seed and the four account commands that change an account change nothing until you add -yes, and those four need -as. Every start deletes the files of an upload that a stop cut short, so run one Gophenberg per media folder. A still picture over the pixel limit is refused with image_pixel_budget_exceeded. A post in the trash is read only, and moving a post to the trash deletes the unsaved work parked on it, from every author. On a site that builds its own plugins, commands such as list and check register every plugin and stop it without starting it, so Register must open nothing, and Stop must work when Start never ran.

Coming from four releases back or older, a browser that saves anything from a page on another site is refused with request_cross_origin, so a plugin form has to sit on this site’s own pages. Behind a reverse proxy, set GOPHENBERG_PUBLIC_URL, or set GOPHENBERG_TRUSTED_PROXIES and let the proxy pass X-Forwarded-Proto. Without one of them, a browser too old to say where a request came from is refused on this site too. Move also deletes the values a field leaves on the content its new group does not reach, where those releases left them hidden.

If a type stopped nesting on an older release while its items still sat inside other items, this release refuses to save those items. Press Let items nest on that type. For a type a plugin declared, move those items to the top level instead.

Coming from five releases back or older, the update also runs the migration that four releases back added. On most sites it only adds a database index, a rule that stops one container from holding two fields of the same name, and changes no row. It never changes what your items, revisions and autosaves store. The migration runs as one step. If it fails, the server stops at start and the database stays as it was, so the older image starts again.

The migration does more on a site where one container held two fields of the same name. That can only happen where a release seven back or older moved a Section, a Repeater or a Flexible content field to another group without the fields inside it. The migration keeps one copy. It keeps the copy stored in the same group as the top-level field above it, or else the older one. The other copy is deleted with its label and settings. If both copies are the same kind, and two relations point at the same type, the fields inside the removed copy move into the copy that stays. Where that copy already holds a field of the same name, those two are settled by the same rule. Otherwise everything inside the removed copy is deleted too. Its values stay in your items, and the public API still serves them, even where they do not fit the field that stays. Saving such an item can be refused until that value is cleared. Last, every field inside a container moves into the group of the top-level field above it.

The server logs nothing about what the migration removes, and rolling back does not bring it back. On such a site, press Export definitions before you update to keep a record, and keep the backup until you have checked those containers. Do not delete one of the two copies by hand first, because on that release it clears the values both copies read.

Rolling back to the release before this one deletes nothing, and there is no migration to undo, since this release added none. Put the older image tag back on the gophenberg service and start it. Leave database-owner on this release, because an older one does not have that command. The site runs on this release’s database as it stands, as the role it logs in as now. Accounts keep signing in, and the database password needs no change. It turns away a theme built on kit 0.16.0 with kit_unsupported, and the site shows the built-in pages. If GOPHENBERG_THEME names that theme, the server does not start at all.

Only a Docker site can roll back this way. The release before this one published its image but no archives, so a server install has no build of it to go back to.

While you run it:

  • It never checks for updates and has no Updates screen. What this release stored about updates stays in the database, unused.
  • It ignores the settings this release added. It stops at once when the database is not up yet, never checks the role it logs in as, and listens on GOPHENBERG_ADDR or localhost:8081, whatever PORT says. Its PostgreSQL pool holds the larger of 4 and the number of CPUs.
  • Add User starts on author again, and the Users screen goes back to its older form. The users API answers role_beyond_reach again where this release answers user_not_editable or role_not_grantable.
  • A confirmation message cuts a long name short again, at 45 characters unless GOPHENBERG_TOAST_NAME_LENGTH says otherwise.
  • It refuses every GIF upload with image_unreadable. It turns a sideways JPEG upright in place of the file you sent, without the details the camera wrote into it.
  • New slugs and uploaded file names follow its older rules, while the ones saved on this release keep their names. The built-in site answers a post, page or listing at more than one address again.
  • Its older media library, content types list and media picker come back.
  • On a SQLite file it stops every account command, and every plugin command that names a capability, with the account commands: error. The accounts and their records stay in the file, and the commands reach them again once you update.
  • A plugin screen written for this release, such as one that takes MenuItem or ConfirmDialog from the frontend SDK, does not build against it.

Updating again runs no migration, and what you changed while rolled back stays as it is.

Going back more than one release is not supported. To run an older release, restore the backup you took just before you first updated past it, with the media volume from the same day. Everything written since that backup is lost.

You can instead start an older image on this release’s database. Before you do, write every sign in the database password that is not a letter from a to z or a digit as its % code, such as %23 for # and %3F for ?. The older image then starts, and starting deletes nothing. Each older release also has the problems of every newer one, the release before this one included, unless its own line says otherwise:

  • Two releases back keeps the description of every type, but neither shows nor exports them. Its import refuses a definitions file a newer release exported, with a message naming description, so take every description out of the file first. Every account that signs in enters the admin again, members and accounts holding no role or a plugin’s role included, and can write and upload like an author, so disable the member accounts first if that matters. A plugin role carrying manage_users loses it, and -role member is refused. It has no cron address, so pause the host’s cron, which gets 404, and it sweeps sessions on its own hourly timer. An admin list shows 20 items a page, dates and numbers follow each reader’s language, and a stop takes up to 23 seconds. A plugin that uses deps.DB, deps.Accounts, Needs or RoleProvider, or requires the SDK module, does not build against it. It does not open a SQLite file. Its screens come back with the home screen, the counts on the status tabs and the Undo after a trash, and new slugs keep their accents. Take its newest patch. On its first patch, Empty Trash on any list but Posts deletes the trashed posts for good. Its first two patches run only themes built on theme kit 0.15.0 or older.
  • Three releases back knows three commands, createadmin, grantrole and seed. Any other word, serve, check, migrate and every account: command included, starts the full server and runs its migrations. Under docker compose run, that server keeps running until you stop it. Its seed stores the demo data at once, with no dry run, and its grantrole refuses -as and -yes. It keeps no record of the account changes it makes, and the records kept before stay. It reads every setting as it is written, spaces included, so take those spaces out first. It ignores GOPHENBERG_PUBLIC_URL, so another domain pointed at your server can again make a visitor’s browser post to the site. A stop gives the requests and the plugins one window of 10 seconds. A stop in the middle of an upload leaves its files in the media folder. A post in the trash takes edits again, and two changes made at the same moment can slip past the checks on a page’s place or a field’s depth. Leaving the editor loses the unsaved words, and going Back to a post can show another post’s content. Moving a group with a Linked from field needs that field deleted and declared again. It runs only themes built on theme kit 0.15.0 or older. A newer theme does not load, and the site shows the built-in pages instead. If GOPHENBERG_THEME names that theme, the server does not start.
  • Four releases back accepts what a browser saves from a page on another site. Its Move leaves a field’s values hidden on the content the new group does not reach, and updating again does not clean them up. Its imports delete the values of a field they move to another group, and some imports write part of the file before they refuse the rest. It lets you delete a relation inside a Section that a Linked from field reads, which leaves that field reading nothing. It refuses to delete a group holding both a relation and the Linked from field reading it. A site whose Linked from field reads a relation inside a Section cannot import its own export. It also lets a block delimiter inside an allowed attribute hide an event handler from the content sanitizer, which the newest patch of three releases back fixed.
  • Five releases back cannot move a field into or out of a container, and fields a newer release moved stay where they are. It has no buttons to let a type nest or stop nesting, and it lets the API or an import turn nesting off while items still sit inside other items. After you update again, those items cannot be saved until you press Let items nest. A type a plugin declared, which newer releases keep nesting, turns flat when it starts and stays flat after you update again, so move its nested items to the top level. Deleting a field from a group that is turned off or Shadowed clears the values another active group serves at the same place.
  • Six releases back ignores GOPHENBERG_FIELD_DEPTH and holds the limit at 32. It refuses a new field more than 32 deep, and any import file that holds one.
  • Seven releases back moves a Section, a Repeater or a Flexible content field to another group without the fields inside it. After such a move, adding a field to that container under the name of a field left behind fails with an internal error. Deleting the old group fails the same way. It also lets a shared cache keep a failed content API answer, and does not mark answers to a signed in account as private.
  • Eight releases back does not know a relation inside a container. Its editor refuses to save a change to a container holding one, and a change sent through the API that leaves the relation out deletes its value. It keeps what an item points at in a separate list, while newer releases read the item itself, so a relation you change there is lost when you update again.
  • Nine releases back does not know the newer field kinds. It shows their values but refuses a change to one. It runs only themes built on theme kit 0.12.0 or older. A newer theme does not load, and the site shows the built-in pages instead. If GOPHENBERG_THEME names that theme, the server does not start.
  • Ten releases back knows only the six original kinds and does not know containers at all. It cannot create a field group. Deleting a field there also deletes every field of that name inside the group’s containers, and deleting a group also deletes its fields that stand inside other groups’ containers. It runs only themes built on theme kit 0.9.0.

Running the migrations backwards by hand, as ten releases back would need, deletes definitions, and that is a one way trip. It deletes every field whose kind is not one of the six, every field standing inside another field, every field’s settings, and the record of which plugin declared what. It leaves every Gallery as a single Media field holding a list of files it cannot read. The values stay in the database, but an item holding a value for a deleted field cannot be saved, not even with a new title, until a field of that name exists again. The definitions do not come back if you migrate forward again, and neither do the copies the container migration removed.

This release serves themes built on @gophenberg/astro 0.16.0, and the older kits it still answers. Ask a site which ones through the handshake, and rebuild your theme against one of them before updating. Theme compatibility explains how long a built theme keeps working.

Twice a day, on the next visit or when the host’s cron calls the cron address, a site asks https://updates.gophenberg.org for three files, each with its signature:

  • The key list, the list of the Gophenberg keys, which the two root keys built into the binary sign.
  • The timestamp file, which the timestamp key signs every day.
  • The index of the stable channel, the versions on offer, which a release key signs.

It checks every signature, refuses a file that expired or that is older than the last one it took, and keeps what it found for the admin. A check installs nothing. On a server install, update:apply installs the update when you run it, or an administrator starts it from the admin, see updating a server install. Everywhere else, such as in the Docker image, you update by hand as updating shows.

A check sends nothing about the site but the request itself, with Gophenberg/ and its version as its User-Agent. The site’s address never leaves it.

Run gophenberg update:check to check now. A site with no internet access sets GOPHENBERG_UPDATE_CHECKS to false, which stops the checks it makes on its own.

An old index is how an attacker could hide a security fix from your site. If they keep serving last month’s index, honestly signed, the site never hears of the fix. A signature cannot catch that. Only a date can.

So a key that signs nothing else, the timestamp key, signs a short timestamp file every day. The file names the newest key list and the newest index of each channel by their serial numbers. It expires 7 days after it was signed. While it has not expired, it is fresh.

A site takes the key list and the index only when the timestamp file is fresh and neither file is older than the one it names. A newer file passes, so a new release reaches your site at once, before the next timestamp file names it. A site refuses a timestamp file that is missing, that expired, that another key signed, or that names no index of the site’s channel. A site never takes an index or an archive the timestamp key signed.

The index keeps its own expiry as well, 90 days after it was signed. A fresh timestamp file never carries an index past that date.

These dates work only when the site’s clock is right to within a few days. A clock more than about 6 days fast refuses every timestamp file. When a check refuses a file that expired, the error names the expiry and the time the site’s clock reads, so you can spot a wrong clock. Most hosts keep the clock right with NTP.

To try a release before it reaches every site, point GOPHENBERG_UPDATE_URL at your own copy of the update site, and list the root keys that sign its key list in GOPHENBERG_TRUSTED_KEYS. See configuration.

Your copy needs what the official site holds. Its key list must name a timestamp key beside the release key, a different key for each. It must also serve a fresh timestamp file at v1/timestamp.json, signed by that timestamp key. Make it with releasetool timestamp, the release tool in the Gophenberg source, and make a new one before the last one expires. The official update site makes a new one every day, and each lasts 7 days. Once the last one expires, every site that follows your copy refuses its checks.

A server install runs the gophenberg binary itself, with no container around it. It keeps each build of Gophenberg in its own folder, all under one folder called the install root, and GOPHENBERG_INSTALL_ROOT names that folder, such as /opt/gophenberg. With it set, gophenberg update:apply updates the site from the command line, an administrator can start the same update from the admin, and the first start of the new build checks itself and goes back on its own when it fails.

Three kinds of install keep the manual steps:

  • The Docker image, and any install where GOPHENBERG_INSTALL_ROOT is empty. Update it as updating shows. update:apply and the admin refuse with GOPHENBERG_INSTALL_ROOT is empty and name the version to update to.
  • A binary you built yourself, which about calls a custom build. An official archive would replace it without the plugins you built into it, so update:apply and the admin refuse and ask you to rebuild it on the new version.
  • A site on SQLite, since only a PostgreSQL site serves for now.

Say the server runs Gophenberg 1.4.0 and has just updated to 1.4.1. The install root then holds:

/opt/gophenberg/
versions/1.4.0/gophenberg one folder for each build
versions/1.4.1/gophenberg
current -> versions/1.4.1 the build that runs
previous -> versions/1.4.0 the build to go back to
downloads/ the archive while it downloads
backups/1.4.0-20261020T120000Z.dump the database just before the update
state/update.json how far the last update got, the refused versions and the last failure

current and previous are links. Your service always starts /opt/gophenberg/current/gophenberg serve. Pointing a link at another build is one rename, so a sudden stop leaves the old link or the new one, never half of each. The user Gophenberg runs as needs read and write access to the whole install root. Leave state/update.json to Gophenberg, since the next start reads it.

Install on a Linux server sets up the install root for you. To set one up by hand, unpack the archive of the release you run into its own folder and point current at it, after you check the download:

Terminal window
mkdir -p /opt/gophenberg/versions/0.20.1
tar -xzf gophenberg_0.20.1_linux_amd64.tar.gz -C /opt/gophenberg/versions/0.20.1
ln -s versions/0.20.1 /opt/gophenberg/current

Then set GOPHENBERG_INSTALL_ROOT=/opt/gophenberg beside your other settings.

Set GOPHENBERG_DATA_DIR when something other than an update may rebuild the install root, such as a redeploy on a small hosting plan. It names a folder outside the install root, as an absolute path, and backups/ and state/ move there under the same names. The builds, the links and downloads/ stay in the install root:

/srv/gophenberg-data/
backups/1.4.0-20261020T120000Z.dump
state/update.json
data/media/

serve and update:apply make the folder when it is not there, with the mode 0700, since a backup holds every account, and they leave one that is there as it stands. An update asks for the same free disk on the data folder as on the install root.

The folder must stand outside the install root, so a site with one inside it stops at its start. Setting it on a site that already updated leaves the old backups/ and state/ behind, so move them into the new folder first.

Install on a Linux server sets up a service that may write only under the install root, so leave GOPHENBERG_DATA_DIR unset there.

On a server that install.sh set up, run update:apply through the gophenberg command while the site keeps serving:

Terminal window
sudo gophenberg update:apply

On an install root you set up by hand, run the binary current names from the install root, as the user Gophenberg runs as, since a command reads the .env of the folder it runs in:

Terminal window
cd /opt/gophenberg && ./current/gophenberg update:apply

It takes the newest version the update site offers this site, or the one you name in -to. It fetches and checks the signed key list and index again, then works in these steps, writing each one to state/update.json before it starts it:

  1. Plan. It checks everything it can before it changes anything: the build stamp, the archive for this platform, the PostgreSQL version, the active theme, write access to the install root, pg_dump, and free disk for GOPHENBERG_UPDATE_DOWNLOAD_CAP_MB, the backup and GOPHENBERG_UPDATE_DISK_MARGIN_MB. When it refuses, it says what to do.
  2. Download. It downloads the archive into downloads/, follows only HTTPS redirects, stops past GOPHENBERG_UPDATE_DOWNLOAD_CAP_MB or GOPHENBERG_UPDATE_DOWNLOAD_TIMEOUT, then checks the archive against the checksum in the release record and the signature of a release key from the key list.
  3. Stage. It unpacks the archive into versions/<version>/, refusing any file outside that folder, and runs the new binary’s about -json to check its version and that it is an official build.
  4. Backup. It backs up the database with pg_dump into backups/, in the custom format, the password passed in PGPASSWORD and never on the command line. It keeps GOPHENBERG_UPDATE_BACKUPS_KEEP backups: always the one it just took and the one the last update names in state/update.json, then the newest others. With a setting of 1 it can keep those two. -skip-backup skips this step, except for a release that raised the minimum version.
  5. Switch. It points previous at the build that runs and current at the new one.

It then asks for a restart and exits with code 75:

gophenberg: restart Gophenberg to start 1.4.1

The server still runs the old build until it restarts. On a server that install.sh set up, the gophenberg command restarts it for you. Otherwise restart it yourself, such as with systemctl restart gophenberg. When a step fails, update:apply deletes what it wrote, leaves current as it was and exits with code 1, so nothing changed for the site. It writes which update failed, when, at which step and why into state/update.json, and update:status shows that failure until the next update starts. A second update:apply while one runs stops with another update runs.

An administrator can start the same update from the Updates screen of the admin. Before it answers, the server runs every check of the plan. When one refuses, the admin shows the reason update:apply gives, and nothing changes. Otherwise the server runs the download, the stage, the backup and the switch on its own, so closing the page does not stop the update. An update started from the admin always takes the backup. One update runs at a time, so a second start, from the admin or from update:apply, stops with another update runs.

Once it switched builds, the server stops as it does on SIGTERM. It takes no new request and gives the requests still running GOPHENBERG_SHUTDOWN_GRACE to finish, see stopping the server. Then it exits with code 75, the code update:apply asks for a restart with, and logs:

gophenberg: restart Gophenberg to start 1.4.1

So an install root needs a service manager that starts Gophenberg again when it exits. A server that install.sh set up has one, see the site’s unit. A systemd unit of your own needs that unit’s Restart, OnFailure and exit code 75 and 76 lines, and the rollback unit beside it. The next start runs the new build, and the boot guard checks it as it does after update:apply. Without a service manager, the site stays down after the switch until you start it again.

When a step fails, the server deletes what it wrote, leaves current as it was and keeps serving the build that runs. It writes which update failed, when, at which step and why into state/update.json, and the admin and update:status show that failure. When the new build fails its start check, it goes back on its own, as a version that fails its check shows, and the admin can try that version again once you have fixed what failed.

Updates is the last item of the admin menu. It shows to every role carrying update_core, which admin carries. While a newer version waits, a small number sits beside Updates, and a line above every other admin screen names the version and links to the screen. After an update fails before it switches builds, a line says the update to that version failed to complete and links to the screen to try again. When the failed version is the one on offer, only that line shows.

From top to bottom, the screen shows:

  • The version that runs, under the title.
  • When the site last checked for a new version, and when the next check runs. Check again checks now. A second check within GOPHENBERG_UPDATES_SCREEN_CHECK_AGE, one minute unless set, is refused, and the screen asks you to try again later. When GOPHENBERG_UPDATE_CHECKS is false, the screen says the site does not check on its own.
  • That the site receives no automatic updates. Nothing installs until you press the button.
  • The version on offer and a link to its release notes, or that the site runs the latest version. Before the first good check it says neither, as it cannot know yet. There is no button to install the same version again, since the server refuses a version that is not newer than the one that runs.
  • How many database backups the install root keeps, and when the newest was taken.

Update to version asks before it starts, and says what happens if the new version fails. Once you confirm, the warning to back up and the sentence above the button go away, and the screen shows each step on its own line, the one under way marked: the download, the unpacking, the check of the unpacked files, the database backup, the restart and the check of the new version. It asks the server where the update stands every GOPHENBERG_UPDATES_SCREEN_PROGRESS_INTERVAL, 2 seconds unless set. While the server restarts it cannot answer, so the screen keeps asking for up to GOPHENBERG_UPDATES_SCREEN_RESTART_WAIT, 5 minutes unless set. Opening the screen while an update runs shows its steps and its ending too.

The update ends in one of five ways:

  • Gophenberg updated successfully. The open tab still runs the old admin, so press Reload the admin.
  • The update to 1.4.1 failed. The message adds that Gophenberg went back to 1.4.0 and is running normally, since the new version failed its start check. It stays until you dismiss it. The version stays on offer, and under the line saying it failed its start check, the button now reads Re-install version 1.4.1. It tries that version again, as -retry does, so fix what failed first.
  • The update to 1.4.1 failed its start check, and Gophenberg cannot go back to 1.4.0 on its own. An update that raised the minimum version failed its start check after it reached the database, and the screen says so once the service manager starts the new version again. Run update:status to see the backup taken before the update, then restore it or fix what failed, see an update that raised the minimum version.
  • The update failed before anything changed. A step before the switch failed, and the reason follows. The site keeps running the version it ran, and Update to version tries again.
  • Gophenberg has not come back yet. The wait passed with no answer from the new version. Check that your service manager starts Gophenberg again after exit code 75, and run update:status on the server to see where the update stands. The screen keeps asking, and shows how the update ended once Gophenberg answers again.

Two offers show no button. An update that needs a newer PostgreSQL names the version it needs and the version your server runs. The screen reads your server each time it loads, so the button comes back as soon as you upgrade PostgreSQL. An install that updates by hand, such as the Docker image or a binary you built yourself, says why and links to this page. An update that raised the minimum version keeps its button, and says the backup is required and that the site stays down if the new version fails after it reaches the database, see an update that raised the minimum version.

At every start, before it opens the database, Gophenberg reads state/update.json. When the last update switched to this build and the build has not passed its check yet, the start checks it:

  1. It counts the attempt. A build that already tried to start GOPHENBERG_UPDATE_ATTEMPTS times, 3 unless set, fails at once.
  2. It waits for a database that is not up yet, see a database that starts late after an update. Once the database answers, it writes database_reached into state/update.json, then migrates the database, as every start does.
  3. Within GOPHENBERG_UPDATE_VERIFY_TIMEOUT, one minute unless set, it checks that the public site serves through the theme the site chose. Then it asks itself over loopback for /admin/ and /api/locale, which must answer 200, and for /, which must answer below 500.

When every check passes, it keeps the update, logs kept the update after its start check, and deletes the oldest builds past GOPHENBERG_UPDATE_VERSIONS_KEEP, 2 unless set. It never deletes the builds current and previous name. Then it keeps serving. update:status says kept from then on.

When a check fails, the new build goes back on its own. It adds its version to the refused versions, points current at the build before it and exits with code 76, so the next start runs the older build. The older build runs on the database as it stands, since the new one kept the minimum version, see going back to an older version.

update:apply never takes a refused version again on its own. It takes a newer version when the update site offers one, and otherwise stops and names the command that tries the refused one again. Once you have fixed what failed, run:

Terminal window
sudo gophenberg update:apply -to 1.4.1 -retry

On an install root you set up by hand, run it from the install root:

Terminal window
cd /opt/gophenberg && ./current/gophenberg update:apply -to 1.4.1 -retry

Once systemd gave up restarting the site, the rollback unit runs update:rollback -after-failure and then starts the site again. Any result but success counts, such as a start that failed its check with exit code 76 or a build that keeps crashing, see update:rollback. To take back an update that passed its check, run sudo gophenberg update:rollback, which also restarts the site. On an install root you set up by hand, run ./current/gophenberg update:rollback from the install root and restart Gophenberg yourself. That version is refused from then on too.

A release that added a migration raises the minimum version past the build before it, which then refuses the database the new build migrated. update:check says going back to this version after it needs the backup for such a release. For it, update:apply always takes the backup, even with -skip-backup.

If such a build reached the database and then fails its check, it does not go back on its own. The site stays down, and nothing restores the backup on its own, since everything written after the backup would be lost. The error, the log and update:status name the backup and the steps:

gophenberg: updater: restore the backup taken before the update, /opt/gophenberg/backups/1.4.0-20261020T120000Z.dump, into an empty database, point current at versions/1.4.0 and start Gophenberg again, as https://docs.gophenberg.org/self-hosting/updates-and-backups/#restoring-on-a-server-install shows, or fix what failed and start Gophenberg 1.4.1 again

A build that stops before its check, such as on a migration that fails, ends the same way. Once systemd gave up restarting it, the rollback unit writes that the update failed instead of going back, so update:status shows the same steps.

A build that never reached the database cannot have migrated it, so it goes back like any other update, see a version that fails its check. That happens when every start stopped before the database answered, such as while PostgreSQL was still down. update:status -json then shows database_reached as false.

A start is not the only way the new build reaches the database. Every command of the new build that migrates, such as migrate, seed -yes, account:create-admin and account:grant-role -yes, sets database_reached too, once the database lets that build on and before the first schema step changes anything. So once you run the new build’s migrate by hand, the update counts as one that may have migrated, and update:rollback prints the restore steps instead of going back. The command marks the update only when it runs with the settings of the service, GOPHENBERG_INSTALL_ROOT among them.

Restoring on a server install shows each step. Or fix what failed, such as a setting or a full disk, and start Gophenberg again. Either way, the build that starts runs the start check once more, but it never goes back or stops on its own. When the check passes, update:status says the update was kept, or taken back after a restore. When it fails, the site keeps serving and the log says the update stays failed with the reason.

A database that starts late after an update

Section titled “A database that starts late after an update”

A server may start Gophenberg before PostgreSQL answers, such as when both start at boot. serve then waits up to GOPHENBERG_DATABASE_WAIT, 60 seconds unless set, and stops with code 1 when the database still does not answer, so the service manager starts it again, see a database that starts late. With no update waiting for its check, the boot guard counts nothing, so a late database never takes anything back.

Right after an update, the boot guard counts each start of the new build before it waits, so one late start costs one attempt. With the defaults, 3 attempts of up to 60 seconds each, the database can stay down for about three minutes after the first start, plus the time the service manager waits between two starts. When it answers within that time, the start goes on, migrates and runs its check as usual. The bound is about GOPHENBERG_UPDATE_ATTEMPTS times GOPHENBERG_DATABASE_WAIT, so raising either one gives the database longer.

A database down for longer than that takes a good update back. The start after the last attempt, the fourth with the defaults, fails its check at once, the new build goes back as a version that fails its check shows, and its version joins the refused versions. Once the database answers again, take the update again:

Terminal window
sudo gophenberg update:apply -to 1.4.1 -retry

On an install root you set up by hand, run it from the install root:

Terminal window
cd /opt/gophenberg && ./current/gophenberg update:apply -to 1.4.1 -retry

This holds for an update that raised the minimum version too. Its starts never reached the database, so database_reached stays false and the update goes back instead of staying down.

update:rollback takes such an update back too while its new build still waits, since that build has not reached the database yet. The waiting start then stops before it migrates, and the next start runs the build before the update.

Every release carries a minimum version, the oldest version allowed to run on the database it leaves. A release that adds a migration sets the minimum version to itself. A patch that adds none keeps the minimum version of the release before it. gophenberg about -json shows the minimum version of the binary you hold, under minimum_version.

After it migrates, Gophenberg stores its minimum version in the database, and it never lowers one stored there. Before it migrates, it compares the stored minimum version with its own version. When the stored one is newer, serve, migrate and every command that migrates stop before they change anything. The message names the version the database needs and the version you started, and tells you to restore the backup taken before the update.

So you can set a patch back to the patch before it whenever neither added a migration. To go back past a release that added one, restore the backup you took before you updated past it, with the media volume from the same day, see restoring. Everything written since that backup is lost.

An image whose about -json shows no minimum_version comes from a release older than the minimum version itself. It never reads the stored one, so nothing stops it on a database a newer release migrated. Restore the backup before you start such an image.

The database, which holds everything you wrote, and the record of each account change applied with -as:

Terminal window
docker compose exec -T db pg_dump -U postgres -Fc gophenberg > gophenberg.dump

The -T is required: without it Docker attaches a terminal that corrupts the binary dump, and you find out when the restore fails.

Your compose file and any .env beside it, the only place your configuration and passwords exist.

The media volume, which holds every file you uploaded. The database records what each file is called and where it lives, but never the file itself, so a lost volume leaves a library of broken pictures no dump can repair:

Terminal window
docker compose cp gophenberg:/media ./media-backup

Back it up whenever you back up the database. The two have to come back together, or the library and the files disagree.

The themes volume, if you upload themes in the admin. An uploaded theme exists only there, so a lost volume means re-uploading every theme:

Terminal window
docker compose cp gophenberg:/themes ./themes-backup

Which theme is active is stored in the database, not in the volume, so both have to come back for the site to look the same. Themes you install by hand need no backup, they are rebuilt from their source projects.

Restore into a database Gophenberg has never touched, because the tables it creates make the restore fail. Starting the server creates them, and so do migrate, seed -yes and account:create-admin, so run none of them before the restore:

Terminal window
docker compose run --rm database-owner
docker compose exec -T db pg_restore -U postgres -d gophenberg < gophenberg.dump
docker compose up -d

Running only database-owner first starts the database and makes the role the restored tables belong to, and it keeps Gophenberg out of the way until the restore is done. A backup from before you moved off postgres restores too, and the last line moves it to the role.

After an update that raised the minimum version failed its check, the backup update:apply took sits in the backups folder of the install root, and the error and update:status name it. Say the site went from 1.4.0 to 1.4.1. On a server that install.sh set up, stop the site and put the backup in place of the database the new build migrated:

Terminal window
sudo systemctl stop gophenberg
sudo -u postgres dropdb gophenberg
sudo -u postgres createdb --owner=gophenberg --encoding=UTF8 --template=template0 --locale-provider=icu --icu-locale=und gophenberg
sudo -u gophenberg pg_restore -d gophenberg /opt/gophenberg/backups/1.4.0-20261020T120000Z.dump
  • dropdb deletes the database the new build migrated, for good.
  • The database keeps its name, gophenberg, since every sudo gophenberg server:install writes GOPHENBERG_DATABASE_URL back to it.
  • createdb makes it as the install did. The owner matters. On PostgreSQL 15 and newer, only the owner of a database may create tables in it, and the next release that adds a migration has to.
  • pg_restore runs as gophenberg, which owns the database and can read the backup.

Then point current back at the build before the update, and start the site:

Terminal window
sudo -u gophenberg ln -sfn versions/1.4.0 /opt/gophenberg/current
sudo systemctl reset-failed gophenberg
sudo systemctl start gophenberg

On an install root you set up by hand, restore into a new empty database the site’s role owns instead, such as with createdb -O gophenberg gophenberg_restored as the PostgreSQL superuser and then pg_restore -d gophenberg_restored with the backup. Point GOPHENBERG_DATABASE_URL at it, point current back, and start Gophenberg.

Once 1.4.0 passes its start check, update:status says the update was taken back. Everything written between the backup and the failed start is lost. Version 1.4.1 stays refused, so update:apply takes it again only with -to 1.4.1 -retry. Restore the media folder from the same day too, if you back it up apart, see what to back up.