Updates and backups
Two operational jobs: keeping Gophenberg current, and being able to put it back after something goes wrong.
Updating
Section titled “Updating”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:
# 1. edit compose.yaml: change both image tags to the new versiondocker compose pulldocker compose run --rm -T gophenberg checkdocker compose up -dcheck 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 thedatabase-ownerservice from Install, makegophenbergdepend on it as that file does, and pointGOPHENBERG_DATABASE_URLat the new role, see moving a site offpostgres. To update first and move later, setGOPHENBERG_SUPERUSER_POLICY=warn, which logs a warning and serves.checkcannot 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.envthat setsGOPHENBERG_WEB_DIR=/web, as the image of the release before this one did, now stops the server, so delete that line.checknames it.PORT. A site that sets neitherGOPHENBERG_ADDRnorGOPHENBERG_SOCKETnow listens on every interface atPORTwhen its environment exports one. The release before this one ignoredPORTand kept tolocalhost:8081. APORTthat is not a whole number from 1 to 65535 stops the server. SetGOPHENBERG_ADDRto keep the old address. The image setsGOPHENBERG_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,migrateand 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. -
servenow 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.orgfor a newer Gophenberg twice a day, as the cron jobcore/update-check. It sends nothing about the site but its version, and installs nothing. A site with no internet access logscron job failedat Warn withjob=core/update-checkat every check, so setGOPHENBERG_UPDATE_CHECKS=falsethere. Theadminrole 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/distand build with-tags embedweb, asmake build-releaseand the Dockerfile do. A plaingo buildserves a placeholder page in its place, unlessGOPHENBERG_WEB_DIRnames an admin build. AGOPHENBERG_WEB_DIRthat 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 runcheckwith your settings first. See configuration. -
On PostgreSQL,
GOPHENBERG_DATABASE_MAX_CONNSnow 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_URLtakes nopool_setting, and the PostgreSQL address lists every form it may not hold. Runcheckwith the new image before you update. It names the setting and the reason without connecting, and it now stops at everypool_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 %40These forms already stopped
migrateandservebefore this update, so no running site holds them: anypool_setting, such aspool_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=disabletwice.dbnameanddatabasecount 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?. sslin place ofsslmode.- 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=valuepairs.
The PostgreSQL address says how to write each one, mostly as its
%code, such as%23for#and%3Ffor?. 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_versiontable, so none of them runs a second time. - A
-
On PostgreSQL,
account:records -jsonnow gives each time in UTC, as the text output already does. When the PostgreSQL driver, pgx, cannot read the address inGOPHENBERG_DATABASE_URL,account:listandaccount:recordsnow 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 settingsThe 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 aspostgres: check the records:whenaccount:recordsor a-yes -ascommand cannot reach the database. A failed records step ofmigratenow readsmigrate 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.serveandseed -yesstill 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
migrateruns started at the same moment on a new file no longer stop withthe database is busy. Opening the file while another connection holds it locked now waits up toGOPHENBERG_SQLITE_BUSY_TIMEOUT, as a write already did, and tries the lock again everyGOPHENBERG_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 whatupdate:checkfound. -
A confirmation message now shows the whole name of an item, as WordPress does.
GOPHENBERG_TOAST_NAME_LENGTHno longer does anything and can go from your settings, and/api/settingsno longer servestoast_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, answersrole_not_grantable. The release before this one answeredrole_beyond_reachfor both. Each account/api/userslists now carrieseditable, true when the reader may change it. A program that reads those codes needs updating. -
GOPHENBERG_DEFAULT_ROLE, a new setting,memberunless 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/userslists now carriesavatar, the same picture the author column draws, and none whileGOPHENBERG_AVATARSisoff. 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 onmemberunless you set it, where it started onauthor. A member cannot enter the admin, so set it toauthorto 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-scaledcopy 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,80unless 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_PROCSandGOPHENBERG_MEMORY_LIMIT_MB, new settings and neither required, hand Go its processor and memory limits once.envhas loaded. Each only ever lowers what Go holds, and a value out of range stopscheckandserve. 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 a301to 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×asx, so Q&A givesqaand 2×4 gives2x4. 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 ascafe-aero.jpg. Saved slugs and stored files keep their names. A new or changed route word can no longer bepage, since/page/2is 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/countsis 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,buildandhealthare 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_ADDRorlocalhost:8081, whateverPORTsays. Its PostgreSQL pool holds the larger of 4 and the number of CPUs. - Add User starts on
authoragain, and the Users screen goes back to its older form. The users API answersrole_beyond_reachagain where this release answersuser_not_editableorrole_not_grantable. - A confirmation message cuts a long name short again, at 45
characters unless
GOPHENBERG_TOAST_NAME_LENGTHsays 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
MenuItemorConfirmDialogfrom 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 everydescriptionout 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 carryingmanage_usersloses it, and-role memberis 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 usesdeps.DB,deps.Accounts,NeedsorRoleProvider, 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,grantroleandseed. Any other word,serve,check,migrateand everyaccount:command included, starts the full server and runs its migrations. Underdocker compose run, that server keeps running until you stop it. Itsseedstores the demo data at once, with no dry run, and itsgrantrolerefuses-asand-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 ignoresGOPHENBERG_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. IfGOPHENBERG_THEMEnames 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_DEPTHand 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_THEMEnames 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.
How a site hears of a new version
Section titled “How a site hears of a new version”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.
Why a check fetches a timestamp file
Section titled “Why a check fetches a timestamp file”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.
Keep the site’s clock right
Section titled “Keep the site’s clock right”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.
Your own copy of the update site
Section titled “Your own copy of the update site”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.
Updating a server install
Section titled “Updating a server install”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_ROOTis empty. Update it as updating shows.update:applyand the admin refuse withGOPHENBERG_INSTALL_ROOT is emptyand name the version to update to. - A binary you built yourself, which
aboutcalls acustom build. An official archive would replace it without the plugins you built into it, soupdate:applyand 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.
The install root
Section titled “The install root”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 failurecurrent 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:
mkdir -p /opt/gophenberg/versions/0.20.1tar -xzf gophenberg_0.20.1_linux_amd64.tar.gz -C /opt/gophenberg/versions/0.20.1ln -s versions/0.20.1 /opt/gophenberg/currentThen set GOPHENBERG_INSTALL_ROOT=/opt/gophenberg beside your other
settings.
A data folder outside the install root
Section titled “A data folder outside the install root”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.
Running an update
Section titled “Running an update”On a server that install.sh set up, run update:apply through the
gophenberg command while the site keeps serving:
sudo gophenberg update:applyOn 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:
cd /opt/gophenberg && ./current/gophenberg update:applyIt 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:
- 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 forGOPHENBERG_UPDATE_DOWNLOAD_CAP_MB, the backup andGOPHENBERG_UPDATE_DISK_MARGIN_MB. When it refuses, it says what to do. - Download. It downloads the archive into
downloads/, follows only HTTPS redirects, stops pastGOPHENBERG_UPDATE_DOWNLOAD_CAP_MBorGOPHENBERG_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. - Stage. It unpacks the archive into
versions/<version>/, refusing any file outside that folder, and runs the new binary’sabout -jsonto check its version and that it is an official build. - Backup. It backs up the database with
pg_dumpintobackups/, in the custom format, the password passed inPGPASSWORDand never on the command line. It keepsGOPHENBERG_UPDATE_BACKUPS_KEEPbackups: always the one it just took and the one the last update names instate/update.json, then the newest others. With a setting of 1 it can keep those two.-skip-backupskips this step, except for a release that raised the minimum version. - Switch. It points
previousat the build that runs andcurrentat the new one.
It then asks for a restart and exits with code 75:
gophenberg: restart Gophenberg to start 1.4.1The 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.
Updating from the admin
Section titled “Updating from the admin”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.1So 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.
The Updates screen
Section titled “The Updates screen”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. WhenGOPHENBERG_UPDATE_CHECKSisfalse, 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
-retrydoes, 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:statusto 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:statuson 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.
The boot guard
Section titled “The boot guard”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:
- It counts the attempt. A build that already tried to start
GOPHENBERG_UPDATE_ATTEMPTStimes, 3 unless set, fails at once. - 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_reachedintostate/update.json, then migrates the database, as every start does. - 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.
A version that fails its check
Section titled “A version that fails its check”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:
sudo gophenberg update:apply -to 1.4.1 -retryOn an install root you set up by hand, run it from the install root:
cd /opt/gophenberg && ./current/gophenberg update:apply -to 1.4.1 -retryOnce 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.
An update that raised the minimum version
Section titled “An update that raised the minimum version”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 againA 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:
sudo gophenberg update:apply -to 1.4.1 -retryOn an install root you set up by hand, run it from the install root:
cd /opt/gophenberg && ./current/gophenberg update:apply -to 1.4.1 -retryThis 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.
Going back to an older version
Section titled “Going back to an older version”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.
What to back up
Section titled “What to back up”The database, which holds everything you wrote, and the record of
each account change applied with -as:
docker compose exec -T db pg_dump -U postgres -Fc gophenberg > gophenberg.dumpThe -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:
docker compose cp gophenberg:/media ./media-backupBack 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:
docker compose cp gophenberg:/themes ./themes-backupWhich 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.
Restoring
Section titled “Restoring”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:
docker compose run --rm database-ownerdocker compose exec -T db pg_restore -U postgres -d gophenberg < gophenberg.dumpdocker compose up -dRunning 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.
Restoring on a server install
Section titled “Restoring on a server install”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:
sudo systemctl stop gophenbergsudo -u postgres dropdb gophenbergsudo -u postgres createdb --owner=gophenberg --encoding=UTF8 --template=template0 --locale-provider=icu --icu-locale=und gophenbergsudo -u gophenberg pg_restore -d gophenberg /opt/gophenberg/backups/1.4.0-20261020T120000Z.dumpdropdbdeletes the database the new build migrated, for good.- The database keeps its name,
gophenberg, since everysudo gophenberg server:installwritesGOPHENBERG_DATABASE_URLback to it. createdbmakes 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_restoreruns asgophenberg, which owns the database and can read the backup.
Then point current back at the build before the update, and start
the site:
sudo -u gophenberg ln -sfn versions/1.4.0 /opt/gophenberg/currentsudo systemctl reset-failed gophenbergsudo systemctl start gophenbergOn 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.