From 627b435232ac903901f81669f490ed6130dd2e24 Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 18 May 2026 22:12:15 +0200 Subject: [PATCH] Document remote-site onboarding flow Add a Remote Sites guide that walks new users from local site setup through SSH thin clone, plugin installation, and top-plugin compatibility. --- README.md | 27 +++++++ astro.config.mjs | 1 + docs/branching.md | 19 +++++ docs/commands.md | 6 +- docs/remote-sites.md | 186 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 238 insertions(+), 1 deletion(-) create mode 100644 docs/remote-sites.md diff --git a/README.md b/README.md index 20056585..ca17a1f1 100644 --- a/README.md +++ b/README.md @@ -213,6 +213,33 @@ marketing/ # marketing WordPress tree `main` cannot be deleted. Resetting `main` requires `--force`. +## Remote sites + +Bring an existing ForkPress-compatible WordPress root into a local branch over +SSH: + +```bash +forkpress remote clone production \ + --ssh deploy@example.com \ + --ssh-key ~/.ssh/id_ed25519 \ + --ssh-port 2222 \ + --path /srv/www/example \ + --url https://example.com \ + --branch production-main +``` + +The first sync is thin by default: uploads, caches, backups, logs, and upgrade +temp files are skipped so the branch can boot quickly. Use `--include-uploads` +or `--full-sync` when you need more of the remote tree locally. + +Install plugins from the branch's WordPress admin at +`/wp-admin/plugin-install.php`. ForkPress tracks the WordPress.org top 100 +popular plugins as an explicit compatibility target and includes a package +smoke test for those plugin downloads. + +See [Remote Sites](docs/remote-sites.md) and +[Top Plugin Support](docs/top-plugin-support.md). + ## Merging ForkPress merges WordPress files and branch-local SQLite database changes. Clean diff --git a/astro.config.mjs b/astro.config.mjs index 5673eb75..6fe59f23 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -43,6 +43,7 @@ export default defineConfig({ label: 'Core workflows', items: [ { label: 'Branching', slug: 'docs/branching' }, + { label: 'Remote sites', slug: 'docs/remote-sites' }, { label: 'Merging', slug: 'docs/merging' }, { label: 'Plugin validator recipes', slug: 'docs/plugin-validator-recipes' }, { label: 'Top plugin support', slug: 'docs/top-plugin-support' }, diff --git a/docs/branching.md b/docs/branching.md index ef37f9d8..4ed936b5 100644 --- a/docs/branching.md +++ b/docs/branching.md @@ -45,6 +45,25 @@ http://marketing.wp.localhost:18080/wp-admin/ The WordPress admin bar shows the current branch and lets you switch between local branches. +## Start From A Remote Site + +If your source site already exists on another server, clone a remote +ForkPress-compatible WordPress root into a local branch: + +```bash +forkpress remote clone production \ + --ssh deploy@example.com \ + --ssh-key ~/.ssh/id_ed25519 \ + --ssh-port 2222 \ + --path /srv/www/example \ + --url https://example.com \ + --branch production-main +``` + +Remote clones use a boot cache by default and skip uploads, caches, backups, +logs, and upgrade temp files. See [Remote Sites](./remote-sites.md) for the +full workflow, including when to use `--include-uploads` or `--full-sync`. + ## Inspect branches ```bash diff --git a/docs/commands.md b/docs/commands.md index 9d5aa9c5..3955d3de 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -46,10 +46,14 @@ audit queues, stale reviews, and source/target/apply-reviewed choices, see | `forkpress commit -m "message"` | Commit and push the current Git branch back to ForkPress. | | `forkpress pull` | Pull with rebase and autostash. | | `forkpress agents [dir]` | Create agent branches and Git worktrees. | -| `forkpress remote clone --ssh --path --branch ` | Thin-clone a boot-ready remote WordPress root over SSH, skipping uploads, caches, backups, logs, and upgrade temp files by default, then create a local COW branch. | +| `forkpress remote clone --ssh --ssh-key --ssh-port --path --url --branch ` | Thin-clone a boot-ready remote WordPress root over SSH, skipping uploads, caches, backups, logs, and upgrade temp files by default, then create a local COW branch. | | `forkpress remote add --cache-root ` | Register an existing local remote-site cache. | | `forkpress remote branch ` | Create a local COW branch from a registered remote cache. | +For the remote-site onboarding flow, including thin syncs, plugin +installation, and the top-100 plugin compatibility target, see +[`remote-sites.md`](remote-sites.md). + ## Diagnostics and storage | Command | Purpose | diff --git a/docs/remote-sites.md b/docs/remote-sites.md new file mode 100644 index 00000000..f7b0616e --- /dev/null +++ b/docs/remote-sites.md @@ -0,0 +1,186 @@ +# Remote Sites + +Use remote-site cloning when you already have a WordPress tree on another +server and want a local ForkPress branch from it. + +This guide covers the boot path: + +- sync a remote WordPress root over SSH; +- keep the first sync small by skipping uploads and cache directories; +- create a local COW branch with merge-base metadata; +- install plugins from wp-admin in that branch; +- understand what ForkPress means by top-plugin support. + +## Start From A ForkPress Site + +Create or enter a local ForkPress site, then start the preview server: + +```bash +mkdir client-site +cd client-site +forkpress init +forkpress serve +``` + +ForkPress creates the local `main` branch and the `.forkpress/` metadata +directory. Remote-site caches are stored under +`.forkpress/cow/remote-sites/`. + +## Thin-Clone A Remote WordPress Root + +Run `remote clone` with the SSH target, remote path, production URL, and local +branch name: + +```bash +forkpress remote clone production \ + --ssh deploy@example.com \ + --ssh-key ~/.ssh/id_ed25519 \ + --ssh-port 2222 \ + --path /srv/www/example \ + --url https://example.com \ + --branch production-main +``` + +The remote path must be a materialized WordPress root. It needs `wp-load.php` +and, for COW branch creation, the ForkPress-compatible SQLite database at +`wp-content/database/.ht.sqlite`. + +ForkPress uses `rsync` over SSH. By default it creates a boot cache and skips +large or rebuildable directories: + +- `wp-content/uploads/` +- `wp-content/cache/` +- `wp-content/upgrade/` +- common backup directories +- logs and `.git/` + +That default is meant to boot quickly. It avoids downloading uploads before the +first local preview. + +## Include More Files When Needed + +Include uploads in the initial sync: + +```bash +forkpress remote clone production \ + --ssh deploy@example.com \ + --path /srv/www/example \ + --url https://example.com \ + --branch production-main \ + --include-uploads +``` + +Download the full tree: + +```bash +forkpress remote clone production \ + --ssh deploy@example.com \ + --path /srv/www/example \ + --url https://example.com \ + --branch production-main \ + --full-sync +``` + +Add project-specific excludes: + +```bash +forkpress remote clone production \ + --ssh deploy@example.com \ + --path /srv/www/example \ + --url https://example.com \ + --branch production-main \ + --exclude wp-content/private-exports/ +``` + +Use `--force` to update an existing remote-site cache registration. + +## Branch Later From A Cache + +If you want to sync now and branch later, omit `--branch`: + +```bash +forkpress remote clone production \ + --ssh deploy@example.com \ + --path /srv/www/example \ + --url https://example.com +``` + +Inspect and branch from the cache: + +```bash +forkpress remote list +forkpress remote show production +forkpress remote branch production production-main +``` + +Branches created from a remote cache get the same merge metadata as normal +ForkPress branches: database merge bases, file merge bases, row identity +capture, and per-branch ID bands. + +## Preview The Branch + +Open the branch preview: + +```text +http://production-main.wp.localhost:18080/ +http://production-main.wp.localhost:18080/wp-admin/ +``` + +The admin opens logged in by default. The branch switcher in the admin bar lets +you move between local branches. + +## Install Plugins + +Install plugins from WordPress admin inside the branch: + +```text +http://production-main.wp.localhost:18080/wp-admin/plugin-install.php +``` + +You can also use the normal WordPress path: + +```text +Plugins → Add New +``` + +ForkPress branch previews keep WordPress file modifications enabled for plugin +installation. The COW router also keeps `plugin-install.php` and `update.php` +requests on the `wp-admin` path, so install and update requests do not fall +through to the public site front controller. + +After installing a plugin, work normally in the branch. Plugin files live under +that branch's `wp-content/plugins/`, and plugin database changes go to that +branch's SQLite database. + +Merge the branch when you are ready: + +```bash +forkpress branch merge production-main --into main +``` + +## Top Plugin Support + +ForkPress tracks the current WordPress.org top 100 popular plugins as an +explicit compatibility target. The package smoke test downloads all 100 plugin +zips, extracts them into a `wp-content/plugins` tree, and verifies their plugin +headers without executing plugin code. + +For the support matrix and the difference between generic merge audit coverage +and plugin-specific semantic recipes, see +[Top Plugin Support](./top-plugin-support.md). + +## Troubleshooting + +If branch creation reports that the source branch database does not exist, the +remote cache is not a ForkPress-compatible SQLite WordPress root. Register or +sync a cache that includes `wp-content/database/.ht.sqlite`. + +If `rsync` fails, verify the SSH target, key, port, and remote path outside +ForkPress first: + +```bash +ssh -i ~/.ssh/id_ed25519 -p 2222 deploy@example.com 'test -f /srv/www/example/wp-load.php' +``` + +If uploads are missing in the local preview, that is the default thin-clone +behavior. Re-run the clone with `--include-uploads` or `--full-sync`.