What Pursae is, what it needs, how to install it with Docker or as a single binary, how the first-run installer works and how updates and rollbacks are handled.
Pursae is WordPress core rewritten in Go. It ships as one static binary that talks to a PostgreSQL database and serves the familiar WordPress admin (/wp-admin/), the block editor, the wp/v2 REST API, classic themes and a page builder. Plugins are WebAssembly packages that run in a sandbox with the permissions you grant at activation, so a broken plugin cannot take the site down or read what it was not allowed to.
Admin — Dashboard, Posts, Pages, Media, Comments, Appearance (Themes, Customize, Widgets, Menus, Theme File Editor), Plugins, Users, Tools, Settings; same markup and CSS as WordPress.
Editors — the block editor (Pursae Editor, built on the @wordpress/* packages) and a built-in Classic Editor plugin (TinyMCE).
Pursae Web Builder — a section-based visual page builder that publishes pages as static HTML; off on a fresh install.
REST API — wp/v2 with cookie + nonce and Application Password authentication.
Themes — bundled themes plus code-free theme packages uploaded as a zip.
Pursae Cache — a built-in full-page cache with tag-based purging.
System — migrations on start, a job runner for scheduled events and e-mail, WXR import/export.
18 built-in plugins — Commerce, Web Builder, SEO, Cache, Security, CDN, Headless, Cookie, Pixel, Analytics, Forum, SMTP, Custom Fields, Multi Language, Contact Form, Maintenance, Backup Manager, Classic Editor. All are off on a fresh install except Pursae Cache and Classic Editor.
Architecture
One static binary (CGO_ENABLED=0) with the admin, the editors and the bundled themes embedded.
gin for HTTP, pgx on PostgreSQL 17 (14+ works); migrations run on start.
Plugins run as WebAssembly in wazero — no cgo, no separate runtime.
Not supported PHP plugins and PHP themes (themes are Go templates with a theme.json manifest), and multisite.
You need Docker (Docker Desktop on macOS/Windows, Docker Engine with Compose v2 on Linux) and git; make is optional.
On a server (production build)
The production build talks to https://hub.pursae.com, so core updates are one click in Dashboard › Updates. Settings go in docker/.env (git-ignored).
git clone https://github.com/pursae/pursae.git
cd pursae
cp docker/.env.example docker/.env # set WPGO_DB_PASSWORD, WPGO_SITE_URL (https://…), WPGO_SMTP_*, WPGO_MAIL_FROM
make prod-up # site on 127.0.0.1:8088; point Caddy or nginx at it
make prod-logs follows the log, make prod-down stops the stack (data is kept). Put a TLS proxy in front, then open the https:// address.
Run the installer right away. Until the installer is finished, anyone who reaches the site can run it and become its administrator.
On your machine (development build)
git clone https://github.com/pursae/pursae.git
cd pursae
make docker-up
# without make:
docker compose -f docker/compose.yaml up -d --build
This development build does not talk to hub.pursae.com (no core updates; it looks for a local Pursae Manager instead), uses the test database password wpgo and trusts the demo plugin signing key. Use it to try Pursae, not to run a site. The first build downloads Go modules and compiles the binary (a minute or two); then open http://localhost:8088 and you land on the installer.
Service
What it is
Host port
wpgo
the Pursae server
8088 (production: 127.0.0.1:8088)
db
PostgreSQL 17
127.0.0.1:5432 (production: not published)
Another port or address
The site URL is written into the settings at install time, so set it before the first run:
WPGO_PORT=9000 WPGO_SITE_URL=http://localhost:9000 make docker-up
# reach it from another device on your LAN:
WPGO_SITE_URL=http://192.168.1.50:8088 make docker-up
Installed with the wrong URL already? Change it under Settings › General or start over (see Troubleshooting).
Volumes
Compose keeps state in named volumes, so docker compose down loses nothing.
Volume
Mounted at
Contains
pgdata
/var/lib/postgresql/data
the database
bin
/data/bin
the running binary; Dashboard › Updates replaces it
uploads
/data/uploads
media library files
plugins
/data/plugins
installed plugin packages
themes
/data/themes
theme packages and files edited in the Theme File Editor
pagecache
/data/wpgo-cache
Pursae Cache disk copy (can be rebuilt)
languages
/data/languages
downloaded language packs
backups
/data/backups
Tools › Backups archives (scheduled and manual)
mail
/data/mail
.eml files of messages sent without SMTP
Everyday commands
make docker-up # development: build and start in the background
make docker-down # stop; data is kept
make prod-up # production: with docker/compose.prod.yaml and docker/.env
make prod-down # stop the production stack (data is kept)
make prod-logs # follow the production server log
make test # unit tests + PostgreSQL integration tests
make docker-test # the same suite inside a Go container
make build # compile bin/wpgo
make builder # rebuild the Web Builder editor into web/web-builder (needs Node 22+)
docker compose -f docker/compose.yaml logs -f wpgo
docker compose -f docker/compose.yaml restart wpgo
Demo signing key The compose file sets WPGO_TRUST_DEV_KEY=1 so the bundled example plugins install. That is for development only: make prod-up adds docker/compose.prod.yaml, which turns it off.
You need Go 1.27 and a PostgreSQL database (14 or newer; the compose file uses 17) that the configured user can create tables in.
Build
git clone https://github.com/pursae/pursae.git
cd pursae
make build # writes bin/wpgo
make build is CGO_ENABLED=0 go build -o bin/wpgo ./cmd/wpgo: a static binary with the admin, the editors and the bundled themes embedded. Copy it anywhere.
Run
export DATABASE_URL='postgres://wpgo:wpgo@localhost:5432/wpgo?sslmode=disable'
export WPGO_SITE_URL='https://blog.example.com' # the public address, without a trailing slash
export WPGO_UPLOADS_DIR=/var/lib/wpgo/uploads
./bin/wpgo serve
On start the server runs the database migrations (under an advisory lock, so several instances can start at once), creates the uploads directory and listens on WPGO_ADDR (default :8080). Open the site and the installer appears.
Command
Does
wpgo serve
migrate, then serve (the default)
wpgo migrate
apply pending migrations and exit
wpgo version
print the version
Other subcommands referenced in the docs: wpgo launch (the Docker entrypoint), wpgo healthcheck / wpgo healthcheck ready, wpgo mcp (MCP stdio bridge) and wpgo adminsec disable-hide-login.
Development mode
Read templates, CSS and JS from the working tree instead of the embedded copy, so edits show on refresh:
make db # starts only PostgreSQL from the compose file
WPGO_WEB_DIR=web go run ./cmd/wpgo serve
make dev does both. make test runs the unit tests and the PostgreSQL integration tests against the compose database, one package at a time; they drop and recreate the database TEST_DB names (default wpgo_test), so give each checkout running tests at once its own, e.g. make test TEST_DB=wpgo_test_feature.
Until the site is installed every request redirects to /wp-admin/install — the same five-minute install as WordPress:
Site title
Username and password of the first administrator
Email of that administrator
whether to ask search engines not to index the site
The installer creates the "Hello world!" post with its first comment, the Sample Page, a draft Privacy Policy page and the default sidebar widgets. Then sign in at /wp-login.
No .php needed Admin URLs have no .php suffix (/wp-admin/edit, /wp-login). WordPress spellings (/wp-admin/edit.php, /wp-login.php) still work: GET requests redirect permanently and POSTs are served in place, so bookmarks, clients and tutorials keep working.
The admin
Menu
Notes
Posts, Pages, Media, Comments
the block editor opens by default; switch to the Classic Editor under Settings › Writing
Installed Plugins, Add Plugin (marketplace, upload); activating a plugin shows the permissions it asks for
Users
roles administrator, editor, author, contributor, subscriber, with per-user capability overrides
Tools
Import and Export (WXR), Site Health, personal data export and erasure
Settings
General, Writing, Reading, Discussion, Media, Permalinks, Privacy, plus pages plugins add
Pursae Cache
the built-in page cache
Write a post
Posts › Add New opens the block editor. Write, add media (the Media Library modal is the real wp.media), pick categories and tags, then Publish. The post appears on the front page with the active theme and in the REST API at /wp-json/wp/v2/posts. Plugin shortcodes such as [gopher-facts] can be typed in a Shortcode block or a paragraph; the plugin expands them at render time.
Pretty permalinks
Settings › Permalinks offers the WordPress structures (/%year%/%monthnum%/%postname%/, /%postname%/, …). No web-server rewrite rules are needed: the Go server routes them itself.
Next steps
Install a theme: Appearance › Themes › Add Theme.
Install a plugin: Plugins › Add Plugin, or upload a package.
Put the site behind TLS (see Reverse proxy & TLS).
Coming from WordPress: export with Tools › Export (WXR) there, import with Tools › Import here — posts, pages, terms, comments, menus, and media fetched from their public URLs. Products move with WooCommerce's product CSV. Users' passwords, settings, PHP plugins and themes do not move.
A production site updates itself from Dashboard › Updates in one click; when a newer release exists, every admin page says Pursae X is available! Please update now. Otherwise you replace the binary (or rebuild the image) and start it. Development builds (make docker-up, make dev) get no updates from https://hub.pursae.com. Database migrations run automatically on start, before the server listens.
What a one-click update does
When Pursae Manager publishes a release built for the site's platform (core.artifacts in GET /api/v1/index has the running GOOS/GOARCH), Dashboard › Updates shows Update to version X. The site then:
downloads the binary from the Manager (at most 1 GB), checking its size and SHA-256;
verifies the Ed25519 signature by the Manager key named in the release over pursae-core-v1\n{version}\n{os}-{arch}\n{sha256 hex};
runs the downloaded binary once (version): a binary this system cannot start, or one that reports another version, is refused while nothing has changed;
keeps the running binary as <executable>.prev, records the update in <executable>.update.json and renames the new binary over the old one;
shows Updated, restarting…, records a core_update event and re-executes itself; the new version runs its migrations on start.
The restart does not drop visitors: the listening socket is handed to the new binary (WPGO_LISTEN_FD), in-flight requests finish first (up to 10 seconds), and new connections wait in the kernel queue until the new version accepts them — a second or two, no error page, also behind a proxy such as Traefik in Dokploy.
Automatic rollback
The new binary confirms the update once it answers requests (within two minutes); until then .update.json stays pending. If it dies first and is started again — by Docker's restart: unless-stopped, systemd's Restart=always or another supervisor — the second start puts <executable>.prev back and runs it, and Dashboard › Updates says Pursae X did not start, so the site went back to Y. If re-executing fails outright, the previous binary is put back at once.
Run under a supervisor Without one, nothing restarts a crashed process. Migrations are forward-only: a rolled-back site keeps any migration the new version applied, which is why releases only add schema.
Keeping and reinstalling the previous version
Once confirmed, .update.json records confirmed (with the version the site came from) and <executable>.prev is kept for 24 hours, then removed (checked at start and every hour). A site never holds more than one extra binary, and only for a day.
Dashboard › Updates › Previous version offers Reinstall version Y: within 24 hours the kept .prev is checked and swapped back (no download); later the signed build of Y is downloaded again from Pursae Manager (GET /api/v1/core/{version}) and verified like an update. Without a Manager the button is hidden once .prev is gone.
A reinstall is recorded as a pending update, so a reinstalled binary that does not start goes back too. It never happens on its own; migrations of the newer version are not undone (the button asks for confirmation) — restore a backup when the older version cannot work with them.
Nothing is replaced when a check fails. The button is replaced by the reason when the executable cannot be replaced (a go run build, or a directory the server may not write). Beta releases are offered only to sites whose license includes the beta channel.
Static release builds
CGO_ENABLED=0 go build -buildmode=exe -tags nodynamic -ldflags "-X wpgo/internal/server.Version=0.2.0" ./cmd/wpgo
make build and make release do this. Static matters: Go's default Linux build asks for the build host's ELF interpreter, and nodynamic keeps the AVIF decoder off purego — such a binary built on a glibc machine does not start in the Alpine image.
Docker
The image starts with wpgo launch: it installs its binary into the bin volume (/data/bin, WPGO_BIN_DIR) and runs it from there, so an admin update survives container restarts. A newer image wins when its binary reports a higher version; a rebuilt image with the same version (development builds without VERSION) also wins when its binary differs; an installed binary with a higher version (an admin update) is kept.
git pull && make prod-up # production from source; migrations run on start
git pull && make docker-up # development stack
Binary
git pull
make build
systemctl restart wpgo # or however you run it
Several instances may start at once: the migration runner takes a PostgreSQL advisory lock and applies missing migrations once. wpgo migrate applies them without serving, handy in a deploy step.
Before you upgrade
Back up the database and the uploads directory. Migrations are forward-only; the backup is your rollback.
Read the release notes (shown on Dashboard › Updates when connected to the Hub).
Check plugin compatibility: a plugin's plugin.json names the minimum core version (requires); the Plugins screen refuses to activate one that needs a newer core.
Manual rollback
Stop the new version, restore the database backup, start the previous binary. Uploads, plugin packages and theme packages are plain files and are not changed by an upgrade.
Plugins and themes
Update packages through Plugins › Add Plugin and Appearance › Add Theme (upload a newer package or install from the marketplace). Re-installing a plugin with the same slug replaces the package and keeps the granted permissions; deactivate and activate it to load the new version, and review the permissions on the activation screen.
Headers, footers and single, page, custom post type, front page, archive, search and 404 templates are designed in Web Builder › Theme Builder and shown by the new bundled theme Hello Pursae. Migration 0029_web_builder_templates.sql adds the wb_template post type; nothing existing changes.
Sites with the plugin already on are not switched: a one-time Switch to Hello Pursae (or Dismiss) notice appears. From now on, activating the plugin switches to Hello Pursae (with a Switch back link) and deactivating switches back.
Older builder pages with their own navigation or footer section keep rendering as full-page canvases; each page can choose under Header & footer in its page settings.
The builder's API version is now 2: an editor tab left open across the upgrade asks to reload. Published pages need no regeneration.
Public Pursae Custom Fields post types now have pretty permalinks (/<slug>/<post>/) and optional archives; old ?p=<id> links redirect. Check that no page or post reuses a custom post type's rewrite or archive slug.
New Pursae Web Builder (old builder data is deleted)
Back up the database first. The release that brings the new builder replaces the previous Elementor-derived builder and deletes everything it stored, with no converter (migration 0028_drop_old_builder). Restoring the backup is the only way back.
Deleted: its tables (revisions, global classes and variables, default styles, form submissions), saved templates, theme parts, popups and components, every _elementor_*/_gwe_* post meta key, its options and the themes saved with it. Pages keep their content as plain HTML; pages on the old Canvas or Full Width template go back to the theme's default template. Generated CSS, form uploads and custom icon sets are removed from uploads at the next start (local fonts stay); a site on Hello Web Builder or a theme saved with the old builder moves to its previous theme or Twenty Twenty-Five. Old builder pages open in the new builder as new documents — rebuild and publish them.
Operations
Running Pursae in production
Every environment variable, the Docker setup, proxies and TLS, caching, scheduled jobs, mail, backups, security, the Hub connection, releases, troubleshooting and AI agents over MCP.
Pursae is configured entirely through environment variables. Everything else (site title, permalinks, mail sender, cache settings, trusted plugin keys) lives in the options table and is edited in the admin.
public URL without a trailing slash; written to the siteurl and home options by the installer
WPGO_UPLOADS_DIR
./data/uploads
media library files. Next to it: plugins (../plugins), compiled-plugin cache (../plugin-cache), themes (../themes) and development mail (../mail)
WPGO_SECRET
generated on first start, stored in the settings
secret for session cookies and nonces. Set it when several instances share one database
WPGO_WEB_DIR
embedded
read admin/theme templates, CSS and JS from this directory, reloading per request (development)
WPGO_EMPTY_TRASH_DAYS
30
days trashed posts and comments are kept before the daily wp_scheduled_delete job removes them. 0 empties the trash at every daily run (Trash links stay visible)
WPGO_LOG_FORMAT
text
json writes the access log as one JSON object per request (status, method, uri, duration, ip, request_id)
WPGO_BACKUPS_DIR
backups/ next to uploads
Backup Manager archives (manual, scheduled, safety snapshots). Keep it outside the publicly served uploads
WPGO_LANG_DIR
languages/ next to uploads
installed language packs
WPGO_TRANSLATIONS_API
https://api.wordpress.org/translations
where language packs are downloaded from (a mirror, or a fake in tests)
WPGO_BIN_DIR
— (/data/bin in the image)
persistent directory wpgo launch installs the binary into, so admin updates survive container restarts
WPGO_LISTEN_FD
—
internal: set when the socket is handed to an updated binary; do not set it yourself
WPGO_PLUGINS_DIR
— (../plugins next to uploads)
plugin packages directory; every instance needs the same volume (mentioned on the Docker page)
Database pool
DATABASE_URL takes pgx pool parameters as query parameters; each one left out gets the default below (pgx alone would allow only max(4, CPUs) connections).
Parameter
Default
Meaning
pool_max_conns
4 × CPUs, at least 10, at most 40
connections per instance. Keep the sum over all instances (plus backups and psql) under PostgreSQL's max_connections (100 by default)
pool_min_conns
2
connections kept open when idle
pool_max_conn_lifetime
1h (+ up to 5 min jitter)
a connection is replaced after this long
pool_max_conn_idle_time
15m
idle connections above the minimum are closed after this long
theme packages (<slug>/theme.json) and overrides saved by the Theme File Editor
WPGO_THEME_LIBRARY_DIR
— (library comes from the Hub)
serve Add Themes › Library from a local directory of theme packages (development, offline sites; the repository's is library/themes). Hub downloads are cached in theme-library-cache/ next to uploads
WPGO_DISALLOW_FILE_EDIT
off
1/true makes the Theme File Editor read-only (like DISALLOW_FILE_EDIT)
WPGO_PLUGIN_KEYS
—
comma-separated base64 Ed25519 public keys trusted to sign plugin packages, in addition to the plugin_trusted_keys option
WPGO_MARKET_DIR
examples/plugins/dist, then /usr/share/wpgo/plugins
a directory of .zip packages offered on Plugins › Add Plugin
WPGO_TRUST_DEV_KEY
unset (1 in compose)
trust the dev-key.pub in the market directory. Development only
WPGO_EXPOSE_USERS
unset
1 lets visitors list accounts (public REST users, /?author=N, users sitemap); off because those routes disclose account names
WPGO_TRUSTED_PROXIES
loopback and private ranges
proxies (comma-separated IPs or CIDRs) whose X-Forwarded-For / X-Real-IP is believed; none trusts no proxy
WPGO_HUB
unset (on)
off switches Pursae Manager (hub.pursae.com) off in any build: nothing is sent, and no update notices, one-click updates, marketplace or licenses. Every admin page warns until removed and restarted. Not recommended
WPGO_DEV_HUB_URL
unset (http://pursae-manager.test:8090 in the development compose file)
devhub builds only: the Manager to use instead of https://hub.pursae.com (https, or http on localhost / *.localhost / *.test); off disables it. Production binaries ignore it
WPGO_TRUST_HUB_KEYS
unset (1 in the development compose file)
devhub builds only: 1 trusts every key the Manager lists, endorsed by the release root or not. Production binaries ignore it
Pursae Manager and devhub builds
Every Pursae install talks to Pursae Manager at https://hub.pursae.com. A production binary has no variable or option that changes this address or relaxes key checking: the Pursae release root key is pinned in it, and only Manager keys endorsed by that root verify core self-updates and Manager-signed plugins. The ROOT_KEYS build arg (-ldflags -X wpgo/internal/server.rootKeysLinked=…) adds release roots for a key rotation; it never removes the pinned one.
go run -tags devhub ./cmd/wpgo serve # make dev does this
docker compose -f docker/compose.yaml up # builds with GO_TAGS=devhub
A devhub binary reads WPGO_DEV_HUB_URL (pursae-manager.test is an extra_hosts alias for the host gateway) and WPGO_TRUST_HUB_KEYS=1, so a local Manager's throwaway key verifies releases and plugins. The production compose file builds with GO_TAGS="" and drops both variables.
Never ship a devhub binary.
Editing theme files
Appearance › Theme File Editor works without recompiling. Saving writes an override into /data/themes (or WPGO_THEMES_DIR); the template set is re-parsed and the page test-rendered. A template or render error is rolled back automatically and shown. Restore original removes the override.
Configuration: content, built-in plugins, compose and tests#
Content
Variable
Default
Meaning
WPGO_POST_REVISIONS
25
revisions kept per post (WordPress' WP_POST_REVISIONS); older ones are deleted on save, Web Builder publishes included. Negative keeps every revision. Tools › Revisions deletes the excess of existing posts
Post search stems words in the site language (Settings › General › Site Language → the PostgreSQL text search configuration, e.g. english, turkish; simple when there is none). Changing the language rebuilds the vectors in the background.
Built-in plugins
Variable
Default
Meaning
WPGO_ADMINSEC_DISABLE_HIDE_LOGIN
unset
recovery switch for Pursae Security's custom login URL: 1/true/yes brings /wp-login back while set (restart after setting). wpgo adminsec disable-hide-login turns the setting off for good
WPGO_CDN_SETTINGS
unset
Pursae CDN settings as one JSON object (keys of the gocdn_settings option, e.g. {"provider":"aws","bucket":"media",…}). Overrides saved settings and shows read-only, so credentials stay out of the database. Invalid JSON is ignored with a log warning
The WPGO_BUILDER_AI* variables in internal/webbuilder/contract.go belong to the Web Builder AI module, which is not shipped; setting them has no effect.
Compose only
make prod-up reads these, WPGO_SITE_URL, the mail settings and WPGO_PLUGIN_KEYS / WPGO_TRUSTED_PROXIES from docker/.env (template: docker/.env.example).
Variable
Default
Meaning
WPGO_PORT
8088
host port for the site
WPGO_BIND
127.0.0.1
host address the site is published on, with compose.prod.yaml only (the development file publishes on every interface)
WPGO_DB_PORT
5432
host port for PostgreSQL on 127.0.0.1, development file only; production does not publish PostgreSQL
WPGO_DB_PASSWORD
— (required)
database password, compose.prod.yaml only (the development file uses wpgo); applied when the pgdata volume is created
Test suite
Variable
Default
Meaning
WPGO_TEST_ADMIN_DB
—
connection used to drop and recreate the test database
WPGO_TEST_DB
—
test database URL; both unset skips the integration tests
TEST_DB (make variable)
wpgo_test
database make test drops and recreates
WPGO_I18N_MISSES
—
development: append every untranslated UI string to this file (JSON lines); WPGO_I18N_MISSES_* are read by the i18n coverage tests only
Options worth knowing (database, not env)
Option
Where
Meaning
plugin_trusted_keys
—
newline- or comma-separated public keys, merged with WPGO_PLUGIN_KEYS
"" (default): JPEG sizes for WebP uploads (PNG with transparency); webp: WebP sizes for WebP uploads; webp-all: WebP for JPEG, PNG and WebP uploads, the image itself saved as WebP (photo.jpg → photo.webp, or photo-scaled.webp above 2560 px). Quality 86, no cgo. Filter: image_editor_output_format. Existing images are not regenerated
docker/Dockerfile is a two-stage build: golang:1.27-alpine compiles a static binary; the final stage is alpine:3.22 with ca-certificates and tzdata, an unprivileged user wpgo (uid 10001) and the data directories /data/uploads, /data/plugins, /data/plugin-cache, /data/mail, /data/themes, /data/wpgo-cache, /data/languages, /data/bin and /data/backups. Entrypoint wpgo launch, default command serve, exposed port 8080. Example plugin packages from examples/plugins/dist are copied to /usr/share/wpgo/plugins if they exist.
postgres:17-alpine, database wpgo, user and password wpgo, health-checked with pg_isready, published on 127.0.0.1:${WPGO_DB_PORT:-5432}
wpgo
the site, built from the Dockerfile (GO_TAGS=devhub), waits for a healthy database, restart: unless-stopped
test
profile test: runs go test ./... -p 1 in a Go container against the same database (make docker-test)
DATABASE_URL: postgres://wpgo:wpgo@db:5432/wpgo?sslmode=disable
WPGO_SITE_URL: ${WPGO_SITE_URL:-http://localhost:8088}
WPGO_UPLOADS_DIR: /data/uploads
WPGO_TRUST_DEV_KEY: ${WPGO_TRUST_DEV_KEY:-1} # demo only
WPGO_DEV_HUB_URL: ${WPGO_DEV_HUB_URL:-http://pursae-manager.test:8090} # devhub builds only
WPGO_TRUST_HUB_KEYS: ${WPGO_TRUST_HUB_KEYS:-1} # devhub builds only
WPGO_TRUSTED_PROXIES: ${WPGO_TRUSTED_PROXIES:-}
WPGO_SMTP_HOST: ${WPGO_SMTP_HOST:-} # without a host: .eml files in /data/mail
WPGO_SMTP_PORT: ${WPGO_SMTP_PORT:-587}
WPGO_SMTP_USER: ${WPGO_SMTP_USER:-}
WPGO_SMTP_PASS: ${WPGO_SMTP_PASS:-}
WPGO_MAIL_FROM: ${WPGO_MAIL_FROM:-}
Add anything else from the configuration reference to the environment, for example WPGO_PLUGIN_KEYS.
Production changes (compose.prod.yaml)
make prod-up adds compose.prod.yaml with settings from docker/.env. It refuses to start until WPGO_DB_PASSWORD and WPGO_SITE_URL are set, and:
builds without the devhub tag (updates only from https://hub.pursae.com; WPGO_DEV_HUB_URL / WPGO_TRUST_HUB_KEYS removed);
takes the database password from WPGO_DB_PASSWORD (for POSTGRES_PASSWORD and DATABASE_URL);
does not publish PostgreSQL; publishes the site on 127.0.0.1:8088 only (WPGO_BIND changes the address);
sets WPGO_TRUST_DEV_KEY=0, passes WPGO_PLUGIN_KEYS and WPGO_TRUSTED_PROXIES through, restarts both services unless stopped and sets stop_grace_period: 35s.
Changing the DB passwordPOSTGRES_PASSWORD only applies when the pgdata volume is first created; on an existing database change it first with ALTER USER wpgo PASSWORD '...'.
Production checklist
Put a TLS-terminating proxy in front and set WPGO_SITE_URL to the https:// address.
Finish the installer right after the site goes live.
For real plugins list your own signing keys in WPGO_PLUGIN_KEYS.
Configure SMTP (WPGO_SMTP_*, WPGO_MAIL_FROM) so password resets are delivered.
Back up pgdata, uploads, plugins and themes; copy the backups volume off the server.
Set WPGO_SECRET explicitly if you run more than one wpgo replica.
Update from Dashboard › Updates; pick a strong admin password.
Both are unauthenticated, answer before maintenance mode, Pursae Security and the page cache, send Cache-Control: no-store and are not logged. The image's HEALTHCHECK runs wpgo healthcheck (asks /healthz on WPGO_ADDR; wpgo healthcheck ready asks /readyz), so no curl is needed.
Shutdown, timeouts and limits
On SIGTERM: stop accepting, let in-flight requests finish (up to 10 s), stop the job runner (up to 10 s), drain background writes — 404 log, counters, pending CDN purges (up to 5 s) — then close the pool. Docker's default grace is 10 s, hence stop_grace_period: 35s; use the same for terminationGracePeriodSeconds.
Request headers: 10 s; idle keep-alive: 120 s; a request body with no progress for 60 s fails. No overall read/write timeout (backups, imports, slow uploads and Headless subscription streams run for minutes) — put per-request limits in the proxy.
Request body limit: 512 MB (the largest upload a screen accepts is a 256 MB WXR import); the Backup Manager import takes archives up to 16 GB. Larger bodies get 413.
Every response carries an X-Request-ID (the proxy's when sane, else generated); the access log line ends with id=<request id>.
The wpgo service has restart: unless-stopped (it also brings back a core update that did not start); compose.prod.yaml adds it to db too. Instances sharing one database compare the plugins table with what they loaded every 10 seconds; plugin packages live in WPGO_PLUGINS_DIR, so every instance needs the same volume.
Pursae serves plain HTTP. Terminate TLS in a proxy and set WPGO_SITE_URL to the public https:// address (or change Settings › General after installing). The server trusts X-Forwarded-Proto: https to treat a request as secure: it then sets Strict-Transport-Security and secure cookies, and generates https:// links.
Visitor IPs and trusted proxies
Send X-Forwarded-For so login throttling, the comment flood check, the Pursae Security IP block list, the maintenance IP whitelist and the logs see the visitor's address. It is believed only from a trusted proxy: by default loopback and private ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, ::1, fc00::/7). If your proxy has a public address, list it in WPGO_TRUSTED_PROXIES; none trusts no proxy.
Why it matters Without a trusted proxy, every visitor shares the proxy's address and five failed logins from one visitor lock everybody out for 15 minutes. Conversely, any machine on the trusted private networks that reaches the port directly could pick its own address — publish the port only where the proxy can reach it, or set WPGO_TRUSTED_PROXIES to exactly your proxy. With an https:// site URL and no WPGO_TRUSTED_PROXIES, the server logs a reminder at start-up.
Sub-requests of /batch/v1 cannot set X-Forwarded-*, X-Real-IP or Forwarded themselves; they carry the outer request's headers.
Caddy
blog.example.com {
reverse_proxy 127.0.0.1:8080
}
Caddy sets the forwarded headers, obtains certificates and passes WebSocket upgrades on its own.
Static files (/wp-includes/, /wp-admin/css/, theme and plugin assets) are served by the binary with long cache headers, so no root or try_files is needed. nginx may cache them in a proxy_cache; Pursae Cache can emit X-Accel-Expires for whole pages.
GraphQL subscriptions (Pursae Headless)
Subscriptions are delivered as server-sent events and over a WebSocket on /wp-json/headlessgo/v1/graphql. SSE needs nothing more (responses carry X-Accel-Buffering: no). A WebSocket needs the upgrade headers:
location = /wp-json/headlessgo/v1/graphql {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 120s; # the server pings every 20 s
}
Apache needs mod_proxy_wstunnel (or ProxyPass / http://127.0.0.1:8080/ upgrade=websocket on 2.4.47+). Keep the Host header: a browser WebSocket is accepted only from the site's own origin or a CORS origin of the Headless settings.
Apache
<VirtualHost *:443>
ServerName blog.example.com
SSLEngine on
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>
/etc/wpgo.env holds DATABASE_URL, WPGO_SITE_URL, WPGO_UPLOADS_DIR, WPGO_SECRET and the mail settings.
Several instances
Run as many wpgo processes as you like against one database with a shared uploads directory (NFS or an object-storage mount). Give every instance the same WPGO_SECRET.
The scheduler claims jobs with FOR UPDATE SKIP LOCKED (events run once); migrations are serialised with an advisory lock.
Settings are cached per process; changes reach other instances via PostgreSQL LISTEN/NOTIFY within moments (one extra connection each, plus a reload every minute).
Side effects of saving a setting (starting a plugin, reconfiguring the cache) run only on the saving instance — restart the others after switching plugins on or off.
Every cache purge is broadcast on the wpgo_cache_purge channel; an instance whose listener reconnects empties its page cache.
Headless GraphQL subscriptions see only changes made through the instance the client is connected to; use its webhooks across instances.
Pursae Cache is a built-in plugin, on by default, modelled on LiteSpeed Cache but server-agnostic. It caches rendered public pages inside the Go process (memory LRU, optional disk persistence), purges them precisely by tags, and can tell a front proxy or CDN to cache them too. Admin menu: Pursae Cache (Dashboard, Cache, Page Optimization, Toolbox).
What is cached
GET requests of the public site from visitors who are not logged in and carry no comment-author cookie. Responses that set cookies, send Cache-Control: private/no-store/no-cache, have Content-Encoding, or are marked X-WPGo-Cache-Control: no-cache (forms with nonces) are never cached. Responses carry X-WPGo-Cache: hit|miss|bypass. Search results are not served from the page cache.
Settings (Pursae Cache › Cache)
Option
Default
Meaning
wpgo_cache_enabled
on
the plugin (switched on the Plugins screen)
wpgo_cache_serve
—
the Enable Cache switch: stops caching but keeps the plugin and its screens
wpgo_cache_ttl_public
7 days
TTL of posts, pages and archives
wpgo_cache_ttl_front
7 days
TTL of the front page
wpgo_cache_ttl_feed
7 days
TTL of feeds
wpgo_cache_ttl_404
1 hour
TTL of not-found pages
wpgo_cache_mobile
off
separate entries for mobile user agents
wpgo_cache_logged_in
off
cache for logged-in users too (per user)
wpgo_cache_exclude_uri
—
one path prefix per line that is never cached
wpgo_cache_drop_qs
—
query parameters ignored for the cache key (tracking parameters)
wpgo_cache_disk
off
persist entries to disk so they survive a restart
wpgo_cache_server
auto
proxy headers to emit: auto, litespeed, nginx, generic, none
wpgo_cache_warm_result
—
last result of the crawler
Other Cache Settings: Cache Query Strings, Do Not Cache Cookies, Do Not Cache User Agents, Browser Cache TTL, 301 Redirect TTL, Memory Limit, Preload (after every purge, 30 s debounced, and daily). The crawler takes its URLs from the core sitemap providers (home, every public post type, taxonomy and author).
Page Optimization (wpgo_opt_*): lazy-load images (skipping the first ones above the fold), defer scripts / Defer All JavaScript with an exclude list, Delay JavaScript (scripts with a listed fragment load on first interaction or after a timeout), minify HTML, inline CSS minification, preload the theme's fonts, preconnect / dns-prefetch origins.
Tags and purging
Every cached page is tagged (home, post:12, term:3, author:1, media:7, feed, date:2026-10, archive:post, 404, search).
Publishing or editing a post purges its page, the home page, feeds, its author and term archives, its dates (and 404, since the new URL may have been cached as a 404).
Comments purge the post; editing or deleting a term purges pages listing or linking it; editing or deleting media purges pages showing it as a featured image.
Settings, theme, menu and widget changes, and saving a plugin settings page, purge everything. Plugins changing posts through the posts API trigger the same purges.
A render that overlaps a covering purge is sent to the visitor but not stored — the purge always wins. Concurrent misses of the same anonymous page render once; the others wait (up to 10 s) and are served from the cache.
The admin bar has Purge this page and Purge all; Toolbox has a crawler that warms the cache after a purge. With several instances every purge reaches all of them.
Front proxies and CDNs
wpgo_cache_server
Headers emitted
litespeed
X-LiteSpeed-Cache-Control, X-LiteSpeed-Tag
nginx
X-Accel-Expires for proxy_cache / fastcgi_cache
generic
Cache-Control: s-maxage, Surrogate-Key and Cache-Tag (Varnish, Fastly, Cloudflare)
auto
LiteSpeed headers only when the request came through LiteSpeed; nothing otherwise
none
in-process cache only
Purges reach the proxy. Set Front Server Purge URL and every purge is forwarded as a PURGE request: URL purges go to the purge URL plus the page path; tag purges carry Surrogate-Key, Cache-Tag and X-LiteSpeed-Purge listing prefixed tags (wpgo_ by default); a full purge sends X-Purge-All: 1 and X-LiteSpeed-Purge: *. Requests run in the background with a 5 s timeout. Without a purge URL, Front Server Lifetime (default 300 s) caps s-maxage, X-Accel-Expires and X-LiteSpeed-Cache-Control, and a warning is shown.
All three are stripped before the response leaves the process. Do not gzip inside the cache: it compresses once at store time and negotiates Accept-Encoding itself (an outer gzip layer must skip responses that already have Content-Encoding). A janitor drops expired entries; warmup runs in-process (e.g. Concurrency: 4, RatePerSecond: 10).
WordPress runs scheduled tasks when a visitor loads a page. Pursae has a real job runner: every 15 seconds each instance publishes due scheduled posts and claims due rows of the jobs table with FOR UPDATE SKIP LOCKED, so several instances never run a job twice. No visitor, no wp-cron.php, no system crontab.
A recurring event exists once (a unique index prevents duplicates when instances start together). Runs missed while down are not caught up one by one: the event runs once, then waits for its next slot, as wp_reschedule_event() does.
Built-in events
Job
Recurrence
Does
wp_scheduled_delete
daily
empties posts and comments trashed for 30 days (WPGO_EMPTY_TRASH_DAYS)
wp_scheduled_auto_draft_delete
daily
removes auto-drafts older than 7 days
delete_expired_transients
daily
drops expired transients
wp_session_gc
hourly
expires login sessions and old login attempts
wpgo_cache_janitor
hourly
drops expired page-cache entries
seogo_404_trim
hourly
keeps Pursae SEO's 404 log at the monitor's limit
wp_mail
one-off
delivers a queued e-mail
publish_future_post
every tick
publishes posts whose date has come
wpgo_backup_scheduled
daily or weekly
Backup Manager's scheduled local backup, only while a schedule is set; not recreated by ensureEvents
Plugin events
Plugins with the cron permission schedule their own hooks (cron_<name>) with an interval of at least a minute or as a one-off; those rows carry every:<seconds> as recurrence and the plugin slug in the payload.
Failures and retries
A failing job (error or panic) is retried after 1, 4, 9 and 16 minutes.
A one-off job is marked failed with the error text after the fifth failure.
A recurring job never fails for good: retries never pass its next regular run; after five failures in a row it waits for that run, keeping attempts and last_error for Site Health.
While running, locked_at is refreshed every minute; a running row with a lock older than ten minutes goes back to the queue.
On SIGTERM the job in hand gets a cancelled context and goes back to the queue without counting an attempt. Finished one-off jobs are kept for a week.
Inspecting
SELECT name, recurrence, status, run_at, attempts, last_error FROM jobs ORDER BY run_at;
Tools › Site Health lists scheduled events and failed jobs. A missing recurring event is recreated at the next start (ensureEvents). Tools › Scheduled Actions (/wp-admin/scheduled-actions, manage_options) lists the whole queue with status, runs, attempts and last error; a job that failed for good can be retried (clean attempt count) or deleted; running jobs cannot be deleted.
Background WXR imports
Tools › Import: upload the WXR file, assign authors and choose "Download and import file attachments"; the import runs as the wxr_import job with a progress screen and a report (kept for a week). The file sits in wxr-imports/ next to uploads (not served) and is removed afterwards. Re-importing is safe: existing posts and media are skipped.
Pursae sends the same e-mails WordPress does: new-user notifications, password resets, comment moderation and "new comment" notices, admin e-mail change confirmations, personal data export links. Messages are queued in the jobs table and delivered by the scheduler, so a slow SMTP server never delays a request.
Variable
Default
Meaning
WPGO_SMTP_HOST
—
SMTP server; without it messages become .eml files
WPGO_SMTP_PORT
587
465 means implicit TLS, anything else STARTTLS when offered
WPGO_SMTP_USER, WPGO_SMTP_PASS
—
credentials
WPGO_MAIL_FROM
<Site title> <wordpress@host>
sender; the host is taken from the site URL
WPGO_MAIL_DIR
mail/ next to uploads (/data/mail in Docker)
where .eml files go when SMTP is off
WPGO_SMTP_HOST=smtp.example.com
WPGO_SMTP_PORT=587 # 465 = implicit TLS; other ports use STARTTLS when offered
WPGO_SMTP_USER=postmaster@example.com
WPGO_SMTP_PASS=…
WPGO_MAIL_FROM='Example Blog <no-reply@example.com>'
With Docker, docker/compose.yaml passes these through. For make prod-up put them in docker/.env and run make prod-up again to apply a change.
Deliverability Set a real WPGO_MAIL_FROM so receiving servers accept the mail, and set up SPF/DKIM for it.
Failures are retried with back-off (1, 4, 9, 16 minutes); after five attempts the job is marked failed and appears in Tools › Site Health.
Development: .eml files
docker compose -f docker/compose.yaml exec wpgo ls /data/mail
Open a file in a mail client or read it as text to see, for example, the password reset link. In the admin, Settings › General holds the administration e-mail and Settings › Discussion decides which comment events notify. Pursae never contacts Gravatar or any other third party on its own.
A site is three things: the database, the uploads directory and the plugins and themes directories next to it. The binary and bundled themes need no backup.
What
Where (compose)
Where (binary)
database
volume pgdata
your PostgreSQL
media
volume uploads (/data/uploads)
WPGO_UPLOADS_DIR
plugin packages
volume plugins (/data/plugins)
<uploads>/../plugins
theme packages and edited theme files
volume themes (/data/themes)
WPGO_THEMES_DIR
Backup Manager archives
volume backups (/data/backups)
WPGO_BACKUPS_DIR
No backup needed for bin (the image or Dashboard › Updates puts one back), pagecache, languages (downloaded again) and mail.
Database
# dump (on a make prod-up stack add -f docker/compose.prod.yaml after -f docker/compose.yaml)
docker compose -f docker/compose.yaml exec db pg_dump -U wpgo -Fc wpgo > wpgo.dump
# restore into the same database
docker compose -f docker/compose.yaml exec -T db pg_restore -U wpgo -d wpgo --clean --if-exists < wpgo.dump
# your own PostgreSQL
pg_dump -Fc "$DATABASE_URL" > wpgo.dump
pg_restore -d "$DATABASE_URL" --clean --if-exists wpgo.dump
Files
docker run --rm -v wpgo_uploads:/data/uploads -v wpgo_plugins:/data/plugins -v wpgo_themes:/data/themes \
-v wpgo_backups:/data/backups -v "$PWD":/backup alpine tar czf /backup/wpgo-files.tgz /data
Volume names are prefixed with the compose project name, wpgo.
Moving a site
Dump the database and copy the files to the new host.
Start the new instance with the same WPGO_SECRET if existing sessions should survive.
Restore the dump, then update the URL under Settings › General if the address changed — once installed, the site URL lives in the database, not the environment.
Backup Manager
The built-in Backup Manager plugin (off by default) makes the same backup from the admin as one .zip (database rows as JSON lines plus the files), restores it on this or another site, and runs scheduled local backups (daily or weekly, keeping the newest N). Archives go to WPGO_BACKUPS_DIR, never inside the public uploads.
Copy archives off the server Scheduled backups stay on the same server; remote storage such as S3 or FTP is not included.
A restore keeps this site's own secret (auth_secret), address and Backup Manager settings. Secrets the built-in plugins store encrypted (SMTP passwords and tokens, CDN credentials, the Multi Language translation key, Security authenticator apps) are re-encrypted for this site; Pursae Security backup codes are stored only as hashes and must be generated again. If the source site encrypted with WPGO_SECRET, start this site with the same value.
Content export (WXR)
Tools › Export writes a WXR file with posts, pages, media references, comments and terms ("All content" also carries Pursae Custom Fields post types and taxonomies). Tools › Import reads one; items of unregistered post types are skipped and listed. It is a content transfer, not a backup: no passwords, settings, plugins or themes.
Passwords hashed with argon2id. Sessions are server-side rows tied to a random cookie (HttpOnly, SameSite=Lax, Secure behind TLS); 2 days, 14 with "Remember Me".
Login throttling: five failed logins from one address within 15 minutes block that address; twenty failures for one user name (from any address) block that name. Attempts are counted before the password check; REST Basic auth counts too. Unknown users cost as much time as wrong passwords, and at most twice as many password hashes as CPUs run at once.
Nonces protect every admin form and the REST API (X-WP-Nonce).
Security headers: X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, Referrer-Policy: strict-origin-when-cross-origin, a Content-Security-Policy (front end: script-src 'self' 'unsafe-inline', no remote scripts) and Strict-Transport-Security behind TLS.
Uploads are data, never code: /wp-content/uploads/ is served with a sandboxing CSP, so uploaded HTML or SVG cannot run scripts.
Content filtering: users without unfiltered_html and all plugins have their content filtered (KSES).
Sandboxed plugins: WebAssembly with no filesystem, no network except what the host allows, a memory cap, a per-call timeout and approved permissions. Packages are signed; only trusted keys install.
Multi-role users: capabilities are the union of the roles, with per-user allow and deny — deny wins.
No third-party calls: no Gravatar. The only service a site talks to is the Hub (see the next article).
Production checklist
Terminate TLS in a proxy and set WPGO_SITE_URL to the https:// address.
Start with make prod-up and settings in docker/.env; run the installer right after the site goes live.
List your own plugin signing keys in WPGO_PLUGIN_KEYS or plugin_trusted_keys; leave plugin_allow_unsigned off; WPGO_TRUST_DEV_KEY must stay 0.
Set WPGO_SECRET yourself when running several instances, and keep it secret.
Set WPGO_DISALLOW_FILE_EDIT=1 (or Pursae Security › Hardening › Disable file editors) if nobody should edit theme files; it covers the admin editors and the REST theme-file routes.
Let clients reach the server only through your proxy; set WPGO_TRUSTED_PROXIES to the proxy's address when other machines share its private network.
Configure SMTP so password resets arrive.
Back up the database and the data directories.
Review plugin permissions on activation. A plugin is disabled automatically after five consecutive failures.
Accounts are not listable by default: /?author=N answers 404, /wp/v2/users needs a login, the users sitemap is empty and the login form gives one message for unknown user and wrong password. Set WPGO_EXPOSE_USERS=1 only if you need a public author list. Author archives (/author/<nicename>) stay public and their slug comes from the login, so give publishing accounts a display name and nickname that differ from the login.
Keep the core up to date and rebuild images regularly (the build uses the latest golang:1.27 image); govulncheck ./... should stay clean.
Pursae Security (built-in plugin) adds two-step login, a custom login URL, lockouts and an activity log on top.
Reporting a vulnerability Open a private security advisory on the GitHub repository rather than a public issue.
Every production build talks to Pursae Manager at https://hub.pursae.com for updates, the theme and plugin marketplace and licenses.
When
What
Once a day (and a minute after a core update)
site URL, Pursae version, language, OS and CPU architecture, license key (if entered), active theme, and installed plugins and themes with versions, active state and origin (built in, Hub, uploaded)
As it happens (batched)
package actions: plugin installed/updated/activated/deactivated/deleted; theme installed/updated/activated/previewed/deleted; demo imported; core updated — each with slug, version and time
On every request to the Hub
site URL and license key as headers; the Hub also sees the server's IP address
It never receives your content, users, e-mail addresses, passwords, visitors, orders or anything else from your database. In return the site gets signed core updates (every binary signed by a Hub key endorsed by the release key built into Pursae), signed Wasm plugins, the theme library (checked against SHA-256), licenses for pro and beta packages and the product logo.
Turning it off
Set WPGO_HUB=off (with Docker: in docker/.env) and restart; the site sends nothing to hub.pursae.com. Remove it and restart to get updates again.
Not recommended With the Hub off the site gets no update notices or one-click updates — security fixes included — no marketplace, no signed plugins and no licenses; you replace the binary yourself for every release, and every admin page says so.
A release is a set of static binaries, one per platform, published as a GitHub release. Pursae Manager imports it, signs each binary's hash with its endorsed key, and every site sees the version under Dashboard › Updates. The Manager never compiles and keeps no copy; sites download from GitHub.
1. Build and publish
make release VERSION=0.2.0 # stable
make release VERSION=0.3.0-beta.1 BETA=1 # beta channel (a GitHub pre-release)
make release VERSION=0.2.0 DRY_RUN=1 # only build and check, into dist/release/v0.2.0
tools/release.sh:
refuses uncommitted changes or untracked files, or a tag v0.2.0 that points to another commit;
builds linux-amd64, linux-arm64, darwin-arm64, darwin-amd64 and windows-amd64 with CGO_ENABLED=0 go build -trimpath -buildmode=exe -tags nodynamic -ldflags "-s -w -X wpgo/internal/server.Version=0.2.0", checks that Linux binaries are static and that your machine's binary reports the version;
writes SHA256SUMS;
asks before publishing, then commits the version ("Pursae 0.2.0"), tags v0.2.0, pushes to the public remote and creates the GitHub release with the binaries (pursae-<os>-<arch>, .exe on Windows) and SHA256SUMS.
Setting
Default
Meaning
VERSION
—
version to release
BETA
—
1 publishes to the beta channel (GitHub pre-release)
DRY_RUN
—
1 only builds and checks
RELEASE_REPO
pursae/pursae
must be public; sites download without credentials
RELEASE_REMOTES
—
release setting (not detailed in the docs)
TARGETS
—
release setting (not detailed in the docs)
NOTES_FILE
GitHub's generated notes
release notes
YES
—
1 skips the question
Needs Go, git and the GitHub CLI (gh auth login).
2. Import it in Pursae Manager
Core › Import: tag, channel (stable, or beta for beta licenses), notes, Import Release. The Manager reads the release from the GitHub API, downloads each pursae-<os>-<arch> asset once, checks it against SHA256SUMS (and that Linux binaries are static), signs pursae-core-v1\n{version}\n{os}-{arch}\n{sha256}, stores hash, signature and GitHub URL, and publishes. A platform without a binary is not offered the release.
3. What sites do
At the next update check (daily, or on Dashboard › Updates) sites see the version. Update asks the Manager for the binary, follows the redirect to GitHub, checks the SHA-256 and signature, replaces the executable and restarts.
Never replace release assets A file replaced on GitHub after import fails the check and sites refuse it. Publish a new patch version instead (and consider GitHub's immutable releases).
Site redirects to /wp-admin/install again after a restart
The database is empty or a different one is used. Check the pgdata volume exists (docker volume ls) and DATABASE_URL points to the right database.
Docker restarted and the site is down
Containers do not always come back. Run make prod-up (production) or docker compose -f docker/compose.yaml up -d (development). Use the command your stack was started with — the development file on a production server brings back development settings and the wrong DB password.
Links/assets point at an old IP or port
The site URL was stored at install time. Change it under Settings › General, or start over with the right WPGO_SITE_URL.
Port 8088 or 5432 already in use (e.g. a local WordPress)
WPGO_PORT=9000 WPGO_DB_PORT=5433 WPGO_SITE_URL=http://localhost:9000 make docker-up
First build slow or module download fails
Make sure Docker has network access; later builds are cached.
Login works but every admin action says the nonce is invalid
Instances behind the load balancer have different WPGO_SECRETs. Set the same value everywhere.
http:// links behind a TLS proxy
The proxy must send X-Forwarded-Proto: https and WPGO_SITE_URL must be the https:// address.
Plugin: "signature could not be verified"
Unsigned or untrusted key. Add the author's public key to WPGO_PLUGIN_KEYS or plugin_trusted_keys; for local development set plugin_allow_unsigned.
Plugin "disabled after 5 consecutive failures"
Read its log lines on Plugins (last five shown); deactivate and activate to reset.
Scheduled posts do not publish / e-mails not sent
The scheduler runs inside wpgo serve; check the server log and Tools › Site Health for failed jobs.
"Template error" after editing a theme file
The editor rolls back broken saves; if you edited files on disk under WPGO_THEMES_DIR, fix or delete the file to fall back to the embedded copy.
make prod-up: "Create docker/.env first" / "set WPGO_DB_PASSWORD"
cp docker/.env.example docker/.env and fill in WPGO_DB_PASSWORD and WPGO_SITE_URL.
Dashboard › Updates never offers a new version
A development build does not talk to the Hub; run the production build (make prod-up).
Where are the logs?
Standard output: docker compose logs -f wpgo, make prod-logs, or your service manager's journal. Every request is logged with status and duration.
Start from scratch
Destructive This deletes every volume: the database, uploads, plugins, edited themes, backups and the updated binary.
docker compose -f docker/compose.yaml down -v
make docker-up
Pursae has a built-in Model Context Protocol server. A connected AI client (Claude, Cursor and others) can write and publish content, upload media, build menus, edit theme files, switch themes, toggle plugins, purge the cache and change the built-in plugins' settings — all through the REST API with the permissions of one credential.
Sign-in: OAuth 2.1 (consent screen in the browser) or HTTP Basic with a user name and an Application Password. Every tool runs as a REST request, so capabilities and scopes apply exactly as for direct REST calls.
stdio:wpgo mcp bridges clients that start a local command; the site can be local or remote.
Resources: the developer docs (pursae-docs://developer/…), so the agent can read how themes and plugins work before changing them.
1. Sign in
OAuth (no password to copy): point the client at the endpoint. It discovers the authorization server from the 401, registers itself and opens the site's Authorize Application screen: check the name, tick scopes (default Content and Media; everything the user can do needs the explicit Full access box) and approve. Revoke under Users › Profile › Connected applications.
claude mcp add --transport http pursae https://example.com/wp-json/pursae/v1/mcp
# then run /mcp inside Claude Code and choose "Authenticate"
Application Password (for clients without OAuth, scripts and wpgo mcp): Users › Profile › Application Passwords — name it, tick the scopes it needs (or none for all your permissions) and copy it (shown once). Use an Editor for content work, an Administrator for themes, plugins and settings. Revoke on the same screen to cut the agent off at once.
Job
Recommended scopes
Writing and publishing
content, media, seo
Design work
themes, media, cache
Running the whole site
none (full access)
2. Connect a client
Use HTTPS for remote sites: Basic auth sends the password with every request.
The header is Basic + base64 of user:password. Any other MCP client works the same way.
wpgo mcp flags
Flag
Environment
Meaning
--url
PURSAE_URL
site address
--user
PURSAE_USER
login or e-mail
--password
PURSAE_APP_PASSWORD
the Application Password; prefer the env var (a flag shows in ps, and the bridge warns)
—
PURSAE_CONFIG_DIR
overrides where OAuth tokens are stored
wpgo mcp login --url https://example.com [--scope "content media"] [--no-browser] runs OAuth 2.1 with PKCE (loopback redirect on 127.0.0.1) and stores the token pair in <user config dir>/pursae/mcp-<host>.json (mode 0600, a plain file, not the OS keychain). Afterwards wpgo mcp --url https://example.com needs no password: it sends the Bearer token and refreshes once on 401. The bridge refuses plain http:// except localhost, 127.0.0.1 and ::1; stdout carries only protocol messages, errors go to stderr.
Sessions and streaming
initialize returns an Mcp-Session-Id; unknown or ended ids get 404 (initialize again). Without the header the server is stateless. Sessions are per user, capped at 10 per user and expire after an hour without use.
POST answers application/json, or a one-event text/event-stream when Accept prefers it.
GET with Accept: text/event-stream opens the server→client stream: notifications and a : keep-alive every 25 seconds; the last 64 events are kept for Last-Event-ID reconnects; one stream per session; it ends when the token or password is revoked or expires.
DELETE ends the session (204).
Tools
Area
Tools
Posts and pages
list_posts, get_post, create_post, update_post, delete_post and the same for pages
Media
list_media, upload_media (base64 or a public URL), update_media, delete_media
site_info, rest_request (any REST route, same permissions)
tools/list shows only tools the credential can use (scopes, capabilities, active plugins); notifications/tools/list_changed is sent when a plugin is toggled. Refused calls return the REST error code (rest_forbidden, rest_scope_forbidden, …). Annotations follow the MCP spec: readOnlyHint on reading tools (and seo_analyze), destructiveHint on everything that is not purely additive.
Safety
Every write is logged (time, user, OAuth app or Application Password name, tool, route, status; no bodies) for 90 days — read it with ai_activity, GET /pursae/v1/mcp/activity or Tools › AI Access (/wp-admin/ai-access, manage_options), which also shows the endpoint, ready client configs and every OAuth grant with Revoke.
An hourly job drops expired OAuth grants and codes, orphaned clients and old activity.
Tool answers over 400 KB are cut and carry no structuredContent.
Pursae ships the plugins a WordPress site usually buys or installs separately inside its own binary. Each one is listed under Plugins, is off on a fresh install, adds nothing (no menu, routes, output) while off, and keeps its data when deactivated.
A clone of WooCommerce with its premium extensions built in as modules: products, cart, checkout, tax, shipping, coupons, orders, payment gateways, e-mails and both REST APIs. Internal name goocommerce, switch native_goocommerce. While off, its screens answer 404 and its REST routes rest_no_route.
Data
Products are posts of type product / product_variation plus a row in goo_products.
HPOS-like orders: goo_orders, goo_order_items, goo_order_notes; plus attributes, coupons, tax rates, shipping zones/methods, sessions, download permissions, API keys and webhooks tables.
Modules (Pursae Commerce › Extensions, all off by default)
Subscriptions:wc/v3/subscriptions (CRUD, batch, notes, orders), webhook topics, customer address/payment-method changes and resubscribe, manual subscriptions and "Process renewal" in the admin.
Gift Cards: disabled on cancel/refund, expiry reminder a week ahead, five colour designs (optional image), PDF card and signed print-at-home page; Store API and wc/v3/gift-cards.
Product Add-Ons: nonce-protected file uploads (20 per address per 10 minutes, orphans deleted after 24 h), conditional fields, date limits.
Bookings: signed .ics downloads and a private ICS feed, blocks past midnight, automatic refund of cancelled paid bookings where the gateway supports it, wc-bookings/v1 REST.
Memberships: lifecycle tied to orders and subscriptions, welcome / ending soon / ended e-mails, drip schedule for restricted content.
Storefront, blocks and APIs
Store pages render inside the active theme like WooCommerce's theme-compatibility mode, keeping WooCommerce's templates, classes and field names. Themes declare "supports": { "woocommerce": true } in theme.json.
Shortcodes are named goocommerce_* and answer to their woocommerce_* alias. Server-rendered blocks: products, featured product, product categories, mini cart, product search.
wc/store/v1 (Store API) and wc/v3 (management API) follow WooCommerce's JSON shapes, parameters, error codes and headers; wc-analytics serves revenue, orders and product reports.
Webhooks for coupon/customer/order/product events, module topics and action.<hook>; failed deliveries retried after 10 s and 1 min, disabled after 5 consecutive failures; delivery log with "Send test delivery".
Analytics reports (Overview, Products, Revenue, Orders, Variations, Categories, Coupons, Taxes, Downloads, Stock, Customers) with uncapped CSV; weekly store summary e-mail.
CSV product import/export with WooCommerce column names and Meta: <key> columns; batch import of 50 rows; CSV export of orders, coupons, subscriptions and customers.
Payments and concurrency
Gateways: direct bank transfer (BACS), check, cash on delivery, Stripe (Stripe-hosted Checkout, signed webhook, API refunds, saved cards, off-session renewals) and a Test payments gateway.
Order status changes are serialized per order; stock and coupon uses are taken with conditional updates, so a payment that loses the last unit puts the order on hold instead of overselling.
Limits iyzico is not built yet. BACS, check, cash on delivery and Bookings do not refund automatically. Geolocation uses CDN/proxy country headers (no GeoIP database). Cart and Checkout have no editor blocks yet; use the [goocommerce_cart] and [goocommerce_checkout] shortcodes. E-mails and module front-end texts are still English. Checkout validates stock but does not reserve it.
The union of Yoast SEO Premium and Rank Math Pro in one plugin with a WordPress-style admin. Slug seo-go, switch native_seogo, settings in one JSON option seogo_options. While off its routes answer 404, nothing is added to <head>, and core's wp-sitemap.xml and robots.txt are served.
Compatibility with imported sites
Writes Rank Math's %var% syntax and accepts Yoast's %%var%%, with both plugins' variable names.
Stores _seogo_* meta but every read falls back to Yoast's _yoast_wpseo_*, then Rank Math's rank_math_* keys, so an imported WordPress site keeps its SEO data without conversion. Tools › Import and the WXR importer also copy it.
Reads Yoast and Rank Math FAQ / How-to blocks and breadcrumb shortcodes; serves both plugins' REST head endpoints (yoast/v1/get_head, rankmath/v1/getHead) plus seogo/v1/get_head.
Editor and analysis
One SEO box: a meta box in the classic editor, a sidebar plus a document panel in Pursae Editor, an SEO tab in Pursae Web Builder's Page tools.
Focus keyphrase plus related keyphrases, mobile/desktop snippet preview, title and description with variables, canonical, all robots directives, breadcrumb title, primary category, Open Graph / X previews.
SEO analysis: all of Yoast's assessments plus Rank Math's extra tests; Yoast-style traffic lights, Rank Math's 100-point score shown alongside. Readability: Yoast's 7 assessments with Flesch and reading time as insights; Turkish gets transition words and Turkish-aware lowercasing.
Cornerstone (pillar) content, internal linking suggestions, link counter with orphaned content, bulk editor (50 per page) and SEO / Readability columns on post lists.
Schema tab: page type, article type, Product and custom JSON-LD.
Site-wide output
Search appearance templates per content type, taxonomy and archive (including Commerce products and Custom Fields post types), the same 14 separators, Knowledge Graph (organization or person), social settings, webmaster verification (Google, Bing, Baidu, Yandex, Pinterest, Naver), RSS before/after text, robots.txt editor, settings import/export as JSON.
Schema graph with Yoast's @id scheme, FAQ and How-to blocks, Product, LocalBusiness (Local SEO module) and custom JSON-LD. Breadcrumbs as a block and shortcodes with BreadcrumbList schema.
Sitemaps on Yoast's URL scheme (/sitemap_index.xml), 1000 URLs per file (configurable), image entries, hreflang alternates with Pursae Multi Language; /sitemap.xml and /wp-sitemap*.xml redirect 301. News sitemap (last 48 hours) and video sitemap (YouTube/Vimeo embeds and self-hosted video).
IndexNow with key file, automatic and manual submission and retries.
Redirections, 404s and Search Console
Redirects 301, 302, 307, 410, 451 with exact, contains, starts with, ends with and regex matching; categories, hit counters, CSV import/export, automatic redirects on post and term slug changes.
404 monitor with hits, referer, user agent, ignore list and a "Redirect" button; optional fallback URL for every 404.
Search Console report with the site owner's own Google OAuth client (read-only scope): clicks, impressions, CTR, position, top 10 queries and pages for the last 28 days. Secret and tokens stored encrypted.
Modules can be switched individually; a role manager grants seogo_* capabilities per role. A five-step setup wizard opens on first activation.
Left out Rank Math Analytics beyond Search Console, Content AI and Yoast AI, SEMrush/Wincher, Yoast word forms and synonyms, inclusive language, the visual schema builder and templates, yoast_head fields on wp/v2, live analysis on the term screen, and the .htaccess editor (not applicable: Pursae serves every request itself).
A native clone of Advanced Custom Fields PRO 6.x. Internal name acfgo, switch native_acfgo. Field groups are acf-field-group posts whose content is ACF's export JSON, and values are stored exactly like ACF (name → value, _name → field key, repeater rows as name_{i}_{sub}, options as options_{name}), so ACF data imported with WXR reads back unchanged.
Field groups and field types
Field Groups list with views, row and bulk actions, search; drag-and-drop editor; field settings tabs (General, Validation, Presentation, Conditional Logic); ACF-style group_… / field_… keys.
Local JSON in <data>/acf-json and the active theme package, with "Sync available"; registration from Go code (acfgoRegisterLocalGroup).
Every ACF field type, including the PRO ones: text, text area, number, range, email, URL, password, image, file, WYSIWYG, oEmbed, gallery, select, checkbox, radio, button group, true/false, link, post object, page link, relationship, taxonomy, user, Google Map, date / date-time / time pickers, color picker, message, accordion, tab, group, Repeater (with pagination), Flexible Content, Clone, Icon Picker.
Bidirectional Relationship, Post Object and User fields mirror their value into the target field of related objects.
Where fields appear
Location rules (OR groups of AND rules): post type, template, status, format, category, taxonomy, page type/parent, current user and role, user form, taxonomy term, attachment, comment, menu and menu item, ACF Blocks, Options Page.
Presentation settings (style, position, label and instruction placement, hide on screen); boxes in both the classic editor and Pursae Editor.
Conditional logic live in the editor and on save; validation via ajax before submit and on the server, including REST writes.
Options pages created in the UI; Post Types and Taxonomies UI that registers types with admin menus, front-end routes, archives and /wp/v2/<rest_base> REST routes.
ACF Blocks from acf-blocks/<name>/block.json with a Go html/template render template.
Developer access
REST acf object on posts, pages, users, terms, comments and media (read and write, validated; ?acf_format=standard for formatted values).
Theme template functions get_field, the_field, get_field_object, get_fields, have_rows, get_sub_field and friends; Go helpers acfGetField, acfUpdateField; Wasm plugins get an acf object from get_post.
Tools: export/import of field groups, post types, taxonomies and options pages as JSON.
Differences No PHP, so no acf/* PHP filters, acf_form() or Generate PHP. Widget locations, field value revisions, moving a field between groups and CPT UI import are left out. Some pickers are native controls (browser date inputs, URL inputs instead of wpLink, address and coordinates instead of the Google Maps picker); WYSIWYG is TinyMCE only where the classic editor loads.
A 1:1 functional clone of Polylang Pro (3.9), plus TranslatePress-style visual translation, automatic string capture, per-language media texts and machine translation. Internal name golylang, option golylang with Polylang's keys. While off there are no menus, the pll/v1 namespace is hidden and /fr/ URLs are 404.
Languages and URLs
Languages screen with about 100 predefined locales, RTL, flag (two-letter code shown as an emoji flag), order, default language; Activate/Deactivate per language.
Language from directory, subdomain, separate domains or content (?lang=); hidden default language; browser language detection; translated slugs and shared slugs.
Every link carries the language; queries, feeds, search and sitemaps are narrowed to it; <html lang>, dir="rtl", hreflang and per-language sitemaps.
Content and strings
Language columns on post, page, term and media lists; Languages box in the classic editor, Pursae Editor and Pursae Web Builder; add-translation flow that copies terms, featured image, custom fields and more.
Synchronization of taxonomies, custom fields, comment/ping status, sticky, date, format, parent, template, order and featured image (each translation keeps its own Pursae SEO texts).
Duplicate content, bulk translate, Untranslated / Outdated views, XLIFF 1.2 export/import of content, PO export/import of strings.
Strings screen covering site title, tagline, date/time formats, URL slugs, theme gettext and Customizer text, Wasm plugin strings and text recorded on pages.
One Media Library item per upload with alt text, title, caption and description translated per language.
Menus per language, a language switcher menu item, block and pll_the_languages template function.
Visual and machine translation
Visual translation screen: the page in an iframe with a string panel; click any text to translate it with live preview. Works with every theme type, needs at least two languages; not in subdomain/domain URL modes.
Machine translation (off by default) with DeepL, Google Cloud Translation or an OpenAI-compatible API. The key is sealed with AES-GCM and never shown again; text is sent only when a manager asks; requests go from the server to public addresses only.
Per-language capabilities manage_translations and translate_{lang} open the translation screens for translators without site admin rights.
Left out.mo language pack downloads and locale fallback, the setup wizard (the Languages screen does the same), synchronized posts, legacy widgets and per-widget languages, Quick/Bulk Edit language select, the WPML API and WP-CLI wp pll.
A native clone of Contact Form 7 (studied at 6.2.3) with Flamingo-style entry storage and the Really Simple CAPTCHA built in. Internal name gontact-form, switch native_gontact_form. Same post type (wpcf7_contact_form), meta keys, default templates, admin screens, form markup and JavaScript events as CF7, so CF7 forms, themes and scripts work unchanged.
Forms and embedding
Contact menu with list, add and edit screens; Form, Mail, Mail (2), Messages and Additional Settings tabs; tag generator; configuration validator.
[contact-form-7 id="…"] and [contact-form …] shortcodes (hash ids, numeric ids, title lookup) and the contact-form-7/contact-form-selector block.
Conditional groups ([group] with equals, contains, greater than… rules), checked again on the server.
Submission and mail
CF7's REST feedback, schema and refill endpoints with the same statuses and response shape; a non-JS fallback with inline errors.
All mail-tags and special tags; HTML mail; attachments held in memory (25 MiB per submission) and never written to disk; delivery status per entry.
Entries stored in gontact_entries: list, search, view, delete, formula-safe CSV export, retention in days; do_not_store: true per form.
Outgoing webhooks (webhook_url) signed with X-Pursae-Signature; Wasm hooks wpcf7_validate, wpcf7_before_send_mail, wpcf7_spam, wpcf7_mail_sent.
Spam protection
Honeypot and HMAC-signed minimum fill time (3 s) on by default; rate limit of 30 submissions and 30 refills per minute per address; disallowed keys; quiz.
reCAPTCHA v3 and Cloudflare Turnstile (reCAPTCHA loads only after consent when Pursae Cookie is on).
Built-in image CAPTCHA drawn in pure Go: 4 characters without look-alikes, single use, one-hour expiry, answer stored only as an HMAC, works behind the page cache.
Not ported Akismet, Constant Contact, Brevo, Stripe, reflection / listo, an audio CAPTCHA (the [quiz] tag is the accessible alternative) and UI translations (the UI is English).
A native clone of WP Mail SMTP (Lite and Pro). Internal name wpgo-mail-smtp, switch native_wp_mail_smtp, settings in one JSON option with upstream's key names. While inactive, wp_mail() keeps using the WPGO_SMTP_* environment variables (or .eml files on development sites). Pro features are included without a licence.
Mailers
Other SMTP (native client: SSL, STARTTLS, Auto TLS, AUTH PLAIN/LOGIN), SendLayer, SMTP.com, Brevo, Mailgun, SendGrid, Postmark, SparkPost, Amazon SES, Microsoft 365 / Outlook, Google / Gmail, Zoho Mail, Elastic Email, Mailjet, MailerSend, Resend, SMTP2GO, Mandrill.
OAuth mailers use the site owner's own app; tokens refresh automatically. All mailers deliver Cc, Bcc and attachments.
Secrets (passwords, API keys, OAuth tokens) are AES-256-GCM encrypted and never printed back into forms.
Routing and reliability
Setup wizard with a test e-mail and a domain checker (SPF, DKIM, DMARC, MX).
Force From e-mail / name, Return Path, backup connection, additional connections and Smart Routing by subject, message, from, to, reply-to or initiator.
Rate limits per minute, hour, day, week and month; over-limit mail is re-queued.
Log, reports and alerts
Email Log with content, status, resend (also to other recipients), export as CSV or EML (zip), retention, optional signed open/click tracking that ignores DNT/GPC visits.
Reports with daily sent/failed chart, open, click and bounce rates, weekly summary e-mail; dashboard widget and Site Health row.
Alerts by e-mail, Slack, Discord, Microsoft Teams, Twilio SMS or a custom webhook, with a failure threshold; delivery, bounce and complaint status from Postmark, SendGrid, Mailgun and Amazon SES (SNS signature verified).
Email Controls to switch off individual core and Commerce notification types; Do Not Send; debug events.
Every upstream WPMS_* constant is read from the environment (with WPMS_ON=true).
Left out One-click Gmail/Microsoft setup (needs WPForms' relay and a licence), XLSX export, storing attachment bytes, push and WhatsApp alerts, usage tracking, importing other SMTP plugins, multisite and WP-CLI.
A login-security plugin at the level of Wordfence Login Security, Two Factor, WPS Hide Login and the login, user and hardening parts of Solid Security. Internal name adminsecgo, switch native_adminsecgo. Deactivating keeps users' factors, settings and the log, and brings /wp-login back.
Second factors
MFA: e-mailed 6-digit codes (10-minute expiry, single use, 60 s resend cooldown, 5 attempts). Needs working e-mail (Pursae SMTP or WPGO_SMTP_HOST).
2FA: authenticator app (TOTP, RFC 6238) with replay protection and a QR code generated server-side in pure Go; requires MFA first.
10 backup codes shown once; "remember this device" (default 30 days); TOTP secrets sealed with AES-256-GCM, codes stored only as HMAC hashes.
Per-role requirement (MFA or 2FA) with a grace period (default 7 days); admin reset and wpgo adminsec reset-user.
Login protection
Custom login URL; /wp-login and /wp-admin answer 404 (or redirect) for visitors; escape hatch WPGO_ADMINSEC_DISABLE_HIDE_LOGIN=1.
Lockouts per IP (default 5 failures in 15 minutes → 20 minutes) and per username, progressive lockouts (default 24 h after 4), IP/CIDR allow and block lists.
Generic error messages, user enumeration blocking, optional Turnstile or reCAPTCHA v3 on login forms, reset-mail limits.
Password policy per role with a strength score, the 10,000 most common passwords refused, optional Have I Been Pwned check (k-anonymity), forced password change.
Active sessions list with per-session logout, idle timeout.
Firewall The per-IP rate limit (900 requests a minute by default) and basic WAF rules on the URL and User-Agent are part of the core and on by default, also without this plugin; Settings › Firewall tunes them and WPGO_FIREWALL=off disables them.
Not included A malware signature scanner, passkeys (WebAuthn), password expiry and XML-RPC (Pursae has no XML-RPC endpoint).
Cookie consent and cookie management on par with Complianz, CookieYes and Cookie Notice & Compliance, built for GDPR / ePrivacy, Turkey's KVKK, CCPA/CPRA and Google Consent Mode v2. Internal name gooike, switch native_gooike.
Banner and preferences
First layer with equally prominent Reject all and Accept all buttons plus Customize; a preferences modal with one switch per category, declared cookies, the visitor's consent ID and date.
Categories Necessary, Preferences, Statistics, Marketing plus custom ones; withdrawal deletes the category's cookies; re-prompt on policy version change or expiry (12 months by default, 1–24).
14 banner themes (bar, top bar, boxes, modal, pill, glass, dark, brand, card, toast, consent wall, split, side panel) with live preview and custom CSS.
26 editable visitor texts with ready-made sets for 8 languages; automatic language with Pursae Multi Language; keyboard-accessible with focus trap and reduced-motion support.
Blocking and Consent Mode
Script manager (head, body open, footer) that prints non-necessary scripts inert until consent; known services from an ID: GA4, Tag Manager, Meta Pixel, Hotjar, Clarity, LinkedIn, TikTok, Google Ads, Pinterest, Microsoft UET, Matomo, Intercom, HubSpot, Stripe.js.
Automatic blocking of known tracking scripts from content, themes and other plugins; embeds of YouTube, Vimeo, Google Maps, Spotify, SoundCloud, Instagram, X, Facebook, TikTok, Dailymotion and Twitch held behind a "Load content" placeholder.
Google Consent Mode v2 script printed first in <head>; per-category mapping; GPC and DNT signals honoured.
Services' hosts are added to the Content-Security-Policy automatically.
Declaration, scanner and log
Cookie declaration with [gooike_cookie_table]; server-side scanner (plus a weekly scan job) that marks cookies as declared or new.
Consent log with anonymized IP (IPv4 /24, IPv6 /48, or hashed, or none), user-agent HMAC, filters, history per consent ID, formula-safe CSV export and retention (12 months by default).
Regulation modes GDPR, KVKK (with information notice) and CCPA (opt-out, "Do Not Sell or Share"); optional geo targeting from CDN country headers; cookie policy page generator.
Identical HTML for every visitor, so pages stay cacheable by Pursae Cache.
No IAB TCF v2.2 Pursae Cookie writes no TC string, so it is not suitable for sites serving AdSense / Ad Manager ads to EU/EEA/UK visitors; use a Google-certified CMP there. Headless-browser crawling is also left out (JavaScript cookies come from the known-services list).
Ad and analytics tracking in the class of PixelYourSite Pro, Pixel Manager for WooCommerce and GTM4WP, written from scratch. Internal name pixelgo, switch native_pixelgo, version 0.1.
Platforms
Platform
Browser
Server-side
Meta Pixel
Yes
Conversions API
Google Analytics 4
Yes
Measurement Protocol, Purchase (and refund) only
Google Ads
Conversions, remarketing, enhanced conversions
No
TikTok
Yes
Events API
Pinterest
Yes
Conversions API
Microsoft Advertising (UET)
Yes
No
Google Tag Manager
Container and GA4 e-commerce dataLayer
No
Events
One event model for every platform: page view, search, scroll, time on page, tel/mailto clicks, outbound links, downloads, forms, comments, registrations, HTML5, YouTube and Vimeo video.
Store events from Pursae Commerce: ViewContent, ViewCategory, AddToCart, RemoveFromCart, ViewCart, InitiateCheckout, AddPaymentInfo, Purchase (once per order and browser).
Custom events by page visit, CSS selector click, scroll, time or form submit; advanced matching with hashed customer data (opt-in); UTM and click-id attribution cookie (90 days).
Consent and delivery
With Pursae Cookie and "Require consent" (default) tags stay inert until consent; without Pursae Cookie no tag is printed.
Browser and server events share one event id for deduplication; Purchase is also sent on payment_complete, so off-site payments count. Retries after 2 s, 15 s and 90 s, an hourly sweep for unaccepted Purchases and a delivery log with Retry.
Product catalog feed (RSS 2.0 for Google Merchant / Meta) at a token URL, streamed in pages of 500, optional per-variation items.
Role exclusions, debug mode, window.pixelgo.track(), settings export/import, test events per platform.
Not in 0.1 Google Ads and Microsoft Advertising server-side events, Snapchat, Reddit and X tags, subscription/booking-specific events, single-page-app page-view deduplication.
Privacy-friendly site statistics and real-user Core Web Vitals, in the class of Plausible, Jetpack Stats and the MonsterInsights dashboard. Switch native_pursae_analytics, version 0.1.
Privacy
No cookies, no browser storage, no fingerprinting script; no IP address stored. A visitor is a SHA-256 of a daily random salt, IP, user agent and host; the salt is deleted the next day.
Signed-in users, Do Not Track / Global Privacy Control and excluded IP ranges are settings. No consent banner is needed.
Collection
A 2.3 KB script (1.2 KB gzipped), identical for every visitor so it works behind the page cache.
Page views (path, UTM source/medium/campaign, referrer host, viewport), events (outbound, download, form, 404) and end-of-view data (visible time, LCP, INP, CLS, FCP, TTFB).
Device, browser, OS, source (known services such as Google, Bing, ChatGPT, Perplexity), country from CDN/proxy headers. Bots, prefetches, admin paths and over 300 requests a minute per address are dropped.
Unique visitors, visits, page views, views per visit, bounce rate, visit duration with change against the previous period; current visitors; SVG chart.
Core Web Vitals at p75 with Google's thresholds and the slowest-LCP pages. Retention 30–3650 days (default 395). JSON API GET /pursae/v1/analytics.
Not in 0.1 Multi-day uniques are the sum of daily uniques (by design). No filters/drill-down, custom theme events, revenue goals, CSV export, public dashboard, e-mail reports or GeoIP database.
Object storage, CDN delivery and on-the-fly images: the ground of WP Offload Media, an imgix / Cloudflare Images style image CDN and CDN Enabler, with purging of Pursae Cache and several CDNs. Internal name gocdn, switch native_gocdn.
Storage and offload
Amazon S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, MinIO or any S3 API, through an own SigV4 client (no AWS SDK) with a step-by-step connection test.
Multipart uploads (from 16 MB by default), server-side encryption (SSE-S3, SSE-KMS, SSE-C), storage class, object versioning; secrets sealed with AES-GCM; configuration via WPGO_CDN_SETTINGS.
New uploads and all sizes copied in the background; optional removal of local files; removed files answered by redirect, presigned URL or proxy; resumable bulk offload, download-back, remove and "move to the current bucket" jobs.
Deactivation never breaks URLs: files that exist only in the bucket keep being served.
Remote storage browser and a "Remote storage" tab in the media picker (import as copy or link).
Images and assets
Image service /cdn-img/<path>?w=&h=&fit=&q=&fm=: JPEG, PNG, GIF, WebP and AVIF (off by default), animated GIFs, fm=auto negotiation, signed URLs, abuse limits, disk or bucket variant cache. No cgo.
Asset CDN for theme, plugin and core files on the front end; CDN origins added to the CSP.
URL rewriting on the front end, feeds, sitemaps and REST; editors keep local URLs.
Purge and private files
Purge Pursae Cache and one or more of Cloudflare, Amazon CloudFront, BunnyCDN, KeyCDN and Fastly, concurrently; automatic purge on changes.
Private files under uploads/private/, delivered only through expiring signed links; Commerce downloadable files use them.
Limits AVIF sources are not accepted, no surrogate-key / tag purges, SSE-C objects have no public or presigned URLs, presigned URLs are not written into cached page HTML.
Backs a whole site up into one .zip and restores it on the same or another Pursae site, like All-in-One WP Migration, without an SQL dump: rows are exported as JSON lines straight from PostgreSQL, so pg_dump / psql are not needed. Slug backup-manager, menu for administrators.
What is backed up
Selectable parts: posts and taxonomy, media library (with uploads), users and roles, settings, themes, plugins, page builder data, each built-in plugin's tables, other plugin data.
Users can be limited to all users, chosen roles or picked users; dependent tables (ON DELETE CASCADE) follow automatically.
Archive: manifest.json, database/<table>.jsonl and files, with a SHA-256 per entry.
Restore
Optional safety snapshot first; the database restore runs in one transaction and rolls back on any failure; files are staged and moved only after the database succeeds.
Optional rewrite of the old site URL (also JSON-escaped) to the new address; archives from a newer schema are refused.
Schedule and storage
Automatic local backups, keeping 1–100 scheduled archives (default 7); failures shown under Last scheduled backup.
Archives in WPGO_BACKUPS_DIR (default <data>/backups, outside the public uploads) with mode 0600; uploads up to 16 GB streamed to disk; one job at a time.
Note A backup holds password hashes and site secrets. Restoring users logs everyone out; restoring plugins needs a restart. Media that exists only in the Pursae CDN bucket is not included. Not yet built: archive encryption, remote storage (S3, FTP, cloud drives), restore on a site not yet installed, merge restore.
A clone of Maintenance by WebFactory (v4.32) with the parts of Maintenance PRO that suit a single-site install, plus a SeedProd-style Coming Soon mode and scheduled window. Switch native_maintenance, settings in maintenance_settings. The gate runs before the page cache, so a closed site never serves a cached page.
Modes and access
Maintenance mode (503 + Retry-After) or Coming Soon mode (200); no-cache headers always, noindex by default.
Admin bar indicator with toggle; scheduled start, countdown with auto-disable.
Bypass: logged-in users (with a role filter), crawlers, IP and CIDR whitelist, URL rules with prefixes, secret link, site password (bcrypt, rate-limited), login form on the page.
Anonymous REST gets a JSON 503 (403 in Coming Soon); feeds and sitemaps gated by default; ?maintenance-preview.
Page design
7 built-in themes (Default, Minimal, Card, Split, Neon, Sunrise, Editorial); logo, background image/colour/gradient, blur, overlay, 7 system font stacks, custom CSS. Nothing is loaded from other servers.
Or a published Pursae Web Builder template as the page.
Modules: countdown, progress bar, subscribe form (double opt-in, consent note, CSV export, notify subscribers), social icons, custom HTML.
SEO title, description, favicon, og:image, GA4 (held by Pursae Cookie when active); texts translated with Pursae Multi Language.
Left out YouTube video backgrounds, maps and videos (third-party frames), a preloader, reCAPTCHA, mailing-list integrations, drag-and-drop ordering (use a Web Builder template), Force SSL and white-label.
Turns the site into a headless CMS: a Content-Type Builder, a Content Manager and a delivery API for Next.js, Nuxt, Astro or mobile apps, following the conventions of popular open-source headless CMSs (collection and single types, components, dynamic zones, filters[field][$op], populate, documentId). Internal name headlessgo, switch native_headlessgo. No single WordPress plugin matches it.
Modelling and editing
Field types: text, rich text (blocks or Markdown), numbers, boolean, dates and times, email, password (argon2id), enumeration, media, relation, JSON, UID, component, dynamic zone.
Relations of every cardinality, to content types, WordPress posts, pages, users, any public post type or taxonomy; bidirectional relations kept in step.
Schema changes migrate stored data (renames, removals, type conversions); NDJSON entry export/import and JSON schema export/import.
Content Manager with draft & publish, i18n through Pursae Multi Language, bulk actions, content history with restore, scheduled publishing, edit locks and a review-before-publishing flow.
Delivery API
REST at /wp-json/headlessgo/v1: CRUD, publish, schedule, media upload, filters, full-text _q, sorting through relations, pagination, populate, fields, locale and status; openapi.json and TypeScript types generated from the model.
GraphQL with mutations, fragments, directives, introspection and spec validation; subscriptions over WebSocket (graphql-transport-ws) and server-sent events.
Public permission matrix (nothing public by default), API tokens (read-only, full, custom; SHA-256 only), optional signed-in users with JWT, CORS allow-list, rate limit, ETag/304 and CDN cache tags.
Signed webhooks with a durable retry queue; preview URLs with short-lived preview tokens; headless mode that stops the front end from rendering.
Limits Subscriptions see only the writes of their own process; a read may run at most 1000 queries and load 20000 related entries; REST and GraphQL are not locked and cannot review; signed-in users have no refresh tokens; admin strings are translated only into Turkish.
Discussion boards in the class of bbPress, written from scratch (0.2.5). Switch native_pursae_forum. Every view renders as a page of the active theme; four library themes ship with forum demo content: Campfire, Devboard, Guild Hall and Study Circle.
Forums and posting
Categories holding forums, pinned and closed topics, posting without JavaScript, basic HTML sanitized twice, PostgreSQL full-text search, profiles and a member list.
Topic tags, views, sort tabs (latest, popular, unanswered, solved), likes, accepted answers, who is online, similar topics, drafts and preview, follow by e-mail, post reports.
Shortcodes [pursae_forum] and theme functions such as forum_user_menu; public read-only forum/v1 REST.
Members
E-mail sign-up with a 48-hour confirmation link, login with Pursae Security's rules, "Continue with Google" (OAuth 2.0 with PKCE, OpenID Connect).
Profile photos (up to 2 MB, cropped to 512 px), initials avatars, no Gravatar.
Points, six default levels (Newcomer to Legend, up to 30) and rule-based or hand-awarded badges (up to 100).
Spam guards: honeypot, signed time token, captcha, sign-up and posting rate limits, flood interval.
Moderation and integration
Front-end moderator bar, an admin queue, first-post moderation, blocking, an edit window (30 minutes by default).
Language prefixes and hreflang with Pursae Multi Language; cacheable visitor pages tagged forum.
Not in 0.2.5 Per-language forums, guest posting, private forums, reply threading, topic merge/split, the weekly digest mail, forum RSS and sitemap entries, Web Builder widgets and bbPress importers.
A section-based visual page builder that ships inside the binary. Visitors never load React: a published page is a static HTML/CSS snapshot with a small optional script.
Pursae Web Builder is a built-in plugin (slug golementor, option native_golementor). The editor is a React app built from github.com/pursae/Builder. With the Theme Builder it also designs the site's header, footer and content templates, shown by the bundled Hello Pursae theme.
It is off on a fresh install. Plugins › Pursae Web Builder › Activate turns it on and switches the site to Hello Pursae; the previous theme is remembered (web_builder_previous_theme) and a notice offers Switch back.
While the plugin is off there are no menu entries, "Edit with" links, routes, assets or front-end output; built pages show their readable fallback inside the theme.
Web Builder › Settings (manage_options) picks the post types the builder edits (pages and posts by default) and lists pages to Regenerate.
The editor UI is English, with Turkish included (picked from the user's language).
Open a page with Edit with Pursae Web Builder (block editor toolbar, classic editor, row action, or the site toolbar). The URL is /wp-admin/post?post={id}&action=web-builder; it needs edit_post and takes the WordPress post lock.
Build from sections: navigation, hero, banner, features, media, steps, quote, FAQ, call to action, footer, text, image, form, layout and custom, or a saved section from the library. Switch between desktop, tablet and mobile.
Changes autosave every few seconds as your own draft; the live page is untouched.
Publish renders the page in the browser and sends the document plus snapshot; the server validates and sanitizes both. Users who may not publish get Pending Review. A concurrent publish shows a conflict instead of overwriting.
Every publish is also a core revision; the builder keeps the document of each one (newest 50 per page).
Preview (?preview=true) shows the last published snapshot.
Detached pages Editing a built page elsewhere (block or classic editor, Quick Edit, REST) detaches it: the site shows the edited content inside the theme, and the builder offers to publish again (discarding outside edits) or leave the page to the other editor.
Site settings and design tokens
While the builder is on the Customizer is hidden; Site settings in the editor's menu edits title, tagline, logo, site icon, homepage and Additional CSS (edit_theme_options).
Design tokens: five colours (primary, secondary, accent, text, background) and two fonts (heading, body) as --wb-color-* / --wb-font-* on :root. A snapshot using var(--wb-color-primary) follows a change without republishing.
What visitors get
Page CSS is inlined up to 24 KiB (a cached file above that); fonts are local @font-face; images go through the core image filters.
The runtime (runtime.<hash>.js, under 8 KB gzipped) loads only when the page uses menus, FAQ/accordions, tabs, dismissible bars, forms, motion or embeds. Content is readable with JavaScript off.
Forms post to web-builder/v2/forms/{page}/{section} with a honeypot, minimum fill time, per-IP rate limit and the Pursae Contact Form captcha; messages go to the admin e-mail.
Everywhere else (REST content.rendered, Headless, feeds, search, sitemaps, exports) the page is the fallback HTML generated from the document into posts.content.
Popups are templates of type popup: triggers on load, scroll depth, exit intent or click; frequency every view, per session, once, or every N days; up to five per page; state kept in localStorage / sessionStorage (wb-popup:<id>), not a cookie.
Not yet AI (stubbed out; no AI request leaves the site), fold-out drop-down menus, form integrations and payments, global classes and kits, a setup wizard.
Web Builder › Theme Builder (edit_theme_options) lists the site's templates. A template is a builder document designed with dynamic widgets and post loops, filled with real content at request time. Templates show only while Hello Pursae is active; a template is active when published, a draft or disabled template never shows.
Type
Fills
Default condition
Header
top of every page
Entire Site
Footer
bottom of every page
Entire Site
Single Post
main content of posts
All posts
Single Page
main content of pages
All pages
Single
entries of one custom post type
All entries of that type
Front Page
the front page
Front Page
Archive
blog, category, tag, author, date and post type archives
All Archives
Search Results
search results
Search Results
404 Page
the "not found" page
404 Page
Single Product / Product Archive
Pursae Commerce product and shop views (only while Commerce is on)
—
Dynamic widgets
Group
Widgets
Site
Site logo, Site title, Tagline, Menu, Search form, Copyright
Post
Post title, Post content, Post excerpt, Featured image, Post info, Post terms, Post date, Post author, Author box, Post navigation, Comments, and Posts (a loop)
Archive
Archive title, Archive description, Pagination
Search
Search query
The editor draws widgets with real content chosen in Preview as; it never invents sample content. The Posts loop repeats one designed card with a source of Posts of the page (the only one with pagination), Custom query (1–24 posts, order, terms, author, offset, exclude current) or Related posts.
Display conditions
Each rule is Include or Exclude plus a place: Entire Site, Singular (…), Archives (…), 404 Page. Any matching Exclude removes a template; otherwise the most specific rule wins:
a specific item, term or author;
Front Page and 404 Page;
In a term, Child of, By author;
a post type; Posts Page, Date Archives, Search Results, Author Archives, a post type archive, all terms of a taxonomy;
All Singular, All Archives;
Entire Site.
Ties go to the higher Priority (−100 to 100, default 0), then the more recently changed template. A Search Results template beats an Archive template with the same rule on a search page.
How a page is assembled
With Hello Pursae active every page is Header + Main + Footer. Main is the page's own builder design, else the matching main template, else the theme default. A builder page chooses Site templates or This page only (canvas). ?wb_template_preview=<id> forces a template for preview; publishing, disabling, trashing or changing conditions clears Pursae Cache.
The builder's theme library offers market themes as ready-made full-site designs. Open it from Web Builder › Theme Library or the editor's Studio › Items › Components › Browse theme library. One import creates the Theme Builder templates (Header, Footer, Front Page, Single Post, Single Page, Archive, Search Results, 404 Page) with conditions, the theme's demo pages and images, and its menus on the primary and footer locations.
Choice
Result
Replace them
the theme's templates go live; yours are disabled (drafts, never deleted)
Keep both
the theme's templates are saved as drafts; nothing changes on the site (no menus)
Your posts, pages, categories, users and settings are never touched; re-importing is idempotent (post meta _wb_theme, _wb_theme_key). Needs edit_theme_options, plus edit_pages and publish_pages.
Import flow
POST /web-builder/v2/themes/{slug}/import{mode: "replace" | "keep", pages: bool}: images imported, templates and pages created as drafts.
The editor draws and publishes each doc through the ordinary publish route.
POST /web-builder/v2/themes/{slug}/finish: in replace mode other templates of those types are set to draft, menus assigned, cache purged.
Making a library theme importable
Add "web_builder": "web-builder/parts.json" to theme.json and ship the file (format web-builder-theme, version 1):
The contract is the single source of truth for how the React editor talks to the Go server. Its two halves, internal/webbuilder/contract.go and builder/host/contract.ts, must match field for field and change in one commit.
Versions and handshake
Constant
Value
Meaning
APIVersion
2
REST and boot schema (2 = Theme Builder)
RendererVersion
1
static markup + runtime attributes
APIHeader
X-WB-Api
sent by the editor on every web-builder/v2 request
Incompatible payload changes bump APIVersion; only incompatible static-markup changes bump RendererVersion (additive data-wb-* attributes do not).
A missing or different X-WB-Api answers 409wb_api_mismatch; the editor stops autosaving and offers "Reload".
Boot config window.__WEB_BUILDER__ never contains an AI key or secret.
Document model and publish
The page document (doc, JSON) is the source of truth; the snapshot and CSS from the browser are untrusted.
Publish runs in one transaction: API check, edit_post, lock (409 wb_locked), revision check (baseRev, 409 wb_rev_conflict), doc validation (422 wb_invalid_doc), stripping html sections and custom CSS without unfiltered_html, sanitizing, writing fallback HTML to posts.content, upserting the docs row, purging the cache. The response lists what was stripped.
Drift: if sha256(posts.content) != content_hash after an outside save, the page is detached; only a publish with reattach: true clears it.
Storage (migration 0027_web_builder.sql): web_builder_docs, web_builder_drafts, web_builder_revisions, web_builder_library. Templates are posts of type wb_template (migration 0029).
Validation rules (key limits)
Rule
Limit / allowed
Request body
≤ 4 MiB (413 wb_too_large)
Top-level sections / items per section / Item.sub nesting
≤ 200 / ≤ 500 / ≤ 4
Ids
^[A-Za-z0-9_-]{1,64}$, unique per doc
Section kind
nav hero banner features media steps quote faq cta footer text image form layout html custom, and loop
Strings
≤ 64 KiB; html section content ≤ 256 KiB
href
http, https, mailto, tel, #…, relative
Privileged (unfiltered_html only)
html sections, style.css
Snapshot
exactly one root div.wb-page[data-wb-root]; ≤ 2 MiB; on* and non-data-wb-* data attributes dropped; script, style, object, embed… dropped
iframes
YouTube (nocookie), Vimeo embeds, or sandbox="allow-scripts" + srcdoc from unfiltered_html authors
CSS
no @import, expression(, javascript:; @font-face only from /wp-content/uploads/web-builder/fonts/; total ≤ 1 MiB; </style → 422
Runtime and Theme Builder model
Runtime features: menu acc tabs dismiss form motion embed, all as data-wb-* attributes; every hiding rule is scoped to .wb-js and prefers-reduced-motion is honoured.
Condition grammar <mode>/<scope> (e.g. include/general, include/singular/post, exclude/archive/category/12) with scores from 10 (general) to 50 (a specific item, term or author); at most 50 rules per template, 200 bytes each.
Snapshot placeholders (data-wb-slot, data-wb-if, data-wb-loop, data-wb-menu-loc…) are filled by the server on each request, so templates never need republishing when posts, menus or the logo change.
A Pursae theme is a set of Go html/template files plus assets and a manifest. Theme packages carry no code at all: the core prepares every piece of data and the theme only decides how to print it.
A theme is a set of templates and assets, plus a description of the widget areas, menu locations and Customizer options it offers and the styles and scripts it loads. There are two kinds:
compiled into the binary (web/themes/<slug>/ + a theme_<slug>.go)
<data>/themes/<slug>/ (WPGO_THEMES_DIR)
functions.php equivalent
Go code: a *Theme registered at start-up with hooks for wp_head, body classes, template data
theme.json: everything a Go theme registers in code, declared as data
Install
ship with Pursae
Appearance › Themes › Add Theme › Upload, or from the marketplace
Code
yes (Go, reviewed with the core)
none: templates, CSS, JS, images. Not signed; verified by SHA-256
Everything a package can express is also what the bundled Classic theme uses, so web/themes/classic/templates is the reference implementation.
What a theme controls
the markup of every page kind: index, single, page, archive, search, 404 and the parts header, footer, sidebar, comments;
its stylesheets and scripts, editor styles and preloaded fonts;
widget areas and menu locations;
Customizer sections and settings with live preview;
what the block editor knows about it: colour palette, wide alignment, supports;
how Pursae Forum looks: the forum page wrapper, the forum's colour tokens and any forum view.
What the core does for every theme
The core builds the whole page model (document title, wp_head() output, body classes, the loop, pagination, comments, menus, widget areas, the admin bar) and the theme decides how to print it. A theme never queries the database or sanitises input, which is why packages can be code-free and safe to install.
Web Builder pages A page published from Pursae Web Builder is served as a canvas document without the theme's header, footer and stylesheet. Theme Builder templates replace a theme's output only on the bundled Hello Pursae theme; a theme package cannot receive Theme Builder parts.
Keep the hooks{{.Head}} prints wp_head() (feeds, block styles, your enqueued styles, the Customizer's CSS, plugin assets) and {{.Footer}} prints wp_footer(). Without them scripts, the admin bar and plugins do not work.
3. Assets
Put style.css, scripts, fonts and images under assets/ and reference them from theme.json (styles, scripts, preload_fonts, editor_styles). screenshot.png (1200×900) is the Themes screen thumbnail.
4. Zip it
cd starter
zip -r ../starter.zip theme.json templates assets readme.md
The files sit at the zip root (a single top-level folder is also accepted and stripped). Limits: 32 MiB per package, 4 MiB per file, and only these extensions: .json .html .css .js .map .svg .png .jpg .jpeg .gif .webp .avif .ico .woff .woff2 .ttf .otf .md .txt.
5. Upload and activate
Appearance › Themes › Add Theme › Upload Theme, choose starter.zip. The package is validated (theme.json, template syntax, file types), unpacked to <data>/themes/starter/ and listed on the Themes screen. Live Preview shows it without activating; Activate switches the site. A package whose slug matches a bundled theme is rejected.
6. Iterate
Upload again, or edit in place with Appearance › Theme File Editor (the overlay directory is the same <data>/themes/starter/). During development point WPGO_THEMES_DIR at your working copy: the server loads every <dir>/<slug>/theme.json at start-up.
Hello Pursae (hello-pursae) is a bundled Go theme made for Pursae Web Builder: a blank canvas whose header, footer, single, archive, search and 404 views are designed in the builder's Theme Builder. Without templates it is a plain, usable theme: a minimal header, the content and a footer.
hello-pursae, plus wb-site when at least one Theme Builder part renders
When it becomes active
Activating Pursae Web Builder switches the site to Hello Pursae and stores the previous theme in web_builder_previous_theme; deactivating the plugin switches back while the site is still on Hello Pursae (the default theme when the previous one is gone). If the user picked another theme in between, nothing changes. Sites that had the builder on before Hello Pursae existed get a one-time "Switch to Hello Pursae" notice instead of a silent switch.
How templates replace the theme's output
Theme Builder templates are used only while Hello Pursae is the active (or previewed) theme. The check is on the slug, so a theme package or another bundled theme never receives template parts. For each request the core picks templates by their display conditions and hands the finished markup to the theme in .Data.wb:
Field
What
Without it
.Data.wb.Header
the header template, filled
Hello Pursae's header: custom logo or site title, tagline, the primary menu
.Data.wb.Main
the page's own builder design, else the matching Single Post, Single Page, Single, Front Page, Archive, Search Results or 404 template, filled
the theme's default view
.Data.wb.HasMain
Main carries its own <main> landmark
—
.Data.wb.Canvas
a builder page set to canvas: print no header and no footer
—
.Data.wb.Footer
the footer template, filled
the footer menu, copyright and privacy link
{{define "site-header"}}{{$wb := .Data.wb}}{{if and $wb $wb.Canvas}}{{else if and $wb $wb.Header}}<div class="wb-part wb-part-header">{{$wb.Header}}</div>{{else}}<header id="site-header" class="site-header">…</header>{{end}}{{end}}
The page always has exactly one <main> and the skip link's #content target. The core merges the fonts of all parts, prints each part's CSS as <style id="wb-css-<post id>">, adds the builder's base CSS and runtime once, and adds Edit Header / Edit Template / Edit Footer to the admin bar.
Editing Hello Pursae's templates can be changed in the Theme File Editor; keep the .Data.wb branches or the Theme Builder parts no longer show. To change a builder site's look, edit the templates in the builder rather than the theme.
Templates are Go html/template files. Output is escaped by context automatically; values the core has already rendered as HTML (.Content, .Head, menus, widget areas) are template.HTML and print as-is. Only index.html is required.
Request
Templates tried, in order
front page showing a static page
front-page.html, the page's own template, page.html, singular.html, index.html
Package spec The theme package spec also lists single-<format> and singular for posts, category-<slug> and tag-<slug> for term archives. A page whose _wp_page_template is set tries that template first, also on the front page.
Parts (header.html, footer.html, sidebar.html, comments.html, content*.html) are included with {{template "header" .}}. Every file is parsed into one template set, so a {{define "name"}} in any file is callable from any other.
Search forms Write them as <form role="search" method="get" action="{{.SearchAction}}">{{.SearchHidden}}…, not with .HomeURL, so the language of Pursae Multi Language travels with the query.
Functions
Function
Does
safe, safeURL, safeAttr
mark a string as trusted HTML / URL / attribute
kses s
wp_kses_post() for user-written HTML
date t format
format a time in the site's time zone with a WordPress format; "" uses the site's date format
theme.json describes what a Go theme would register in code. Unknown fields are rejected.
Metadata
Field
Required
Rules
slug
yes
^[a-z0-9]+(-[a-z0-9]+)*$, 2–64 characters; the directory name and the identifier (theme mods, widgets and menus are stored per slug). Bundled slugs are reserved
name
yes
shown on the Themes screen
version
yes
semver
description, author, author_url, theme_url
no
Themes screen and marketplace; URLs are http(s)
tags
no
marketplace filters (blog, dark, one-column, …)
requires_core
no
minimum Pursae version (must not be newer than the running one)
register_nav_menus(): id, name. Assigned under Appearance › Menus
page_templates
{"<name>": "<Label>"} for the Page Attributes "Template" select. Name is a handle, not index, page, front-page or singular; templates/<name>.html must exist; label one line, max 80 characters, no markup
Assets
Field
Meaning
styles[]
wp_enqueue_style(): handle, src, deps, media
scripts[]
wp_enqueue_script(): handle, src, deps, in_footer
editor_styles[]
add_editor_style(): loaded into the block editor and TinyMCE
preload_fonts[]
.woff2 files under assets/, preloaded in wp_head on every page
block_styles
true: per-block core styles, inlined; an array of block names also leaves those blocks out; default false (whole block library)
Editor and Customizer
Field
Meaning
palette[]
editor-color-palette: name, slug, color; also printed as --wp--preset--color--<slug>
the tag id: <handle>-css, <handle>-js; pattern ^[a-z0-9]+([_-][a-z0-9]+)*$, unique per list
src
a path in the package (served at /wp-content/themes/<slug>/<path>) or an absolute URL
deps
handles loaded first; a dependency cycle is an error
media
all (default), print, screen and (min-width: …)
in_footer
print the script before </body>
CSP Remote URLs must be allowed by the site's Content Security Policy (style-src 'self'; remote stylesheets are not allowed by default, remote scripts never). Ship fonts and scripts in the package.
Core handles
Handle
What
wp-block-library
the block library stylesheet, on every page unless block_styles is on
dashicons
the icon font (loaded with the admin bar)
jquery
jQuery from /wp-includes/js/jquery/
comment-reply
threaded replies; enqueued by the core on singular pages with threaded comments
What wp_head prints, in order
the theme's head_top (bundled themes only),
robots, feed links, admin-bar styles for logged-in users,
the block library stylesheet and inline theme/global styles (with block_styles: only the used blocks' styles),
your preload_fonts[], styles[] and head scripts[], then Customizer css_var properties,
rel="https://api.w.org/", generator meta, canonical and shortlink,
custom background, site icon, Additional CSS,
plugin stylesheets and head scripts.
wp_footer prints comment-reply, the admin bar script, your footer scripts and plugin footer scripts.
Fonts, per-block styles and caching
Fonts go under assets/fonts/; assets/fonts/inter.woff2 is served at /wp-content/themes/<slug>/fonts/inter.woff2, which is also what url(fonts/inter.woff2) in assets/style.css resolves to. No external font service is contacted unless you add one.
"block_styles": true drops the 140 KB render-blocking block-library/style.min.css and inlines only the styles of blocks on the page; then also drop wp-block-library from your deps.
styles[] and scripts[] are served with Cache-Control: public, max-age=31536000, immutable: bump version when you ship changes. Files saved in the Theme File Editor and unversioned URLs are no-cache.
With Pursae Cache "Defer JavaScript" on and its handle list empty, your scripts[] are deferred too (body scripts only, so prefer in_footer).
the core prints <title>; always on, kept for compatibility
post-thumbnails
Featured Image panel; .Thumbnail is filled
custom-logo
logo control in Site Identity; .CustomLogo renders it (on unless set)
html5
HTML5 markup for the listed parts
responsive-embeds
wp-embed-responsive body class and aspect-ratio CSS
align-wide
Wide and Full alignments; style .alignwide and .alignfull
wp-block-styles
opinionated core block styles (theme.min.css)
custom-spacing, custom-line-height
padding/margin and line-height controls
Palette colours appear in every colour control; blocks get has-<slug>-color / has-<slug>-background-color classes and the core prints --wp--preset--color--<slug>, so use var(--wp--preset--color--accent) in your CSS. Block markup is rendered by the core: static blocks as saved, dynamic blocks (latest posts, search, archives, categories, synced patterns, shortcode) in Go.
Not in packages Block patterns and site-editor block templates are not part of theme packages in this version: /wp/v2/templates returns an empty list. Classic templates are the way to build a theme.
Appearance › Customize offers Site Identity, Colors, Menus, Widgets, Homepage Settings, Additional CSS, plus the sections a theme declares. Values are theme mods, stored per theme, so switching themes and back keeps them.
the theme mod name (unique across the theme; custom_logo and custom_css are core's)
label, description
the control
type
color (#rrggbb), text, textarea, number, checkbox, select / radio (with choices), image (attachment id)
default
used until the user saves; must match the type
transport
refresh (default) or postMessage for a live preview (not for image)
css_var
print the value as a custom property on :root (--accent: #2271b1)
body_class
add this class to <body> when truthy; with {value} the value is filled in (layout-grid)
<footer class="site-footer">{{with index .ThemeMods "footer_text"}}<p>{{.}}</p>{{end}}</footer>
Settings in a section named title_tagline appear under Site Identity.
With postMessage, the core's preview script applies css_var and body_class changes itself; for anything else enqueue a script that listens for wp.customize('setting_id', …) (see Classic's assets/js/customize-preview.js).
Changes are previewed through a changeset and saved together with Publish.
Appearance › Theme File Editor opens any installed theme's templates, stylesheets and scripts in the browser, bundled themes included (their Go glue is compiled and cannot be edited).
Files are read through an overlay: first <data>/themes/<slug>/<path> (WPGO_THEMES_DIR, the themes volume in Docker), then the embedded copy or the installed package.
Saving writes to the overlay, re-parses the template set and test-renders a page; a template or render error is rolled back automatically and shown in the editor.
Restore original deletes the overlay file (bundled themes). For a package the overlay and package directory are the same, so edits are edits of the installed files; edited assets are recorded in .edited-files and served no-cache until the package is updated.
WPGO_DISALLOW_FILE_EDIT=1 makes the editor read-only. It requires the edit_themes capability.
Not editable Theme glue written in Go, theme.json semantics (re-upload the package for those), and plugins (plugin code is compiled WebAssembly).
Installed themes live in WPGO_THEMES_DIR (default <data>/themes), one sub-directory per slug. The server loads every directory at start-up and after an upload; a package that does not validate is logged and skipped. The directory name must equal the slug.
assets/ is served at /wp-content/themes/<slug>/; every path in theme.json must point under assets/.
Limits: 32 MiB per package, 4 MiB per file, 64 MiB extracted, 2000 files; allowed extensions only. Templates must parse before anything is replaced.
Uploading needs install_themes; a package with an installed slug replaces it only with a higher version (theme mods and widgets are kept). Deleting needs delete_themes; the active theme cannot be deleted.
Themes are not signed; the Hub and the installer verify the SHA-256 of the zip.
A store theme declares "supports": {"woocommerce": true} and is listed under Pursae Commerce › Store Themes.
Demo content
A theme may ship demo/demo.json plus images under demo/images/ (.jpg, .jpeg, .png, .webp, each ≤ 1 MiB, ≤ 24 images). It is validated on install. Import is offered on the active theme's card, after activation, and as Install & Import Demo in the library; it needs the import capability.
Imported items carry _wpgo_demo = "<theme slug>", so a second import skips them and Remove Demo Content deletes exactly them and restores what it changed.
Tokens in content: {{media:hero}}, {{media_id:hero}}, {{page:about}}, {{post:…}}, {{category:…}}, {{tag:…}}; each must name an item of the demo.
Limits: 24 images, 50 pages, 100 posts, 10 menus, 20 comments per post; menus nest up to 3 levels; the import has a two-minute limit.
Live Preview with demo content
/wp-admin/theme-preview?theme=<slug> shows a theme with its demo imported, in a sandbox: a second site in the PostgreSQL schema wpgo_preview_<slug> with files in <data>/preview/<slug>/. The real site is untouched. At most 8 sandboxes are kept; only GET and HEAD are allowed, and responses carry X-Robots-Tag: noindex, nofollow.
The library's sources live in library/themes/<slug>/, each a complete theme package, and are published to Pursae Manager (make publish-themes). A site reads the library from Pursae Manager (default https://hub.pursae.com, GET /api/v1/themes, cached 12 hours per license key) or, when WPGO_THEME_LIBRARY_DIR is set, from a directory. Appearance › Add Themes opens on the Library tab with category filters and search; Install uses the same installer as Upload Theme, and a higher library version offers Update.
The repository ships 67 library themes. All have demo content. "Store" marks supports.woocommerce; "Forum" marks Pursae Forum themes; "WB" marks themes with Web Builder parts.
Theme
Category
Style
AppNest (appnest)
startup
Mobile app marketing site with phone mockups and store buttons
Archform (archform)
architecture
Monochrome, concrete texture, huge imagery, grotesk and serif italics
Atelier Nord (atelier-nord)
portfolio
Swiss grid, big grotesk type
Atlas Academy (atlas-academy)
education
Bold neo-brutalist course site in violet, coral and mint
Aurum & Pearl (aurum-and-pearl) · Store
shop
Quiet luxury jewellery, ivory and gold
Bean There (bean-there)
restaurant
Espresso café with mint accent, menu board and brew guides
Bright Smile Dental (bright-smile)
health
Fresh aqua and white, rounded and playful
Byte Notes (byte-notes)
technology
Dark-first developer blog with code blocks
Campfire (campfire) · Forum
personal
Warm maker community forum, ember and moss on paper
Campus Commons (campus-commons)
education
Friendly academic theme for schools and online courses, navy and mustard
Cloudline (cloudline)
technology
Crisp blue IT services site with SLA figures and advisories
Crumb & Crust (crumb-and-crust)
food
Bright recipe blog, rounded cards, coral and butter yellow
Datafield (datafield)
science
Chart-inspired research notebook with figures and footnotes
Devboard (devboard) · Forum
technology
Dense developer Q&A board with code styling and a stats sidebar
Dog-Ear Books (dog-ear-books) · Store
shop
Indie bookshop, newspaper masthead and shelves
Driftwood Inn (driftwood-inn)
hotel
Boutique seaside hotel, sandy neutrals and ocean blue, airy serif
Encore (encore)
music
Dark stage with neon accent
Ever After (ever-after)
wedding
Romantic wedding site with serif and script type in blush and sage
Evergreen Care (evergreen-care)
health
Calm clinic site in soft teal and white with an appointment call to action
Faithful Commons (faithful-commons)
religion
Welcoming place of worship in gentle stone and gold with arched windows
Fernwood (fernwood) · Store · WB
home
Botanical plant shop, forest green and terracotta
Frame by Frame (frame-by-frame)
entertainment
Cinematic letterbox magazine in paper, ink and festival gold
Gearhead Garage (gearhead-garage)
automotive
Carbon black and racing red auto shop, angled edges, condensed caps
Glow Botanica (glow-botanica) · Store
shop
Soft skincare boutique, blush tiles and arches
Good Boy Supply (good-boy-supply) · Store · WB
pets
Playful pet store, navy and sunshine yellow
Green Basket (green-basket) · Store
shop
Friendly organic grocery, leaf and butter
Green Pulse (green-pulse)
environment
Climate news magazine, deep forest and electric lime, data callouts
Greenleaf Market (greenleaf-market)
shop
Organic farm shop on kraft paper, fresh greens and hand-lettered labels
Guild Hall (guild-hall) · Forum · WB
gaming
Dark gaming community hub, lime and magenta on deep violet
Headline Daily (headline-daily)
magazine
Dense news front page, red and black
Hearth & Herb (hearth-and-herb)
food
Rustic home cooking, herb green and wood, printable recipes
Ink & Needle (ink-and-needle)
beauty
Black and bone tattoo parlour with blackletter and blood red
Inkwell (inkwell)
blog
Classic editorial serif with drop caps and a centered masthead
Ironbeam Construction (ironbeam)
construction
Safety yellow and steel, condensed industrial type
Justitia (justitia)
legal
Burgundy and charcoal, Caslon serif, gold hairlines
Keystone Estates (keystone-estates)
real-estate
Clean agency, forest green and stone, search-first hero
Kiln & Loom (kiln-and-loom) · Store
shop
Warm editorial crafts market, terracotta and indigo
Kite & Crayon (kite-and-crayon) · Store · WB
kids
Bright kids' toy shop, cream with tomato and mint
Launchpad (launchpad)
startup
SaaS landing page with a gradient mesh hero and changelog
Ledger & Co. (ledger-co)
business
Corporate navy and slate, serif headings, brass accent
Little Sprouts (little-sprouts)
kids
Cheerful primary colours, rounded shapes and wavy edges
Lumen Folio (lumen-folio)
photography
Dark full-bleed masonry gallery
Nest & Nook (nest-and-nook)
home
Airy neutral interiors, masonry rooms, before/after and shop-the-look
Northstar Ventures (northstar-ventures)
finance
Venture firm in dark navy and silver with serif essays
Numera (numera)
finance
Calm blue-green, clear tables, friendly geometric sans
Oak & Form (oak-and-form) · Store
shop
Airy Scandinavian furniture, linen and oak
Open Hands (open-hands)
nonprofit
Warm, hopeful charity site with impact numbers and donate buttons
Pageturner (pageturner)
books
Literary author site with Caslon type, oxblood ink and a shelf of book covers
Paper Lantern (paper-lantern)
personal
Cosy handwritten journal on cream paper
Paws & Whiskers (paws-and-whiskers)
pets
Friendly vet clinic in orange and teal, rounded and playful
Peak Athletics (peak-athletics) · Store
shop
Energetic sports gear, carbon and volt
Petal & Stem (petal-and-stem)
shop
Botanical florist with bouquet catalogue, peony and moss
Pixel Arcade (pixel-arcade)
gaming
Retro-futuristic dark UI with pixel type and neon scores
Podwave (podwave)
podcast
Bright, rounded show site with waveforms, violet and coral
Pulse Fit (pulse-fit)
fitness
High-energy dark gym, electric lime, bold condensed type
Quiet Hours (quiet-hours)
minimal
Monospaced, text-only, light and dark
Roast & Ritual (roast-and-ritual) · Store
shop
Warm coffee roaster, bag-label cards and stamps
Studio Fizz (studio-fizz)
agency
Bold, colourful and playful
Study Circle (study-circle) · Forum · WB
education
Friendly study-group forum, teal and sunshine yellow on white
Sugar & Saffron (sugar-and-saffron)
food
Pastel pastry blog, script and serif type, arched photos
Summit Trails (summit-trails)
sports
Hiking club with topographic contours, slate and alpine orange
Threadline (threadline) · Store
shop
Minimal apparel boutique, serif and sand
Trattoria (trattoria)
restaurant
Warm terracotta trattoria, classic serif, menu with price leaders
Velvet Runway (velvet-runway)
fashion
Editorial serif magazine, muted luxury
Velvet Salon (velvet-salon)
beauty
Hair and beauty salon in dusty rose and champagne, arched images
Voltage (voltage-store) · Store
shop
Dark gadget store, big search and glowing cards
Wanderline (wanderline)
travel
Adventurous travel journal with poster type and sunset colors
Pursae Forum draws every forum page (index, forums, topics, profiles, member list, login, sign-up, account) inside the active theme, so any theme shows the forum unchanged. A theme made for the forum can go further, step by step:
Step
What you write
What you get
1. Nothing
—
the forum in your page.html chain with its own forum.css
2. Colours and type
--pf-* tokens in style.css
every forum view uses your palette, fonts and radius
3. Wrapper
supports: {"pursae-forum": true} and templates/forum.html
your own layout for forum views; the forum prints its own title and breadcrumbs
Log in / Join in the header, latest topics on the home page
5. View overrides
templates/forum/<view>.html
your own markup for a view
6. Demo
a "forum" section in demo/demo.json
members, forums, topics and replies in one click
A forum page is a synthetic page (.Q.Kindpage, post ID 0) rendered via forum.html, page.html, singular.html, index.html; the body gets pursae-forum and pf-view-<view>.
Overrides must be self-contained, keep the root <div class="pf …" data-view="<view>">, and fall back to the plugin's template if they error.
Set tokens (--pf-accent, --pf-surface, --pf-text, --pf-radius, --pf-font…) on body .pf, not on :root; they fall back to Web Builder's --wb-* tokens.
Shipped references: Campfire, Devboard (packages), Guild Hall and Study Circle (package + Web Builder parts). Full guide: docs/developer/themes/forum.md
Plugin development
Plugins
A Pursae plugin is a Go program compiled to WebAssembly, packed in a signed zip and run in a wazero sandbox. It reaches the site only through a small host API, gated by permissions the administrator approves on activation.
The site runs each plugin.wasm in wazero, a WebAssembly runtime written in pure Go. The plugin talks to the core only through JSON messages and host functions; every host function and hook is gated by a permission declared in plugin.json.
Isolation. No filesystem, no sockets, no environment. A plugin sees only JSON messages from the host and can call only the host functions its permissions allow.
Containment. A panic, an infinite loop or os.Exit is caught: the call times out or fails, the filter keeps its original value and the module is re-instantiated. After five consecutive failures the plugin is disabled and the admin sees why.
Portability. One plugin.wasm runs on every platform Pursae runs on. The SDK is Go today (wpgo/sdk/go/wpgo); the ABI is plain JSON, so other languages can follow. Test with wpgotest; scaffold and package with wpgo plugin new|build.
What a plugin can do
Need
SDK
Permission
Change rendered post content and titles (the_excerpt is reserved, not fired yet)
Packages are signed with Ed25519. A site installs a package only if its signature verifies against a key it trusts (WPGO_PLUGIN_KEYS or the plugin_trusted_keys option), or if the administrator explicitly allows unsigned packages for development. Plugins published through the Hub are re-signed with the Hub's key, which sites trust automatically. Files under assets/ are covered by the signature through their digests in plugin.json.
You need Go 1.27 and a checkout of the Pursae repository (for the SDK module and the wpgo-pkg tool). The plugin is an ordinary Go main package.
1. Create the module
The SDK lives in the repository as wpgo/sdk/go/wpgo; since the wpgo module is not published separately yet, the simplest layout is a directory inside the repository:
cd pursae
mkdir -p examples/plugins/hello-reader
cd examples/plugins/hello-reader
To keep the plugin in its own repository, point a module at your checkout:
go mod init example.com/hello-reader
go mod edit -require=wpgo@v0.0.0 -replace=wpgo=../pursae
2. Write the code (main.go)
// Command hello-reader greets readers at the end of every post.
package main
import (
"html"
"wpgo/sdk/go/wpgo"
)
func init() {
// Filters receive the current value and the extra arguments the core passed.
wpgo.AddFilter("the_content", wpgo.DefaultPriority, func(_ wpgo.Context, content string, args []any) string {
post, _ := args[0].(map[string]any)
if single, _ := post["is_single"].(bool); !single {
return content
}
name := "reader"
if u, _ := wpgo.CurrentUser(); u != nil { // needs users:read
name = u.DisplayName
}
return content + "<p class=\"hello-reader\">Thanks for reading, " + html.EscapeString(name) + "!</p>"
})
}
func main() {} // never called: the host drives the plugin through its exports
Hooks registered in init are queued and sent to the host when the plugin is initialised; callbacks registered with wpgo.OnInit run right after that and may already call host functions.
3. Describe it: plugin.json
{
"slug": "hello-reader",
"name": "Hello Reader",
"version": "1.0.0",
"description": "Greets readers at the end of every post.",
"author": "You",
"requires": "0.1.0",
"license": "GPL-2.0-or-later",
"permissions": ["content:filter", "users:read"],
"hooks": ["the_content"]
}
Every subscribed hook must be in hooks, and every permission a hook or host function needs must be in permissions; the manifest is validated on pack and on install.
Use c-shared.-buildmode=c-shared produces a WASI reactor whose exports can be called after initialisation. The default build mode produces a command whose runtime exits when main returns; the loader rejects it and tells you to use c-shared.
5. Pack and sign
go build -o wpgo-pkg ./internal/plugins/cmd/wpgo-pkg # once, from the Pursae checkout
./wpgo-pkg keygen -out mykey # writes mykey.pub and mykey.key (keep .key private)
./wpgo-pkg pack -dir examples/plugins/hello-reader -wasm plugin.wasm -key mykey.key -out hello-reader-1.0.0.zip
./wpgo-pkg verify -pub mykey.pub hello-reader-1.0.0.zip
pack takes plugin.json, readme.md, icon.svg and the assets/ directory from -dir. tools/build-plugins.sh does steps 4 and 5 for every example plugin with a development key.
6. Install
Trust your key: WPGO_PLUGIN_KEYS='<contents of mykey.pub>' in the environment, or paste it into the plugin_trusted_keys option. For local hacking you can set plugin_allow_unsigned instead.
Plugins › Add Plugin › Upload Plugin, choose the zip, then Activate. The activation screen lists the manifest's permissions; tick the ones you grant.
Open a post: the greeting is there. The plugin's log (last lines shown on the Plugins screen) tells you when a call was refused or failed.
7. Iterate
wpgo plugin new -slug my-plugin -sdk /path/to/pursae writes plugin.json, main.go, a unit test using wpgotest, readme.md and a go.mod. wpgo plugin build -dir my-plugin [-key mykey.key] compiles to Wasm and packs in one step; wpgo plugin keygen|pack|verify are the wpgo-pkg commands, so the released wpgo binary is enough to package a plugin. Re-upload (the same slug replaces the package), deactivate and activate. Unit-test callbacks on a normal Go toolchain with wpgo.Dispatch.
Next step. The shortcode-demo example uses shortcodes, REST routes, a settings page, assets, transients and a scheduled event in about 150 lines.
2–64 characters, ^[a-z0-9]+(-[a-z0-9]+)*$. Identifies the plugin, owns its hooks, prefixes its REST namespace and option names. Reserved: core, built-in plugin slugs (classic-editor, wpgo-cache, goocommerce, …) and core REST namespace roots (wp, wp-admin, wp-json, wp-content, wp-includes, wp-site-health, wp-block-editor, wp-abilities, admin, oembed, batch, pursae, wpgo, wc, wc-admin, wc-analytics, wc-store, wc-telemetry, pll, contact-form-7, web-builder, elementor, gooike, headlessgo, pixelgo, seogo, rankmath, yoast); a package using one is refused at install
name
yes
up to 100 characters
version
yes
1.2.3 or 1.2.3-beta.1; the Hub refuses a version not newer than the last
description
no
up to 2000 characters, plain text
author, author_uri, plugin_uri
no
URIs must be absolute http(s) URLs
requires
no
minimum Pursae version; a plugin needing a newer core is refused at install and activation
requires_plugins
no
slugs of plugins that must be active first (a Wasm slug or a built-in plugin's slug, e.g. contact-form-7); activation is refused and lists the missing ones
license
no
an SPDX identifier
permissions
yes (may be empty)
from the permission vocabulary; no duplicates
hooks
yes (may be empty)
every hook the plugin may subscribe to (letters, digits, _ . : / -, max 128). Registering an unlisted hook is refused at runtime; a hook needing a permission requires it to be declared
shortcodes
no
every tag the plugin may register (^[a-z0-9_-]{1,64}$); needs content:filter
assets
filled in by wpgo-pkg pack
path → hex SHA-256 of every file under assets/; do not write it by hand
The Hub reads the same file and also understands tested_core, author_url and homepage as aliases shown on the marketplace listing.
Validation
wpgo-pkg pack and the site installer both validate and report every problem at once:
On activation the administrator sees each permission with a one-line description and can grant a subset. The plugin receives the intersection of declared and granted; a call needing more returns permission_denied and is logged, but does not count as a failure.
The plugin runs with the intersection of declared and granted permissions. A host function or hook needing a missing permission fails with permission_denied (logged, not fatal).
Permission
Shown to the admin as
Unlocks
options:read
Read site options
GetOption and friends: the plugin's own options (<slug>_*, plugin_<slug>_*) and the public core options; everything else (secrets, users, mail, licenses, other plugins' and built-in plugins' settings) reads as not found
options:write
Create and change site options
UpdateOption for <slug>_* / plugin_<slug>_*, stored in the plugin's own namespace. Core option names are refused even when they start with your slug, as are names starting with auth_, wpgo_, native_, pursae_ or another plugin's plugin_ prefix
posts:read
Read posts and receive post data from post lifecycle hooks
GetPost, QueryPosts; hooks save_post, save_post_*, wpgo_post_stats, plus reserved post lifecycle names
No permission is needed for Log, init, or hooks the vocabulary does not classify.
Options a plugin can read
Its own <slug>_* (dashes as underscores) and plugin_<slug>_* options, plus these public core options: blogname, blogdescription, siteurl, home, WPLANG, timezone_string, gmt_offset, date_format, time_format, start_of_week, use_smilies, default_category, default_post_format, posts_per_page, posts_per_rss, rss_use_excerpt, show_on_front, page_on_front, page_for_posts, blog_public, default_ping_status, default_comment_status, require_name_email, comment_registration, close_comments_for_old_posts, close_comments_days_old, show_comments_cookies_opt_in, thread_comments, thread_comments_depth, page_comments, comments_per_page, default_comments_page, comment_order, show_avatars, avatar_rating, avatar_default, the image size options (thumbnail_size_w … large_size_h, thumbnail_crop), uploads_use_yearmonth_folders, permalink_structure, category_base, tag_base, template, stylesheet, sticky_posts, wp_page_for_privacy_policy, site_icon, users_can_register, blog_charset, html_type.
A plugin's options are stored as wasm:<slug>:<name> in the options table; the plugin keeps using the plain name (GetOption("hello_gopher_footer")) and the host adds the namespace.
Guidelines and enforcement
Ask for what the plugin needs today. A content plugin asking for posts:write and http:outbound looks suspicious on the activation screen.
Degrade gracefully: wpgo.IsPermissionDenied(err) lets you fall back when an optional permission was not granted.
Explain permissions in readme.md; the Hub shows the list on the marketplace page.
The check happens in the host before your request is decoded, and again when a hook is registered (add_hook is refused, so the callback never runs). The manifest validator cross-checks hooks and shortcodes against declared permissions on pack and on install.
As in WordPress: filters receive a value and return it, actions receive arguments and return nothing. Callbacks run in ascending priority (default 10); core and plugin callbacks share one registry, so a plugin can run before or after core behaviour.
AddFilter is generic: the value is decoded from JSON into your declared type (string, map[string]any, a struct); if decoding fails the host keeps the original value and logs it. ctx carries the plugin slug, hook name and callback id. Every hook must be listed in the manifest's hooks.
Hooks the core fires
Hook
Type
Value / arguments
Permission
the_content
filter
Rendered post HTML (after blocks, autop and shortcodes); argument post: {"id", "type", "is_single"} (is_single is false in archives)
content:filter
the_title
filter
Title HTML (escaped, texturized); argument {"id", "type"}. Additions sanitised unless content:html
content:filter
wp_head, wp_footer
filter
Markup printed so far; return it with your additions (sanitised without content:html)
content:filter
admin_notices
action
No arguments; queue notices with wpgo.AdminNotice
admin:notices
wpgo_post_stats
filter
map[string]any of statistics in the classic editor's publish box; argument post: {"id", "title", "content"}
posts:read
wpcf7_mail_sent
action
One map: contact_form_id, title, posted_data; fired after the mail was sent
Order id, the order {id, status, currency, total, customer_id, payment_method, billing, shipping, items, date_created}
commerce:orders
woocommerce_order_status_changed
action
Order id, old status, new status, the order
commerce:orders
headless_entry_validate
filter
{"type", "documentId", "locale", "action", "data"}; add "errors" to reject with a 400 ValidationError (max 20), or change scalar attributes in data. 5 s budget
After all active plugins are loaded at start-up; after activation, update or load by another instance it fires for that plugin only
—
activate
When an administrator activates the plugin (wpgo.OnActivate)
—
deactivate
Before the plugin is unloaded (wpgo.OnDeactivate); 5 s budget
—
uninstall
When the plugin is deleted (wpgo.OnUninstall); 5 s budget; then its options, transients and events are removed
—
cron_<name>
Fired by the scheduler with {"plugin": "<slug>", "args": {…}}
cron
Reserved names
Permission rules already classify names the core will fire later, so today's manifests stay valid. Subscribing to a hook that is not fired yet is allowed; the callback just never runs.
Timeouts: content hook or shortcode 2 s, REST handler 10 s, cron_* 30 s. An overrunning callback is killed, the filter keeps its value, the plugin is re-instantiated on the next call.
Failures count: five consecutive failures (panic, timeout, malformed response) disable the plugin. A call that uses 75 % of its budget (1.5 s) counts too; REST and cron are exempt from this slow-call rule. Permission errors do not count.
One call at a time: a busy plugin makes a request wait at most one call timeout, then the callback is skipped and logged; such a page is not stored by Pursae Cache.
Re-instantiation: a fresh instance runs your init functions and OnInit again, so register everything there.
Sanitised output: without content:html, HTML you add is passed through KSES; changes inside <script>, <style> or comments are dropped.
Re-entrancy: a callback that would re-enter your plugin on the same call chain is skipped instead of deadlocking.
Types survive: a string filter must return a string, wpgo_post_stats a JSON object. Hooks fire with the request's user attached; cron callbacks see no user.
Each host function is a JSON request to a wpgo import, wrapped by a typed SDK function. Errors are *wpgo.Error with code permission_denied (wpgo.IsPermissionDenied(err)), invalid_request or host_error. Outside the Wasm host every function returns wpgo.ErrNotInHost.
Options: readable are the plugin's own and the public core options; writable only its own, stored as wasm:<slug>:<name>. Names at most 191 characters.
Posts:Post has ID, Title, Content, Excerpt, Status, Type, Slug, Date, Modified, Author, Link, Terms, Meta. PostQuery: Type, Status, Search, Author, Term, OrderBy, Order, PerPage (1–100, default 10), Page. PostInput fields are pointers (wpgo.String("…")): Title (≤1000), Content (≤1 MiB), Excerpt (≤10 000), Status, Type, Slug, Meta. Meta keys starting with an underscore are refused; content goes through KSES.
Users:User has ID, Login, DisplayName, Roles, Caps and Can(cap). Plugins never see e-mail addresses or password hashes.
Storage is a private key/value table per plugin (keys ≤256 chars, values ≤1 MiB), deleted with the plugin. Transients are JSON values with a TTL (keys ≤172 chars, values ≤1 MiB), cleaned up daily.
HTTP:HTTPGet returns Status, Header, Body (≤1 MiB, larger is an error), 8 s timeout, private and loopback addresses blocked. HTTPRequest supports GET, POST, PUT, PATCH, DELETE, HEAD; ≤32 headers (Host, Content-Length and hop-by-hop refused), body ≤1 MiB.
Mail: 1–10 recipients, sender set by the site, 60 messages per plugin per hour.
Notices: kinds NoticeInfo/Success/Warning/Error, plain text ≤2000 chars, inside an admin_notices callback.
Translation: with Pursae Multi Language on, strings appear under Languages › Translations as "Plugin: name"; otherwise the text comes back unchanged. Text ≤10000 bytes, context ≤200 bytes.
A plugin is a WASI preview1 reactor module that speaks UTF-8 JSON over guest linear memory. Any language that compiles to wasm32-wasi and exports functions can implement it; the Go SDK is the reference. A packed value is a u64 equal to ptr<<32 | len.
Toolchains. Smaller runtimes (TinyGo, Rust, AssemblyScript) produce much smaller packages than a standard Go build, but only the standard Go toolchain is tested by the project today.
Guest export
Signature
Purpose
_initialize
() -> ()
language runtime init (Go: runs package inits)
wpgo_init
() -> ()
called once after _initialize; registers hooks via add_hook
The guest replies with {"value":…} or {"error":"…"}. type is filter, action, shortcode (args = [attrs, content]) or rest (args = [request], value {"status":200,"body":…,"headers":{…}}). UI callbacks use admin_page, dashboard_widget, meta_box, meta_box_save, block and builder_widget.
Host imports live in module wpgo, all with signature (ptr, len i32) -> i64. Each returns a packed pointer to an envelope allocated with wpgo_alloc:
An import returns 0 if no response could be delivered. Example requests: add_hook{"type":"filter|action","hook":"…","priority":10,"callback":"…"}; schedule_event{"hook":"cron_x","interval":3600,"at":0,"args":{…}} (interval 0 = one-off at at); register_rest_route{"namespace":"<slug>/v1","route":"/items/(?P<id>\\d+)","methods":["GET"],"callback":"…"}; register_settings_page returns {"option_prefix":"plugin_<slug>_"}. Registrations made with register_* and enqueue_* are kept by the runtime and re-sent after a re-instantiation, so repeating one is a no-op. The guest may call host imports from inside any export.
With rest:routes a plugin registers routes under its own namespace. The core authenticates the request like any REST request (cookie + X-WP-Nonce, or an Application Password) and passes a RestRequest; the plugin returns a status, a JSON body and optional headers.
Namespace: the plugin slug or <slug>/v<N>. Core routes are matched first and foreign namespaces are refused, so plugins never shadow core routes.
Route: a regular expression anchored at both ends with named groups, e.g. /items/(?P<id>\d+).
Methods: GET, POST, PUT, PATCH, DELETE (GET when empty). HEAD uses the GET handler; OPTIONS answers with the allowed methods.
func init() {
wpgo.RegisterRestRoute("shortcode-demo/v1", "/facts", []string{"GET", "POST"}, facts)
wpgo.RegisterRestRoute("shortcode-demo/v1", `/facts/(?P<id>\d+)`, nil, fact)
}
func facts(_ wpgo.Context, req *wpgo.RestRequest) *wpgo.RestResponse {
if req.Method == "GET" {
return wpgo.JSON(200, map[string]any{"facts": allFacts()})
}
if !req.User.Can("edit_posts") { // nil user → false
return wpgo.RestError(403, "rest_forbidden", "Sorry, you are not allowed to add facts.")
}
var in struct{ Fact string `json:"fact"` }
if err := req.BindJSON(&in); err != nil || in.Fact == "" {
return wpgo.RestError(400, "rest_invalid_param", "fact is required")
}
// …store it…
return wpgo.JSON(201, map[string]any{"fact": in.Fact})
}
Request field
Content
Method
after X-HTTP-Method-Override / _method handling
Route
the matched path, e.g. /shortcode-demo/v1/facts/7
Params
named groups; req.Param("id")
Query
URL query parameters, first value each (req.QueryAll for all)
JSON body (req.BindJSON(&v)) or a JSON string; at most 1 MiB
User
{ID, Login, DisplayName, Roles, Caps} or nil
Response and authentication
wpgo.JSON(status, v) encodes a body; wpgo.RestError(status, code, message) builds {"code","message","data":{"status"}}. Allowed response headers: Cache-Control, Expires, ETag, Last-Modified, Vary, Link, Retry-After, Content-Language, Content-Disposition, X-WP-Total, X-WP-TotalPages, Location (same-site path) and the plugin's own X-<Slug>-*; others are dropped and logged. Bodies max 1 MiB; a panic, 10 s timeout or malformed result yields 500 rest_plugin_error.
There is no permission_callback: check req.User yourself (req.User.Can("edit_posts") is safe on nil). A cookie without a nonce is anonymous.
RegisterRestRouteWithHeaders requests extra headers (e.g. Stripe-Signature, X-Hub-Signature-256); max 16 per route; Cookie, Authorization, Proxy-Authorization refused.
req.RawBodyBytes() returns the unmodified body for HMAC checks.
wpgo.Text(status, contentType, text) answers with text/plain, text/csv, text/html, text/xml, application/xml, application/rss+xml or application/atom+xml; sent with nosniff, HTML sandboxed by Content-Security-Policy: sandbox.
A plugin cannot render admin HTML for a settings page; it declares one and the core renders it under Settings › <Menu title>, validates input, saves each field as an option and shows "Settings saved." Permissions: admin:settings to register, options:read to read values.
never printed back; empty input keeps the stored value
Placeholder
color
#rgb, #rrggbb, #rrggbbaa or ""
—
date
YYYY-MM-DD or ""
—
Rules: ID is ^[a-z0-9_]{1,64}$ and unique; 1–50 fields per page; labels and placeholders ≤200 characters, descriptions ≤2000. Everything is escaped. Each field is stored as option plugin_<slug>_<id> (dashes → underscores), readable only by the owning plugin.
heading := wpgo.SettingString("heading", "Did you know?")
count := int(wpgo.SettingFloat("count", 3))
greet := wpgo.SettingBool("greet", true)
name := wpgo.SettingName("heading") // "plugin_shortcode_demo_heading"
Saving the page purges the page cache. Custom HTML, buttons that call the plugin, uploads or pages outside Settings are not possible here; use an admin page (admin:pages) instead.
With cron a plugin schedules recurring or one-off events. The core's job runner stores them in the jobs table and fires the plugin's hook as an action; no visitor is needed and an event runs once even with several server instances. The hook name must start with cron_, be listed in hooks and have an action registered. Schedule from OnInit.
Shortcodes use WordPress syntax and are expanded in the_content after blocks and autop, before the the_content filters (like do_shortcode at priority 11).
[gopher-facts] self-closing
[gopher-facts count="3" style=plain] attributes: quoted or bare, names are lower-cased
[box title="Note"]Some *text*[/box] enclosing: the content is passed to the callback
[[gopher-facts]] escaped: rendered as the literal text [gopher-facts]
List the tag in plugin.json under shortcodes (needs content:filter):
wpgo.AddShortcode("box", func(ctx wpgo.Context, attrs map[string]string, content string) string {
title := attrs["title"]
if title == "" {
title = "Note"
}
return `<div class="box"><strong>` + html.EscapeString(title) + `</strong>` + content + `</div>`
})
attrs holds named attributes plus positional ones under "0", "1", …
content is the raw inner text, already autop'd; nested shortcodes are not expanded for you.
Output goes through KSES (wp_kses_post) unless the plugin holds content:html. ctx.Hook is the tag.
A panic or timeout renders an empty string and is logged.
They work in post and page content (Shortcode block and classic content), not in excerpts, widget text or the REST API's content.rendered.
Files in the package's assets/ directory are served at /wp-content/plugins/<slug>/assets/<path>?ver=<version> while the plugin is active. Permission: content:filter; a script also needs content:html on the front end and admin:scripts in the admin (wpgo.Both needs both). An admin stylesheet needs admin:settings (printed on the plugin's settings page only) or admin:scripts (every admin screen).
Rule
Value
Extensions
.css .js .svg .png .jpg .jpeg .webp .woff2
Size
2 MiB per file, 16 MiB and 256 files per package
Paths
letters, digits, ., -, _; no segment starts with a dot; sub-directories allowed
Integrity
wpgo-pkg pack writes each file's SHA-256 into plugin.jsonassets; the installer rejects unlisted, missing or modified assets
Serving
Cache-Control: public, max-age=604800, nosniff; SVGs get a sandboxing CSP
Call the enqueue functions from init or OnInit; they are static registrations. Reference fonts and images from CSS with relative URLs, or from HTML with /wp-content/plugins/<slug>/assets/…. The site's CSP allows scripts and styles from its own origin only, so prefer a packaged script over inline <script>.
Beyond settings pages a plugin can add five kinds of UI, each with its own permission. The plugin returns HTML; the core places and sanitises it: admin output loses scripts, event handlers and iframes (wp.KsesAdmin) unless admin:scripts; front-end output (blocks, widgets) goes through KSES unless content:html.
What
SDK
Permission
Limit
Admin menu page
RegisterAdminPage(AdminPage{…})
admin:pages
20
Dashboard box
RegisterDashboardWidget(id, title, cap, fn)
admin:dashboard
10
Post edit screen box
RegisterMetaBox(MetaBox{…})
admin:metaboxes
20
Pursae Editor block
RegisterBlock(Block{…})
blocks:register
50
Pursae Web Builder widget
RegisterBuilderWidget(BuilderWidget{…})
builder:widgets
50
A render callback may return 1 MiB of HTML and receives at most 256 KiB of input. Admin pages get 10 s, the others 2 s.
Admin pages
wpgo.RegisterAdminPage(wpgo.AdminPage{
Slug: "", PageTitle: "Gopher Board", MenuTitle: "Gopher Board",
Parent: "tools", // "" = top-level, "self" = under the plugin's main page, or a core menu
Render: func(ctx wpgo.Context, req wpgo.AdminRequest) wpgo.AdminResponse {
if req.Method == "POST" { /* req.Form["message"] … */ }
return wpgo.AdminResponse{HTML: `<input name="message"> <button class="button button-primary">Save</button>`,
Notices: []wpgo.PageNotice{{Type: "success", Message: "Saved."}}}
},
})
URL: /wp-admin/admin?page=<plugin slug>, or …?page=<plugin slug>.<Slug>.
Parent: "" (top-level with a dashicons-*Icon), self, or dashboard, posts, media, pages, comments, appearance, plugins, users, tools, settings.
Capability defaults to manage_options. The core wraps your HTML in a <form method="post"> with a nonce; POSTs reach the plugin only after the nonce check. Up to 10 plain-text notices.
Dashboard widgets, meta boxes, blocks
Dashboard widget box id is plugin_<slug>_<id>; capability "" = read.
Meta boxes show in the classic editor and Pursae Editor (default post and page). Declared Fields are stored as post meta plugin_<slug>_<field id>; Render output never gets form controls; OnSave receives post id and values.
Blocks are named <plugin slug>/<name>, dynamic (only attributes are saved), with inspector controls from Attributes and a server preview via /wp/v2/block-renderer/<name>. An inactive plugin's block renders nothing.
The widget type is <plugin slug>/<ID>. The core exposes widgets through GET /wp-json/web-builder/v2/plugin-widgets and renders one with POST /wp-json/web-builder/v2/plugin-widgets/render (both need edit_posts).
Not finished yet. The builder's widget panel does not list plugin widgets yet; the editor side is pending, so today the widget is reachable only through these endpoints.
Plugins run inside wazero with no cgo and no process boundary; isolation comes from the module having only linear memory and the imports the host gives it.
Area
Access
Filesystem
none: no preopens, WASI file calls fail
Network
none except HTTPGet / HTTPRequest with http:outbound (8 s, 1 MiB, loopback and private addresses blocked)
Environment, arguments
none
Clocks and randomness
available (time.Now, crypto/rand)
stdout / stderr
captured into the plugin log
Other plugins
invisible; options, storage and transients scoped by slug
Limit
Default
Linear memory
1024 pages = 64 MiB per plugin
Concurrency
one call at a time per plugin
Compiled code
kept in memory, compiled again at start-up
Hook, shortcode callback
2 s
REST route handler
10 s
cron_* callback
30 s
Instantiation + wpgo_init
10 s
Message across the boundary
8 MiB
Post content
1 MiB; title 1000, excerpt 10 000, slug 200 characters
REST body, HTTP response body, storage/transient value
1 MiB (keys 256 / 172 characters)
Admin notice
2000 characters
Settings page
50 fields
Cron interval
60 s to 1 year
Assets
2 MiB per file, 16 MiB and 256 files per package
Failure handling
A trap, timeout, os.Exit, panic or malformed response is logged; the filter keeps its value, a shortcode renders empty, a REST route answers 500. After five consecutive failures the plugin is disabled (hooks, shortcodes, routes, settings page and assets disappear), the reason is shown on the Plugins screen and survives restarts. Activate it again to reset.
For your code. Keep callbacks short and move slow work to a scheduled event; don't rely on package-level state (an instance can be replaced any time; use storage); goroutines run only while the host is inside your export; Go's runtime uses part of the 64 MiB cap, so stream and page.
64 MiB; WASI reactor built with -buildmode=c-shared
readme.md
no
1 MiB; shown on the marketplace page
icon.svg
no
256 KiB; marketplace icon
assets/…
no
2 MiB per file, 16 MiB total
signature
if the site requires signatures
1 KiB
No other files are allowed.
wpgo-pkg
wpgo plugin keygen|pack|verify|new|build # the same tool is built into the wpgo binary
go build -o wpgo-pkg ./internal/plugins/cmd/wpgo-pkg
wpgo-pkg keygen -out mykey [-comment "My plugins key"]
# writes mykey.pub (publish this) and mykey.key (mode 0600; keep it private); existing files are kept
wpgo-pkg pack -dir ./my-plugin -wasm plugin.wasm -key mykey.key -out my-plugin-1.0.0.zip
# packs plugin.json, readme.md, icon.svg and assets/** from -dir; omit -key for an unsigned package
wpgo-pkg verify -pub mykey.pub my-plugin-1.0.0.zip
# verifies the signature and prints the manifest summary
Key files are base64 with optional # comment lines. tools/build-plugins.sh [plugin-dir …] builds the example plugins into examples/plugins/dist/ with a development key; set WPGO_SIGNING_KEY=/path/to/key to sign with your own.
Development only.plugin_allow_unsigned has no screen; never turn it on in production.
Trusted keys come from WPGO_PLUGIN_KEYS (comma-separated), the plugin_trusted_keys option (Plugins > Trusted Keys, effective immediately), the Manager's key list (replaced on every index refresh), and in development the dev-key.pub next to the example packages when WPGO_TRUST_DEV_KEY=1.
Updates and versioning
The site records which key signed each plugin. A new version must come from the same key (any two Pursae Manager keys count as the same publisher) and must not be older: from the Manager such a package is refused; an upload offers Replace current with uploaded. Before a Manager update the previous package is kept as <slug>.zip.prev and restored if the new one fails to load. Bump version for every release; the Hub refuses an existing or lower version. Packages over 64 MiB are refused.
The SDK compiles on every platform. Outside the host, host functions return wpgo.ErrNotInHost, while hook registration and wpgo.Dispatch work, enough for go test without WebAssembly.
func TestFooterOnSinglePosts(t *testing.T) {
wpgo.Init() // flushes registrations made in init(); safe to call more than once
req := map[string]any{
"plugin": "hello-reader", "hook": "the_content", "type": "filter",
"callback": callbackFor(t, "the_content"),
"value": "<p>Hi</p>",
"args": []any{map[string]any{"id": 1, "type": "post", "is_single": true}},
}
raw, _ := json.Marshal(req)
var resp struct {
Value string `json:"value"`
Error string `json:"error"`
}
if err := json.Unmarshal(wpgo.Dispatch(raw), &resp); err != nil || resp.Error != "" {
t.Fatalf("dispatch: %v %s", err, resp.Error)
}
if !strings.HasSuffix(resp.Value, "Thanks for reading, reader!</p>") {
t.Fatalf("got %q", resp.Value)
}
}
Callback names are generated (the_content#1, shortcode:box#2, rest:ns/route#3). Shortcode requests use "type": "shortcode" with "args": [attrs, content]; REST requests "type": "rest" with "args": [request].
Faking the host: wpgotest
wpgo/sdk/go/wpgo/wpgotest fakes the host so code calling GetOption, Storage, Transients, GetPost, QueryPosts, CurrentUser, HTTPGet/HTTPRequest, SendMail or AdminNotice runs in plain go test.
func TestRates(t *testing.T) {
h := wpgotest.New(t)
h.SetOption("plugin_rates_currency", "EUR")
h.StubHTTP("https://api.example.com/rates", 200, `{"eur":1.1}`)
h.AddPost(wpgo.Post{Title: "Hello", Content: "body"})
h.SetUser(&wpgo.User{ID: 1, Caps: []string{"edit_posts"}})
// ... call your code, then inspect what it did:
_ = h.Storage() // plugin storage
_ = h.Mails() // queued mail
_ = h.Notices() // admin notices
_ = h.Requests() // outbound HTTP requests
}
Unstubbed URLs fail like a refused request; permissions are not enforced by the fake. For UI: h.RenderAdminPage, h.RenderBlock, h.Registered("register_meta_box"). Inside the repository, internal/plugins tests run a real plugin.wasm with plugins.NewRuntime and plugins.MemoryHost.
On a site
Run with WPGO_WEB_DIR=web and plugin_allow_unsigned; upload, activate, read the plugin log on the Plugins screen (also in the server log with plugin=<slug>).
WPGO_MARKET_DIR=/path/to/zips lists your packages on Plugins › Add Plugin for one-click install.
The Hub is the marketplace sites read from Plugins › Add Plugin. A Hub operator publishes through the admin panel; as a developer you deliver a package and listing details.
Build and pack, signed with your own key: the Hub keeps your signature as provenance and re-signs with its key, so sites install without extra configuration.
Fill in plugin.json completely. The Hub reads slug, name, version, description (the card text: one or two sentences), author, author_url, homepage, requires_core, tested_core, permissions, hooks (author_uri, plugin_uri, requires are the same data).
Add readme.md (the listing page) and a square icon.svg (otherwise a placeholder is generated).
Test on a clean site with only the permissions you ask for.
Submit: send the zip to the Hub operator; for the public Hub, through the repository's plugin submission process. Updates are published the same way with a higher version. Details in the Hub section below.
The Hub (wpgo-hub) is the central service behind the plugin and theme marketplace, core updates, licenses and signing keys. Every production Pursae site talks to https://hub.pursae.com.
a public JSON API under /api/v1/, read by sites and the public site: no authentication, cacheable, rate limited;
an admin panel under /admin/ where the operator manages the plugin and theme marketplace, core releases and signing keys.
There is no environment variable or option to point a production site elsewhere; only development builds (-tags devhub) read WPGO_DEV_HUB_URL. Sites talk to a Hub only over https (plain http only for localhost, loopback, *.localhost and *.test); redirects never downgrade to http.
Feature
Endpoint
Where it shows
Plugin marketplace
GET /api/v1/plugins
Plugins › Add Plugin
Theme marketplace
GET /api/v1/themes
Appearance › Themes › Add Theme
Package downloads
…/{slug}/download[/{version}]
one-click install; site checks SHA-256 and, for plugins, the Hub signature
Core releases
GET /api/v1/index → core
Dashboard › Updates (Update to version X)
Previous core release
GET /api/v1/core/{version}
Dashboard › Updates › Reinstall version Y
Plugin updates
GET /api/v1/plugins
Plugins and Dashboard › Updates
License check
GET /api/v1/license
Settings › License
Signing keys
GET /api/v1/index → keys
added to trusted plugin keys automatically (replaced on every refresh)
Product logo
GET /api/v1/index → brand
replaces the shipped logo on every screen
Catalog responses carry Cache-Control: public, max-age=300; sites cache the catalog for 12 hours. One ping per host per 10 minutes is accepted (429 otherwise).
A key listed in the same answer as the release it verifies proves nothing, so core self-updates need a release root key compiled into the binary: rootKeysBuiltin in internal/server/hub_trust.go (the pinned Pursae release root), plus optional extra roots via -ldflags "-X wpgo/internal/server.rootKeysLinked=…" (Docker: --build-arg ROOT_KEYS=…), which only add roots.
endorsement = base64(Ed25519.Sign(rootKey, "pursae-hub-key-v1\n" + id + "\n" + public)). Plugin packages are verified only against endorsed Hub keys too (with wpgo_hub_trust_keys on). A production binary cannot relax this; a development build with WPGO_TRUST_HUB_KEYS=1 trusts every listed key. A compromised Manager key is rotated by generating a new one, having the root endorse it and no longer listing the old one.
Settings › License takes the license key (option pursae_license_key, never readable by plugins), checked with GET /api/v1/license and cached 12 hours. Every Hub request carries X-Pursae-Site and, with a key, X-Pursae-License; the Hub then also lists Pro and Private packages and beta versions (badges Pro, Private, Beta).
Statistics are on by default and can be turned off under Settings › License › "Send usage statistics" (pursae_send_stats). The daily ping is POST /api/v1/sites/ping (also run by wpgo_hub_check) with url, version, locale, os, arch, license, theme, plugins, themes and contacts. Events (POST /api/v1/sites/events) include plugin_install, plugin_update, plugin_activate, plugin_deactivate, plugin_delete, theme_install, theme_update, theme_activate, theme_delete, theme_preview, demo_import and core_update.
Privacy. The site never sends user data, e-mail addresses (other than opted-in update contacts), post content, titles or visitor information. The public site count is GET /api/v1/sites/count; the site list is not public.
Lists the Hub catalog (GET /api/v1/plugins, sorted by last update, searchable by name, slug, description and author) next to the built-in plugins and any packages in WPGO_MARKET_DIR. A card shows name, author, version, description, icon, the permissions the plugin asks for, download count and minimum core version; the detail view shows the package's readme.md. Cards show Requires Pursae X and Tested up to Y (requires_core, tested_core); a too-new requirement shows a disabled Incompatible button. tags are filter links (?tag=<tag>).
Install Now downloads from download_url, verifies the SHA-256 against the listing's sha256 and the signature against a trusted key (Hub keys are trusted automatically), stores the plugin inactive and records the signing key.
Activate opens the permission screen where you grant what the plugin may do.
The Upload Plugin tab goes through the same signature check.
Themes
Appearance › Themes › Add Theme › Library shows the Hub's theme catalog (GET /api/v1/themes). Theme packages contain no code and are not signed; Install checks size and SHA-256, validates theme.json, templates and demo, and unpacks into <data>/themes/<slug>/. Live Preview builds a sandbox with the demo content first. WPGO_THEME_LIBRARY_DIR serves the library from a local directory.
Updates
Hub-installed plugins (source = hub) show an update row on the Plugins screen and under Dashboard › Updates (Update Plugins) when the catalog lists a higher version. Updates verify SHA-256 and signature like an install; an active plugin keeps only previously granted permissions the new version still asks for. The optional changelog is shown in the update row.
Automatic updates: Enable auto-updates on the Plugins screen (option pursae_plugin_auto_updates); the daily wpgo_hub_check then updates them, but an active plugin only when the new version asks for no new permission.
Offline: without a reachable Hub only built-in plugins, bundled themes and local packages show, and uploads still work.
Publishing goes through the Hub's admin panel (Admin › Plugins, Admin › Themes): the operator uploads a zip, reviews the listing and publishes it. Developers deliver the package and listing details; for the public Hub, through the project's submission process.
Sending your plugin. Send the signed zip to the Hub operator: for the public Hub through the repository's plugin submission process, for a private Hub however your organisation agreed. The docs do not describe the public submission process in more detail.
What the Hub does on publish
Parses and validates the zip and manifest; rejects a version that already exists for the slug or is lower than the latest published one.
Keeps the developer's signature (if any) as provenance and re-packs the zip with the Hub's own signature over the same digest.
Stores the repacked zip, its SHA-256 and size.
Listing fields come from plugin.json (slug, name, version, description, author, author_url/author_uri, homepage/plugin_uri, requires_core/requires, tested_core, permissions, hooks); the operator can override description and homepage. readme.md becomes the detail page and icon.svg the icon.
After publishing
The item appears in GET /api/v1/plugins immediately (with download_url, sha256, signed_by and permissions) and on sites within their 12-hour catalog cache. Each download increments downloads; older versions stay under versions in GET /api/v1/plugins/{slug}; unpublish hides an item without deleting files.
Themes (zip with theme.json, templates/, assets/) are validated but not signed; the core theme library is published with make publish-themes PURSAE_MANAGER_DIR=/path/to/pursae-manager [PREINSTALL=slug,slug|all].
The Hub's signing key lives in WPGOHUB_DATA_DIR/keys/<id>.key; old public keys stay listed in GET /api/v1/index so installed packages keep verifying.
Production binaries always talk to https://hub.pursae.com. Run your own Manager to develop and test packages and releases against development builds (-tags devhub), or as the Hub of a fork that builds its own binaries (with its own config.DefaultHubURL and release root key).
wpgo-hub is a single binary with PostgreSQL and a data directory; in the Pursae compose stack it is on host port 8090.
Variable
Default
Meaning
WPGOHUB_ADDR
:8080
listen address
WPGOHUB_PUBLIC_URL
http://localhost:8090
used in download_url and links; set to the public https:// address
Open /setup to create the operator account, then /login (argon2id, login throttling).
Screen
Does
/admin
overview: site count, plugins and themes, last pings, latest core release
/admin/sites
hosts, versions, first/last seen, local flag; search; delete
/admin/plugins, /admin/themes
upload a zip, publish/unpublish, versions, edit the listing, delete
/admin/releases
core releases: version, download and notes URLs, notes; publish
/admin/keys
signing keys; generate a new one
/admin/settings
hub name, public URL, rate limits
Before the first plugin. Generate a signing key under /admin/keys: packages are re-signed with it, and sites add it to their trusted keys from GET /api/v1/index.
Connect sites
Only a development build connects to another Hub: build with -tags devhub (make dev, or the development compose file with GO_TAGS=devhub), set WPGO_DEV_HUB_URL=http://localhost:8090 (compose default http://pursae-manager.test:8090) and WPGO_TRUST_HUB_KEYS=1. WPGO_DEV_HUB_URL=off disconnects from every Hub. Production binaries ignore both.
API
The same public API as the public Hub: GET /api/v1/index, /plugins, /plugins/{slug}, /plugins/{slug}/download[/{version}], /plugins/{slug}/icon, the same for /themes (with /screenshot), POST /api/v1/sites/ping, GET /api/v1/sites/count.
Pursae serves the WordPress REST API at /wp-json/. The wp/v2 namespace mirrors WordPress closely enough that the block editor, mobile apps and headless clients work unchanged.
Differences from WordPress No wp-site-health/v1, wp/v2/plugins or wp/v2/font-families yet; wp/v2/templates returns an empty list. Block types, pattern directory and block directory searches return empty lists.
no credentials; published posts, pages, media, terms, public profiles, comments
Cookie + nonce
browser clients
session cookie plus X-WP-Nonce (or ?_wpnonce=) for action wp_rest; a cookie without a nonce is anonymous, a wrong nonce is 403 rest_cookie_invalid_nonce
Application Passwords
scripts, apps, CI
HTTP Basic with the login and a 24-character password (shown once); wrong or missing is 401 incorrect_password
OAuth 2.1
MCP clients
Authorization: Bearer pat_… tokens from the OAuth flow; narrowed by scopes like Application Passwords
Admin pages expose the nonce in wpApiSettings.nonce; every authenticated response returns a fresh one in X-WP-Nonce.
Application Passwords are created under Users › Profile › Application Passwords, via /wp/v2/users/me/application-passwords, or through /wp-admin/authorize-application.
After five Basic-auth failures from one address within 15 minutes, further requests get 429 too_many_retries.
TLS only Basic authentication sends the password with every request; use Application Passwords only over TLS.
Application Password scopes
A password without scopes has all its user's capabilities. A scoped password is narrowed twice: capabilities are cut to what the scopes need, and a route of another scope returns 403 rest_scope_forbidden with data.required_scope. Scopes never add a capability.
Every scoped password may also read the REST index, /wp/v2/users/me and use /pursae/v1/mcp. A scoped password cannot create, change or revoke Application Passwords.
OAuth 2.1 endpoints
Endpoint
Purpose
/.well-known/oauth-protected-resource
protected-resource metadata (RFC 9728)
/.well-known/oauth-authorization-server
authorization-server metadata (RFC 8414)
POST /oauth/register
dynamic client registration (RFC 7591), public clients only
/wp-admin/oauth-authorize
consent screen with scope checkboxes
POST /oauth/token
authorization_code (PKCE) and refresh_token grants
POST /oauth/revoke
token revocation (RFC 7009)
PKCE with S256 is mandatory; codes live 5 minutes and work once.
Access tokens (pat_…) last one hour; refresh tokens (prt_…) last 30 days and rotate on every use. Only SHA-256 hashes are stored.
A user keeps at most 20 grants. The Headless delivery API (/wp-json/headlessgo/v1) uses its own API tokens.
Capabilities
Writes are checked like WordPress: edit_posts, edit_pages, upload_files, manage_options / edit_theme_options, manage_categories, and meta capabilities per item. Authenticated without the capability: 403 rest_forbidden; anonymous: 401.
Plugins add endpoints under their own namespace, /wp-json/<slug>/v1/… (the version may differ). They appear in the index under routes and namespaces while the plugin is active and disappear when it is deactivated or disabled.
Core routes are matched first, so a plugin can never take over a wp/v2 path.
Authentication is the core's; the plugin receives the user, if any, and applies its own checks.
OPTIONS returns the allowed methods; an unaccepted method is 404 rest_no_route.
Request bodies are limited to 1 MiB; JSON is decoded for the plugin, other types are passed as text.
A failing plugin answers 500 rest_plugin_error; after repeated failures it is disabled and the route returns 404 until re-activated.
Responses are application/json; charset=UTF-8; _fields and _envelope do not apply.
Scopes Plugin routes are covered by no Application Password scope, so a scoped password gets 403 rest_scope_forbidden on them.
Benchmarks
Performance
Pursae and WordPress measured on the same machine, content, theme and container limits on 2026-11-09. Every config and raw result is in the repository, and the tables keep the places where WordPress wins.
Uncached pages: about 8× WordPress' throughput. Home 397 vs 51 req/s, single post 394 vs 58, REST posts list 1,046 vs 89, admin dashboard 627 vs 72 (stock against stock).
With the usual plugin stack: about 13× (single post 232 vs 19 req/s), and a product page at 194 vs 16 req/s. The six WordPress plugins cut its throughput to about a third and take a page from 32 to 139 queries; the six Pursae built-ins cost 30–40 % (13 → 16 queries on the home page).
Cached pages: a tie. WP Super Cache served by nginx and Pursae Cache both answer in about 0.1 ms and both run into the load generator (28–35 k req/s).
Memory: 95 MiB idle for the whole Pursae stack against 233 MiB (stock) and 330 MiB (with plugins); peak under load 184–202 MiB against 276–489 MiB.
Lighthouse (home, mobile): 100 against 96 stock, 99 tuned and 67 with the plugin stack.
Where Pursae does not win
Search is not page-cached (/?s= answers Cache-Control: no-cache): 105–119 req/s, while WP Super Cache caches search results and serves 5,724 req/s. Uncached it is still 2.5× stock WordPress (119 vs 48), but it is Pursae's slowest page (93 ms TTFB under load, 26 ms alone).
Cached pages are no faster than a well-set-up WordPress page cache.
Cold start is the same: about 3 s for the whole stack on both sides, about 1 s for the app alone.
The database is bigger: 30 MB and 92 tables against 16 MB and 59 tables, because migrations create the built-in plugins' tables whether or not they are on.
Pursae Cache slowed uncached routes a little (REST list 1,046 → 885 req/s, admin post list p50 27 → 70 ms).
WordPress "tuned" was slower than stock on uncached requests (REST list 64 vs 89 req/s, admin 43 vs 72); it was kept as configured rather than tuned after seeing the results.
Pursae 0.1.9 (commit cb856438), PostgreSQL 17. k6 1.3.0, 10 virtual users, median of three 20 s runs.
Setups
Setup
WordPress
Pursae
Stock
WordPress 7.1.4, PHP 8.3 php-fpm (official image, OPcache on, pm = dynamic, 5 children), nginx, MariaDB 11.4, no plugins
Pursae Cache off, no built-in plugins (Classic Editor stays on, as on a fresh install)
Cached ("tuned")
Stock plus Redis 7 with Redis Object Cache, WP Super Cache served from disk by nginx (gzip_static), static php-fpm pool of 12, innodb_buffer_pool_size = 512M
Pursae Cache on (defaults)
Real site
Stock plus WooCommerce, Yoast SEO, Polylang, ACF, Elementor and Contact Form 7, no page cache
Commerce, SEO, Multi Language, Custom Fields, Web Builder, Contact Form; Pursae Cache off
Content, theme and limits
Deterministic content (bench/content/gen.py): 1000 posts with block markup, 10 categories, 60 tags, 50 pages, 200 products in 5 categories, 12 images as featured images. Permalinks /%postname%/ on both.
Seeding took 125.2 s on WordPress (WXR import 7.5 s) and 13.5 s on Pursae (WXR import 5.5 s).
Theme: Twenty Twenty-Five on both (WordPress' 1.5 and Pursae's Go-template port); Pursae's home page HTML is about half the size, mostly because WordPress inlines more block CSS.
Endpoints: home, single post, category archive, product (real-site setups only), search (/?s=garden), REST posts list, and logged in as administrator the dashboard and post list.
Metrics
Load: k6 in its own container (4 CPUs), 10 virtual users in a closed loop over random sample URLs; every URL requested once first, a 5 s warm-up, then three 20 s runs. Reported: req/s, TTFB p50, latency p95/p99, median of three.
Cold and warm requests: first and second request after a restart on URLs the load test never touches, with TTFB and server-side database statement counts.
Memory: sum of docker stats of every container, idle and peak. Cold start: seconds to the first home page answer. Size: images, install on disk, database. Lighthouse: home page, mobile preset, median of three.
Fairness rules Each side runs its recommended production shape (WordPress' official image behind the WordPress.org nginx config; Pursae from its own Dockerfile, production build). WP-Cron is disabled on page views. Versions are pinned. Nothing was tuned after looking at the results.
You need Docker with Compose v2 (8 GB of memory for Docker is plenty), Python 3 and, for the Lighthouse column, Node and Chrome.
make bench runs everything in about an hour; results land in bench/results/<date>/.
make bench BENCH_ARGS="--setups wp-stock,pursae-nocache --runs 1 --duration 5s" gives a quick look.
bench/run.py --help lists the options: --vus, --duration, --reuse (skip seeding), --keep (leave the stacks up on ports 18081 and 18082).
Each setup leaves raw k6 summaries, query samples, Lighthouse scores and result.json in bench/results/<date>/<setup>/; summary.json holds everything and bench/report.py turns it into summary.md.
The WordPress stack, nginx configs (stock and WP Super Cache), php-fpm pools, the PhpRedis image
bench/pursae/compose.yaml
The Pursae stack
bench/content/gen.py
The WXR file and the product payloads
bench/k6/load.js
The load test
Limits of these numbers One machine with Docker Desktop on macOS (a Linux VM): absolute numbers are lower than on bare Linux, so the ratio matters more than the values. Cache hits on both sides run into the load generator, so cached throughput says "both are fast enough", not who is faster. The themes are equivalent, not identical, and the built-ins are not feature-for-feature copies of the WordPress plugins.
Each built-in plugin covers the core features of a WordPress plugin people usually pay for. Prices are the cheapest one-site plan billed yearly at list price (renewal), read on the vendor's pricing page on 2026-11-09, without tax.
Pursae built-in
Covers the core features of
Plan
Price / year
Commerce
WooCommerce (free) + premium extensions such as WooCommerce Subscriptions
Subscriptions, 1 year
$279
Web Builder
Elementor Pro
Essential, 1 site
$60
SEO
Yoast SEO Premium (and Rank Math PRO)
1 site
$118.80
Cache
WP Rocket
Single
$60 ($36 first year, offer until 2026-11-28)
CDN
WP Offload Media
Bronze (up to 2,000 media items)
$69 ($39 first year)
Cookie
Complianz Premium
Personal, 1 site
$59
Pixel
PixelYourSite Pro
Starter, 1 site
$199
SMTP
WP Mail SMTP Pro
Pro, 1 site
$99 ($49 first year)
Custom Fields
ACF PRO
Personal, 1 site
$49
Multi Language
Polylang Pro
Pro
€99 (renewals 50 % off)
Backup Manager
All-in-One WP Migration Unlimited Extension
Standard (up to 50 sites)
$69
Contact Form
Contact Form 7
—
free
Security
The login-security part of Wordfence / Solid Security — no firewall or malware scanner
Wordfence Premium
($149, not comparable)
Maintenance
Maintenance PRO (WebFactory)
Personal
sold lifetime only ($59 once)
Headless
A headless CMS layer; no single WordPress plugin matches
—
—
Total Added up at list prices, the rows with a yearly price come to about $1,062 plus €99 a year for one site (Security, Maintenance, Headless and Contact Form left out). Pursae's built-ins ship in the GPL binary at no extra cost.
Choose which cookies you allow. Necessary cookies are always on because the site does not work without them. Your choice is stored in a cookie on this device.
Stores your cookie choice, its date, the policy version and your consent ID, so the banner does not come back on every page.
12 months
wpgo_logged_in
This site
Keeps you signed in to the forum and the dashboard; it lasts longer when “remember me” is ticked.
Session / 14 days
pll_language
This site
Remembers the language you chose (Turkish or English).
1 year
pursae-theme
This site (browser storage)
Remembers your light or dark theme choice; it is only created when you switch the theme. It is never sent to the server.
Until you clear it
pursae-cookie
This site (browser storage)
Records your cookie choices and when you made them in your browser.
Until you clear it
pursae-stars
This site (browser storage)
Keeps the star count of the GitHub button for an hour so GitHub is not asked again on every page. It holds no personal data and is never sent to the server.
1 hour
Preferences
Remembers the tab you picked and the boxes you closed.