Deploying WP SSR Framework — Production Setup Checklist

Deploying the WP SSR framework means wiring together a Bedrock-structured WordPress backend and a Vite-compiled React SPA that consumes it. Because configuration is fully environment-driven there is no code to change between environments — only .env values. The checklist below covers a complete production setup from an empty server to a running site.

ACF Pro is required. The options-page and field-group APIs depend on Advanced Custom Fields Pro (acf/acf). The free version from wordpress.org does not include the acf_add_options_page() function or the extended field group API. Ensure ACF Pro is installed in web/app/plugins/ before activating the framework.

1 — Environment Setup

Copy and fill .env

Copy the example file to .env in the project root, then fill in every required variable:

cp .env.example .env

Minimum required values for production:

DB_NAME='my_db'
DB_USER='my_user'
DB_PASSWORD='my_password'

WP_ENV='production'
WP_HOME='https://example.com'
WP_SITEURL="${WP_HOME}/wp"

WEB_RENDER_TOKEN='tok_live_xxxxxxxxxx'
HEALTH_ENDPOINT_TOKEN='xxxxxxxxxxxxxxxx'

See the Environment Variables reference for the full list.

Generate WordPress salts

Visit roots.io/salts.html and paste the generated block into .env:

AUTH_KEY='...'
SECURE_AUTH_KEY='...'
LOGGED_IN_KEY='...'
NONCE_KEY='...'
AUTH_SALT='...'
SECURE_AUTH_SALT='...'
LOGGED_IN_SALT='...'
NONCE_SALT='...'

Never reuse salts from another environment. Each server should have its own unique set.

2 — Install Dependencies

Install PHP dependencies

Run Composer with production flags to skip dev packages and optimise the autoloader:

composer install --no-dev --optimize-autoloader

WordPress core, plugins, and the wp-ssr mu-plugin are all managed by Composer and will be placed in the correct Bedrock directories automatically per composer.json:

"installer-paths": {
  "web/app/mu-plugins/{$name}/": ["type:wordpress-muplugin"],
  "web/app/plugins/{$name}/":    ["type:wordpress-plugin"],
  "web/app/themes/{$name}/":     ["type:wordpress-theme"]
},
"wordpress-install-dir": "web/wp"

Build the Vite client

Install Node dependencies and produce a production build of the React SPA:

cd web/client
yarn install
yarn build

The compiled assets are written to web/client/dist/. The framework’s Vite SSR class reads the manifest at web/client/dist/.vite/manifest.json to inject hashed asset URLs into the document.

3 — Web Server Configuration

Set the document root

Point your web server’s document root to the web/ directory. All requests must be routed through web/index.php (standard WordPress setup).

Nginx
Apache

server {
    listen 443 ssl;
    server_name example.com;
    root /var/www/project/web;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

<VirtualHost *:443>
    ServerName example.com
    DocumentRoot /var/www/project/web

    <Directory /var/www/project/web>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Understand the framework rewrites

The AppServiceProvider registers two important rewrite rules inside WordPress:

Incoming path	Resolves to	Purpose
`/api/v1/*`	`index.php?rest_route=/api/v1/$matches[1]`	Maps clean `/api/v1/` URLs to the WP REST API
`/admin`	`wp-login.php`	Provides a clean admin URL

Static cache files generated during SSG pre-rendering are served from:

web/app/cache/client/static/

Ensure your web server user has write permission to this directory.

4 — WordPress Setup

Install WordPress core

Run the standard WP-CLI install command (the wp-cli.yml in the project root pre-configures --path=web/wp):

wp core install \
  --url="https://example.com" \
  --title="My Site" \
  --admin_user="admin" \
  --admin_password="secure_password" \
  --admin_email="admin@example.com"

Alternatively, visit https://example.com/wp/wp-admin/install.php in a browser.

Activate required plugins

ACF Pro must be present in web/app/plugins/ (install it by adding it to composer.json or uploading the zip). Activate it along with any other plugins:

wp plugin activate advanced-custom-fields-pro

Mu-plugins in web/app/mu-plugins/ (including wp-ssr itself) are loaded automatically by WordPress — they do not need to be activated.

Flush rewrite rules

After first setup, regenerate the WordPress rewrite rules so the /api/* and /admin rewrites registered by AppServiceProvider take effect:

wp rewrite flush

5 — Initial Page Sync

Once WordPress is running and all plugins are active, sync the code-defined routes to WordPress pages. Because WP_ENV=production disables automatic page registration, this step is required after every fresh deployment or route change:

wp pages:sync

Expected output:

Registered page Accueil
Registered page Agence
Registered page Devis
Registered page Contact
Registered page Services
Registered page Réalisations
Registered page Blog

See the WP-CLI reference for details on how this command works.

6 — SSG Pre-Generation

The framework supports pre-rendering pages to static HTML via an external render API. This step is optional but recommended for optimal Time to First Byte on public-facing pages.

Ensure WEB_RENDER_TOKEN is set

The render API at api.ahon.dev authenticates requests with a Bearer token. Confirm it is present in .env:

WEB_RENDER_TOKEN='tok_live_xxxxxxxxxx'

Trigger pre-generation

WP Admin
REST API

Navigate to WP Admin → SSG → Generate All Pages and click the generate button. Progress is displayed in-page as each route is rendered and cached.

# Obtain a nonce first (must be authenticated)
NONCE=$(wp eval 'echo wp_create_nonce("wp_rest");')

curl -X POST https://example.com/api/v1/ssg/all \
  -H "X-WP-Nonce: ${NONCE}" \
  -H "Content-Type: application/json"

Pre-generated static files are cached in web/app/cache/client/static/. Invalidate the cache after publishing content changes either through the WP Admin SSG panel or by deleting files from that directory.

Full Post-Deploy Command Sequence

For convenience, here is the complete command sequence for a typical zero-downtime deployment after code changes:

# 1. Pull latest code (handled by your CI/CD)

# 2. Install/update PHP dependencies
composer install --no-dev --optimize-autoloader

# 3. Build frontend assets
cd web/client && yarn install && yarn build && cd -

# 4. Run database migrations (if any)
wp core update-db --network 2>/dev/null || wp core update-db

# 5. Regenerate post-type classes
wp eloquent:generate

# 6. Sync routes to WordPress pages
wp pages:sync

# 7. Flush rewrite rules
wp rewrite flush

# 8. Trigger SSG cache refresh (requires authenticated nonce)
NONCE=$(wp eval 'echo wp_create_nonce("wp_rest");')
curl -s -X POST https://example.com/api/v1/ssg/all \
  -H "X-WP-Nonce: ${NONCE}" \
  -H "Content-Type: application/json"

Getting Started

Core Concepts

Features

Frontend

Configuration & Deployment

Deploying WP SSR Framework — Production Setup Checklist

1 — Environment Setup

2 — Install Dependencies

3 — Web Server Configuration

4 — WordPress Setup

5 — Initial Page Sync

6 — SSG Pre-Generation

Full Post-Deploy Command Sequence

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Features

Frontend

Configuration & Deployment

Documentation Index

​1 — Environment Setup

​2 — Install Dependencies

​3 — Web Server Configuration

​4 — WordPress Setup

​5 — Initial Page Sync

​6 — SSG Pre-Generation

​Full Post-Deploy Command Sequence

Build docs developers (and LLMs) love

1 — Environment Setup

2 — Install Dependencies

3 — Web Server Configuration

4 — WordPress Setup

5 — Initial Page Sync

6 — SSG Pre-Generation

Full Post-Deploy Command Sequence