| 1 |
# Deployment Guide |
| 2 |
|
| 3 |
CartFlows is deployed as a standard WordPress plugin. Build artifacts are committed to the repository, so no CI build step is required during deployment. |
| 4 |
|
| 5 |
## Pre-deployment Checklist |
| 6 |
|
| 7 |
Before deploying a new version, complete these steps: |
| 8 |
|
| 9 |
### 1. Code Quality |
| 10 |
|
| 11 |
```bash |
| 12 |
# PHP standards |
| 13 |
composer lint # Must pass with 0 errors |
| 14 |
composer phpstan # Must pass with 0 errors |
| 15 |
composer test # All tests must pass |
| 16 |
|
| 17 |
# JavaScript |
| 18 |
npm run lint-js # Must pass |
| 19 |
npm run lint-css # Must pass |
| 20 |
npm run pretty # Must pass |
| 21 |
``` |
| 22 |
|
| 23 |
### 2. Build Assets |
| 24 |
|
| 25 |
```bash |
| 26 |
# Build all compiled assets |
| 27 |
npm run all-builds |
| 28 |
``` |
| 29 |
|
| 30 |
Verify the following files are updated in `admin-core/assets/build/`: |
| 31 |
- `editor-app.js` |
| 32 |
- `editor-app.css` |
| 33 |
- `editor-app.asset.php` |
| 34 |
- `settings-app.js` |
| 35 |
- `settings-app.css` |
| 36 |
- `settings-app.asset.php` |
| 37 |
|
| 38 |
**These files must be committed to the repo before deployment.** |
| 39 |
|
| 40 |
### 3. Version Bump |
| 41 |
|
| 42 |
Update the version number in: |
| 43 |
|
| 44 |
| File | Field | |
| 45 |
|------|-------| |
| 46 |
| `cartflows.php` | `Version:` plugin header | |
| 47 |
| `cartflows.php` | `CARTFLOWS_VER` constant | |
| 48 |
| `package.json` | `version` field | |
| 49 |
| `readme.txt` | `Stable tag:` | |
| 50 |
|
| 51 |
### 4. Changelog |
| 52 |
|
| 53 |
Update `readme.txt` with the release changelog entry. |
| 54 |
|
| 55 |
### 5. Testing |
| 56 |
|
| 57 |
Run E2E tests against a staging environment: |
| 58 |
|
| 59 |
```bash |
| 60 |
npm run env:start |
| 61 |
npm run test:e2e |
| 62 |
npm run env:stop |
| 63 |
``` |
| 64 |
|
| 65 |
Manually verify: |
| 66 |
- [ ] Flow creation works |
| 67 |
- [ ] Step creation (checkout, optin, landing, thank you) |
| 68 |
- [ ] Checkout form submits correctly |
| 69 |
- [ ] Order bump appears and processes |
| 70 |
- [ ] Analytics dashboard loads |
| 71 |
- [ ] Global settings save correctly |
| 72 |
- [ ] Template import works |
| 73 |
|
| 74 |
--- |
| 75 |
|
| 76 |
## Deployment Methods |
| 77 |
|
| 78 |
### Method 1: Direct File Upload (FTP/SFTP) |
| 79 |
|
| 80 |
1. Run `npm run all-builds` locally |
| 81 |
2. Commit and push all changes including build assets |
| 82 |
3. Upload the plugin directory to `wp-content/plugins/cartflows/` on the server |
| 83 |
4. In WordPress admin: deactivate and reactivate the plugin if needed |
| 84 |
|
| 85 |
### Method 2: WordPress Plugin Updater |
| 86 |
|
| 87 |
CartFlows ships with a built-in update mechanism (`class-cartflows-update.php`) that checks for new versions from the CartFlows API. For self-hosted (pro) deployments: |
| 88 |
|
| 89 |
1. Tag the release in git |
| 90 |
2. Upload the plugin ZIP to the update server |
| 91 |
3. WordPress installs will receive the update notification automatically |
| 92 |
|
| 93 |
### Method 3: Deployment via CI/CD |
| 94 |
|
| 95 |
Since build artifacts are committed, CI deployment simply needs to: |
| 96 |
|
| 97 |
1. Checkout the repository |
| 98 |
2. Rsync/deploy files to the server (no build step required) |
| 99 |
3. Optionally run `composer install --no-dev` for production dependencies |
| 100 |
|
| 101 |
```yaml |
| 102 |
# Example CI step |
| 103 |
- name: Deploy plugin |
| 104 |
run: | |
| 105 |
rsync -av --exclude='.git' --exclude='node_modules' --exclude='tests' \ |
| 106 |
./ user@server:/var/www/wp-content/plugins/cartflows/ |
| 107 |
``` |
| 108 |
|
| 109 |
--- |
| 110 |
|
| 111 |
## Post-deployment Verification |
| 112 |
|
| 113 |
After deploying: |
| 114 |
|
| 115 |
1. **Admin dashboard** — Verify CartFlows admin menu loads |
| 116 |
2. **React apps** — Verify the flow editor and settings app load without console errors |
| 117 |
3. **Checkout** — Complete a test purchase through a CartFlows funnel |
| 118 |
4. **API** — Verify REST endpoints respond: `/wp-json/cartflows/v1/flows` |
| 119 |
|
| 120 |
--- |
| 121 |
|
| 122 |
## Rollback Procedure |
| 123 |
|
| 124 |
If a deployment causes issues: |
| 125 |
|
| 126 |
1. Identify the last working git commit/tag |
| 127 |
2. Deploy that version using the same method as above |
| 128 |
3. If the database was migrated, check `class-cartflows-update.php` for rollback considerations |
| 129 |
4. Deactivate and reactivate the plugin to re-run activation hooks |
| 130 |
|
| 131 |
--- |
| 132 |
|
| 133 |
## Production Considerations |
| 134 |
|
| 135 |
### PHP Configuration |
| 136 |
|
| 137 |
Recommended server PHP settings: |
| 138 |
|
| 139 |
| Setting | Minimum | Recommended | |
| 140 |
|---------|---------|-------------| |
| 141 |
| `max_execution_time` | 60 | 120 | |
| 142 |
| `memory_limit` | 128M | 256M | |
| 143 |
| `upload_max_filesize` | 32M | 64M | |
| 144 |
| `post_max_size` | 32M | 64M | |
| 145 |
|
| 146 |
### Asset Serving |
| 147 |
|
| 148 |
Build assets in `admin-core/assets/build/` are static files. Configure your server/CDN to: |
| 149 |
- Set long cache TTL for `.js` and `.css` files (they are versioned via asset.php) |
| 150 |
- Serve with gzip/Brotli compression |
| 151 |
|
| 152 |
### Database |
| 153 |
|
| 154 |
CartFlows uses standard WordPress tables (`wp_posts`, `wp_postmeta`, `wp_options`). No custom tables are created. The main performance consideration is: |
| 155 |
- Index on `wp_posts.post_type` (standard WP behaviour) |
| 156 |
- `wp_postmeta` queries for flow/step settings (cached via object cache if available) |
| 157 |
|
| 158 |
### Caching |
| 159 |
|
| 160 |
CartFlows is compatible with standard WordPress caching plugins. If you use full-page caching: |
| 161 |
- Exclude checkout pages (`wcf-step` post type with checkout type) |
| 162 |
- Exclude cart and order confirmation pages from page caching |
| 163 |
|
| 164 |
--- |
| 165 |
|
| 166 |
## Plugin Activation / Deactivation |
| 167 |
|
| 168 |
### On Activation |
| 169 |
|
| 170 |
`register_activation_hook( CARTFLOWS_FILE, ... )` handles: |
| 171 |
- Creating default flows/steps if needed |
| 172 |
- Setting default options |
| 173 |
- Flushing rewrite rules (for CPT permalinks) |
| 174 |
|
| 175 |
### On Deactivation |
| 176 |
|
| 177 |
`register_deactivation_hook( CARTFLOWS_FILE, ... )` handles: |
| 178 |
- Flushing rewrite rules |
| 179 |
- Cleaning up transients |
| 180 |
|
| 181 |
### On Uninstall |
| 182 |
|
| 183 |
Uninstall logic (if defined) would remove plugin options and custom post type data. |
| 184 |
|
| 185 |
--- |
| 186 |
|
| 187 |
## Related Pages |
| 188 |
|
| 189 |
- [](Build-SystemBuild-System](Build-System](Build-System) |
| 190 |
- [](Testing-GuideTesting-Guide](Testing-Guide](Testing-Guide) |
| 191 |
- [](Environment-ConfigurationEnvironment-Configuration](Environment-Configuration](Environment-Configuration) |
| 192 |
- [](Contributing-GuideContributing-Guide](Contributing-Guide](Contributing-Guide) |
| 193 |
- [](Troubleshooting-FAQTroubleshooting-FAQ](Troubleshooting-FAQ](Troubleshooting-FAQ) |
| 194 |
|
