Deploying a Forme site ​

This is fairly similar to your local setup, but with a few differences for the remote server. This will depend on your specific server setup to a certain extent so YMMV.

Assumptions ​

• PHP ^8.1
• wp cli
• node 18.x lts/hydrogen (if using Forme Base)

Deploying Forme Themes and Plugins ​

You will need to make sure your project directories make their way into the themes and plugins folders as appropriate, nothing different there. How you achieve that is completely up to you - you can scp or even (s)ftp them up like it's the 90s, although we heartily recommend publishing them to packagist so you can use composer and a Forme base installation repo.

If you're using Forme for non open source work and you need to keep your projects private, you should consider setting up your own Satis instance. Check out Satisfy for a solution that's straightforward to set up.

After they are deployed, you then activate them in the usual way via the admin or wp-cli.

Deploying a Forme site with Forme Base ​

If you've used Forme Base for your local dev environment, then by far the best solution is to use this same repo for your deployment too.

On a server you typically need to:

• copy or git clone your base install repo to a new directory
• cd into the directory and run composer setup-wordpress
• Run composer install --no-dev and any other local scripts you need
• Update WP_ENV in public/wp-config.php to something other than development
• Run composer init-dotenv and then fill .env in
• Make public the web root, or symlink public to your existing web root path

You should require your custom themes and plugins as composer dependencies - npm workspaces configuration will handle running npm run build across all of them if relevant.

npm workspaces ​

npm Workspaces allow us to automate npm installations and asset builds from the server root across all plugins and themes. It's specifically configured to trigger those whose directory name end with -plugin and -theme respectively (as is default for Forme), and that have a package.json with a build command defined.

npm install will run in all matching themes and plugins.

npm run build -ws will run npm run build in all matching themes and plugins.

These commands should run automatically on every composer update/install via the post-update-cmd and post-install-cmd hooks, but you can also run them directly from the command line.

You can checkout out the base installation's composer.json and package.json to see what's going on under the hood.

Deploying a Forme site Without Forme Base ​

composer.json ​

Alternatively, you should be able to copy the composer.json from your local development install. You'll need to make sure the various path refs match what's actually on the server if it's any different.

You should run all composer commands from the root directory, usually one up from public.

You can edit the composer file or composer require all plugins, themes and libraries that you need.

Then you can run composer install (or more usually for a production server composer install --no-dev if you don't want dev libraries to be installed)

wp-config.php ​

Straight after ABSPATH, you need to define FORME_PRIVATE_ROOT with the root directory. On the server, this will be one level up from your public folder (i.e. one up from ABSPATH).

define('FORME_PRIVATE_ROOT', ABSPATH . '../');

You should then require the autoload just after that definition.

require_once FORME_PRIVATE_ROOT . 'vendor//autoload.php';

You can also set WP_ENV to development if required (not for production though!)

define ('WP_ENV', 'development');

The framework uses this to determine whether Whoops should be enabled amongst other things.

Further Configuration ​

.htaccess ​

Add the htaccess directives below (after the wordpress stuff) to make the composer json and any files in code related directories inaccessible.

## Forme - Prevent code and config leaks

<IfModule mod_rewrite.c>
RewriteRule (?:^|/).*/composer\.(lock|json)$ / [F,L]
RewriteRule (?:^|/).*/app/.*$ - [F,L]
RewriteRule (?:^|/).*/assets/src/.*$ - [F,L]
RewriteRule (?:^|/).*/scripts/.*$ - [F,L]
RewriteRule (?:^|/).*/helpers/.*$ - [F,L]
RewriteRule (?:^|/).*/routes/.*$ - [F,L]
RewriteRule (?:^|/).*/views/.*$ - [F,L]
</IfModule>

You'll need to translate these to nginx directives if you're using it without apache.

forme.env ​

This is the global .env file for all your Forme plugins and themes, and lives in your FORME_PRIVATE_ROOT directory. If it doesn't exist, you can create it. It should be named either forme.env or .env. If both of them exist, forme will use forme.env

Copy over the environment variables from the forme.env.example file of any plugins and themes you want to activate, and define them in here.

Job Queue Cron ​

If any of your activated plugins or themes use the job queue, you'll need to set up a cron job to trigger it. Add the following task and set it to run once a minute:

cd /path/to/your-base-installation/ && php wrangle queue:run >> /dev/null 2>&1

This assumes you have wrangle appropriately symlinked in your base installation.

Installing packages ​

You should run all composer commands from the root directory.

You can edit the composer file or composer require any plugins, themes and libraries that you need.

For production or staging server composer install --no-dev (this means the dev utilities won't get installed)

For dev server composer install (this means the dev utilities will get installed)

Updating plugins, themes and libraries ​

Plugins and themes can be updated in the WordPress admin in the normal way, or you can use composer on the server depending on how you set them up, in which case you would need to run composer update vendor/package.

For private plugins and themes, you will need to update those on the server, since by definition you won't be using the public WordPress directory. How you update those will depend on your specific setup - scp, sftp will work fine but ideally you should publish to a private packagist repository of some sort and use composer. We don't really advise pushing anything to a public web directory with git for security reasons - you could mitigate that with additional htaccess rules but better to avoid it altogether.

You will need to manually deactivate and reactivate plugins and themes if any schema migrations need to be run.

For standard php libraries (i.e. not WordPress themes or plugins), updating will of course always need to be done via the server and composer.