diff --git a/docs/build/03-guides/_category_.json b/docs/build/03-guides/_category_.json new file mode 100644 index 00000000..8abec922 --- /dev/null +++ b/docs/build/03-guides/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Guides", + "position": 3, + "link": { + "type": "generated-index", + "description": "Step-by-step guides for integrating Quilibrium services with popular platforms and tools" + } +} diff --git a/docs/build/03-guides/wordpress-backups-with-qstorage.md b/docs/build/03-guides/wordpress-backups-with-qstorage.md new file mode 100644 index 00000000..4e642328 --- /dev/null +++ b/docs/build/03-guides/wordpress-backups-with-qstorage.md @@ -0,0 +1,240 @@ +--- +sidebar_position: 1 +title: WordPress Backups with QStorage +description: Store WordPress media uploads and backups on QStorage using the S3-compatible API with the S3 Uploads plugin. +keywords: [wordpress, backups, qstorage, s3, media uploads, object storage, wp-cli] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# WordPress Backups with QStorage + +QStorage is fully compatible with the S3 API, which means you can use battle-tested WordPress plugins to offload your media library and backups to decentralized, encrypted storage on the Quilibrium network. + +This guide walks through setting up the [S3 Uploads](https://github.com/humanmade/S3-Uploads) plugin by Human Made to store all WordPress uploads directly on QStorage instead of the local filesystem. + +## Why Use QStorage for WordPress? + +- **Decentralized storage** — your media is distributed across the Quilibrium network, not locked to a single cloud provider +- **S3-compatible** — drop-in replacement that works with existing S3 tooling and plugins +- **Built-in encryption** — all objects stored in QStorage are encrypted via QKMS by default +- **Scalable** — no need to worry about disk space on your web server + +## Prerequisites + +Before you begin, make sure you have: + +1. A running WordPress installation (WordPress >= 5.3) +2. [Composer](https://getcomposer.org/) installed on your server +3. [WP-CLI](https://wp-cli.org/) installed (recommended) +4. PHP >= 7.4 +5. QStorage credentials from [QConsole](https://console.quilibrium.com) — see [Setting Up Credentials](/docs/api/q-storage/user-manual/credentials) for details + +You will need the following credentials: + +| Credential | Description | Example | +|---|---|---| +| Access Key ID | Alphanumeric string from QConsole | `ABCDEF12D213546709A` | +| Secret Key | Secret access key string | `AbcdI32/daY+jjad4M...` | +| Endpoint | QStorage API endpoint | `https://qstorage.quilibrium.com` | +| Region | QStorage region | `q-world-1` | + +## Step 1: Install S3 Uploads + +Install the S3 Uploads plugin via Composer in your WordPress project root: + +```bash +composer require humanmade/s3-uploads +``` + +:::important +Composer's autoloader must be loaded before WordPress loads. +Add the following line to your `wp-config.php` **before** the line that requires `wp-settings.php`: +::: + +```php +require_once __DIR__ . '/vendor/autoload.php'; +``` + +## Step 2: Configure QStorage Credentials + +Add the following constants to your `wp-config.php` file, replacing the placeholder values with your QStorage credentials from QConsole: + +```php +/** QStorage Configuration */ +define( 'S3_UPLOADS_BUCKET', 'my-wp-backups' ); +define( 'S3_UPLOADS_REGION', 'q-world-1' ); +define( 'S3_UPLOADS_KEY', 'your-access-key-id' ); +define( 'S3_UPLOADS_SECRET', 'your-secret-access-key' ); +``` + +:::tip +You can use a path prefix within your bucket to organize uploads. +For example, to store all files under a `wp-uploads/` folder inside your bucket: + +```php +define( 'S3_UPLOADS_BUCKET', 'my-wp-backups/wp-uploads' ); +``` +::: + +## Step 3: Configure the QStorage Endpoint + +S3 Uploads defaults to Amazon S3 endpoints. +To point it at QStorage, create a [must-use plugin](https://developer.wordpress.org/advanced-administration/plugins/mu-plugins/) file at `wp-content/mu-plugins/qstorage-endpoint.php`: + +```php += 3.337, these settings prevent compatibility errors. +::: + +## Step 4: Configure URL Rewrites + +By default, S3 Uploads rewrites media URLs to point to S3. +To serve your media from QStorage, set the bucket URL in `wp-config.php`: + +```php +define( 'S3_UPLOADS_BUCKET_URL', 'https://my-wp-backups.qstorage.quilibrium.com' ); +``` + +This rewrites all media URLs from your local `/wp-content/uploads/` path to your QStorage bucket URL. + +:::tip +If you use a CDN or reverse proxy in front of QStorage, set `S3_UPLOADS_BUCKET_URL` to your CDN origin URL instead. +::: + +## Step 5: Activate and Verify + + + + +Activate the plugin and verify the connection: + +```bash +wp plugin activate s3-uploads +``` + +```bash +wp s3-uploads verify +``` + +If the connection is successful, you will see a confirmation message. +All new media uploads will now be stored directly on QStorage. + + + + +1. Navigate to **Plugins** in your WordPress admin dashboard +2. Find **S3 Uploads** in the plugin list +3. Click **Activate** + +To verify the connection, use WP-CLI as shown in the WP-CLI tab, or upload a test image through the Media Library and confirm it appears in your QStorage bucket via [QConsole](https://console.quilibrium.com). + + + + +## Migrating Existing Media to QStorage + +If you have an existing media library on local disk, use WP-CLI to copy everything to QStorage: + +```bash +wp s3-uploads upload-directory /path/to/wp-content/uploads/ uploads +``` + +This copies all files from your local uploads directory to the `uploads/` prefix in your QStorage bucket. + +You can also copy individual files: + +```bash +wp s3-uploads cp ./backup.sql s3://my-wp-backups/backups/backup.sql +``` + +## Optional: Private Uploads + +By default, uploaded objects are publicly readable. +To make all uploads private (requiring signed URLs for access), add the following to your theme's `functions.php` or a custom plugin: + +```php +add_filter( 's3_uploads_is_attachment_private', '__return_true' ); +``` + +Private files are served via temporarily signed URLs that expire after 6 hours. +You can customize the expiry: + +```php +add_filter( 's3_uploads_private_attachment_url_expiry', function ( $expiry ) { + return '+1 hour'; +} ); +``` + +## Optional: Cache Control Headers + +Set cache headers for uploaded media to improve performance: + +```php +define( 'S3_UPLOADS_HTTP_CACHE_CONTROL', 30 * 24 * 60 * 60 ); +``` + +This sets a 30-day `Cache-Control` header on all uploaded objects. + +## Full wp-config.php Example + +Here is a complete example of all the QStorage-related configuration in `wp-config.php`: + +```php +/** Load Composer autoloader (must be before wp-settings.php) */ +require_once __DIR__ . '/vendor/autoload.php'; + +/** QStorage Configuration */ +define( 'S3_UPLOADS_BUCKET', 'my-wp-backups' ); +define( 'S3_UPLOADS_REGION', 'q-world-1' ); +define( 'S3_UPLOADS_KEY', 'ABCDEF12D213546709A' ); +define( 'S3_UPLOADS_SECRET', 'AbcdI32/daY+jjad4M...' ); +define( 'S3_UPLOADS_BUCKET_URL', 'https://my-wp-backups.qstorage.quilibrium.com' ); +define( 'S3_UPLOADS_HTTP_CACHE_CONTROL', 30 * 24 * 60 * 60 ); +``` + +## Troubleshooting + +### Connection Errors + +If `wp s3-uploads verify` fails: + +1. Double-check your Access Key ID and Secret Key in `wp-config.php` +2. Confirm the endpoint is set to `https://qstorage.quilibrium.com` in your mu-plugin +3. Ensure `use_path_style_endpoint` is set to `true` +4. Set `$params['debug'] = true;` in your mu-plugin to enable verbose logging + +### Upload Failures + +If uploads fail silently: + +1. Check PHP error logs for S3 client exceptions +2. Verify your bucket exists — create one via [QConsole](https://console.quilibrium.com) or the [QStorage API](/docs/api/q-storage/user-manual/working-with-buckets/creating-a-bucket) +3. Ensure your credentials have write permissions on the target bucket + +### URL Rewrite Issues + +If media URLs still point to the local filesystem: + +1. Verify `S3_UPLOADS_BUCKET_URL` is set correctly +2. Clear any caching plugins or CDN caches +3. Regenerate thumbnails with `wp media regenerate` if needed + +## Next Steps + +- [Create a Bucket](/docs/api/q-storage/user-manual/working-with-buckets/creating-a-bucket) in QStorage +- [Setting Up Credentials](/docs/api/q-storage/user-manual/credentials) for QStorage +- [QStorage User Manual](/docs/api/q-storage/user-manual/getting-started) for full documentation +- [S3 Uploads Plugin Documentation](https://github.com/humanmade/S3-Uploads) on GitHub