Documentation

Install

WP Freighter is one plugin on the site that will become the host. Current release: 1.5.1, for WordPress 5.4+ and PHP 7.0+.

1. Download wp-freighter.zip and upload it under Plugins → Add New, or install it from the command line:

   wp plugin install --activate \
     https://github.com/WPFreighter/wp-freighter/releases/latest/download/wp-freighter.zip

2. Open Tools → WP Freighter. On first run the plugin writes wp-content/freighter.php (the bootstrap) and adds one require_once line to wp-config.php, right after $table_prefix.
3. Pick a files mode and add your first tenant site. That's the whole setup.

Hosts that lock wp-config.php

If the plugin cannot write those two files it says so and shows the exact bootstrap contents and the one-line include to paste yourself, or to hand to your host. Nothing else in WordPress core is touched. Updates arrive through the plugin's own updater, which reads the release manifest from GitHub.

Files modes

Every tenant site always has its own database tables under stacked_<id>_. The files mode decides how much of wp-content is shared. Switch it any time with Tools → WP Freighter or wp freighter files set <mode>.

Shared

One wp-content/ for everyone: plugins, themes and uploads. Right for brand variants or language editions built from the same assets.

Hybrid

Plugins and themes come from wp-content/; each site's media lives in content/<id>/uploads/. Update a plugin once for every site while keeping libraries separate. The default for most people.

Dedicated

Each site gets a whole content/<id>/: its own plugins, themes and uploads. Full isolation, so a plugin update can be trialled on one site without touching the others.

Changing mode does not move files. Going from shared to hybrid, for example, gives new uploads their own folder while existing media stays where it is.

Tenant sites

Create

Add an empty site with a title, a label (or a domain when mapping is on) and an administrator. Only database tables are created, so it is ready in a few seconds. The new site gets a theme it can load: the default theme when the host has it, otherwise the main site's theme; dedicated sites download the default theme into their own folder.

Clone

Clone the main site or any tenant. The source's tables are copied to a new prefix; in hybrid and dedicated mode its content folder is copied too. Internal URLs are rewritten to the new site. This is the staging move: clone production, work in the clone, delete it when done.

Switch

Administrators move between sites from the admin bar. Switching sets a stacked_site_id cookie that the bootstrap reads on the next request; the cookie is only honoured alongside a valid login cookie, so it cannot be used to reach a site you are not signed in to. "Exit" returns you to the main site.

Magic login

Each site has a one-time login link that drops you straight into its dashboard as its administrator. Generate one from the site list, or from the command line with wp freighter login <id>.

Delete

Deleting drops the site's tables and, in hybrid and dedicated mode, removes its content/<id>/ folder. The dialog shows how much is about to go. There is no undo, so clone first if in doubt.

Self-healing

Before switching into a tenant the plugin checks it is present and active there and restores itself if someone deleted or deactivated it from inside the child site.

Domain mapping

With domain mapping off, tenants ride on the host's domain and are reached through the admin switcher or magic login. Good for sandboxes and staging.

With domain mapping on, each tenant is addressed by its own hostname: the bootstrap matches the requested host against the mapping list and loads that tenant. Point the domain's DNS at the host and add it to the server or hosting account so requests actually arrive at this WordPress install; WP Freighter routes from there. Toggle with wp freighter domain set on|off.

WP-CLI

Everything the Tools page does is also a wp freighter command.

Running any command inside a tenant

WP-CLI's --url is not how tenants are selected. Set STACKED_SITE_ID in the environment and every wp command runs against that site:

STACKED_SITE_ID=15 wp option get home
STACKED_SITE_ID=15 wp plugin update --all

Combined with list --format=ids, that is a fleet update in three lines:

for id in $(wp freighter list --format=ids); do
  STACKED_SITE_ID=$id wp plugin update --all
done

WP-Cron only runs when a site gets traffic, so for quiet tenants schedule the same loop with wp cron event run --due-now.

PHP API

The same operations are static methods on WPFreighter\Site, for provisioning from your own code.

// Create. Returns an array with 'stacked_site_id', or WP_Error.
$site = \WPFreighter\Site::create( [
    'title'    => 'Project Alpha',
    'name'     => 'alpha',               // label
    'domain'   => 'alpha.example.com',   // optional, needs domain mapping on
    'username' => 'admin',
    'email'    => 'admin@example.com',
    'password' => 'optional, generated if omitted',
] );

// Clone the main site, or a tenant by ID.
$staging = \WPFreighter\Site::clone( 'main', [ 'name' => 'Staging' ] );
$copy    = \WPFreighter\Site::clone( 5, [ 'name' => 'Copy of 5' ] );

// One-time login URL, optionally landing on a specific admin screen.
$url = \WPFreighter\Site::login( 2 );
$url = \WPFreighter\Site::login( 2, 'post-new.php' );

// Delete.
\WPFreighter\Site::delete( 4 );

The admin screen talks to the same code through REST routes under wp-freighter/v1, which require a logged-in administrator.

Questions

Limitations

Tenants share one install, so they share the things an install has only one of.

• wp-config.php has to be writable, or editable by you. The bootstrap include is the one hook into WordPress. If a host forbids both automatic and manual edits to wp-config.php, WP Freighter cannot run there.
• Root files are shared. .htaccess, robots.txt, anything in the web root, and the WordPress core version are the same for every tenant. If a tenant needs its own root-level folder, put it under content/<id>/ and add a redirect with the Redirection plugin: for example /presentations/ to /content/1/presentations/.
• One PHP, one server, one database. Tenants are separate sites, not separate machines. Size the host for the sum of them, and remember one backup covers them all.
• WP-Cron depends on traffic. A quiet tenant's scheduled tasks wait for a visitor. Drive them with a system cron and STACKED_SITE_ID=<id> wp cron event run --due-now.

Videos

Recorded for the 1.0 release in 2020. The admin screen has been redesigned since, but the ideas and the hosting walkthroughs still hold.

• Introducing WP Freighter
• Walkthrough with GridPane
• Walkthrough with Kinsta
• Overview with Local