Below is our formal document, written as a combined overview + implementation specification, using practical examples while keeping it reusable. This is not intended to be a final document or exhaistvie.

WordPress Media Library CDN Integration

Infrastructure Prerequisites & AWS Configuration (nginx / Debian 13 / Linode)

1. Overview

This document outlines the infrastructure and AWS configuration required to support a custom WordPress Media Library integration using an S3-backed CDN via CloudFront.

It is written for engineers with solid general IT skills and working knowledge of:

• AWS services (S3, CloudFront, IAM, ACM, Route/DNS concepts)
• Linux systems (Debian-based)
• nginx and PHP-FPM
• DNS management

While this implementation is based on:

• Debian 13 (Linode/Akamai)
• nginx + PHP 8.4-FPM

…the architectural principles apply broadly (e.g. Apache2 or Amazon EC2 with IAM Roles). Alternative platform notes may be added in later revisions.

2. Architecture Summary

At a high level, the system works as follows:

User Browser
     ↓
cdn.DOMAIN_NAME (CloudFront)
     ↓
S3 Bucket (media storage)
     ↑
WordPress (uploads via IAM credentials)

Key Components

3. Environment & Naming Conventions

To keep documentation reusable, the following placeholders are used:

4. Base Server Prerequisites (High-Level)

Before integrating AWS services, the following must already be working:

4.1 Web Stack

• nginx installed and configured
• PHP 8.4-FPM (with tuned www.conf, opcache, memory settings)
• MariaDB configured and optimised
• WordPress installed and functioning

4.2 SSL (Origin Server)

• Let’s Encrypt certificates for:
  • DOMAIN_NAME
  • www.DOMAIN_NAME
• Automated renewal (certbot)

4.3 Supporting Services (Recommended)

• Memcached (or Redis)
• phpMyAdmin (optional)
• Proper file permissions for WordPress

Note: These are prerequisites. This document does not cover their setup in detail.

5. DNS Configuration

All DNS entries should be set to DNS only (no proxying) with a TTL of ~1 hour unless otherwise required.

5.1 Core A Records

A     DOMAIN_NAME        LINODE_IPV4
A     www                LINODE_IPV4

5.2 CAA Records (Certificate Authority Restrictions)

CAA   DOMAIN_NAME   0 issue "letsencrypt.org"
CAA   DOMAIN_NAME   0 issue "amazontrust.com"
CAA   DOMAIN_NAME   0 issuewild "letsencrypt.org"
CAA   DOMAIN_NAME   0 issuewild "amazontrust.com"
CAA   DOMAIN_NAME   0 iodef "mailto:admin@DOMAIN_NAME"

5.3 CDN (CloudFront) DNS

CNAME CDN_DOMAIN    CLOUDFRONT_DOMAIN

Example:

cdn.example.com → dxxxxxxxxxxxx.cloudfront.net

5.4 ACM Validation Record (Required)

Created automatically by AWS Certificate Manager:

CNAME _TOKEN.CDN_DOMAIN → _VALIDATION.acm-validations.aws

5.5 SES (Email) DNS Records (Referenced Only)

These are required if using AWS SES:

MX   DOMAIN_NAME        inbound-smtp.REGION.amazonaws.com
MX   mail.DOMAIN_NAME   feedback-smtp.REGION.amazonses.com

TXT  DOMAIN_NAME        "v=spf1 include:amazonses.com ~all"
TXT  mail.DOMAIN_NAME   "v=spf1 include:amazonses.com ~all"

TXT  _dmarc.DOMAIN_NAME "v=DMARC1; p=none;"

Additional SES domain verification CNAME records are also required.

Full SES setup is outside the scope of this document but must exist.

6. AWS Region Strategy (Important)

AWS services used in this setup span multiple regions:

Key Notes

• CloudFront only supports ACM certificates from us-east-1
• S3 should be closest to your origin/server
• SES region is chosen based on availability (not all regions support SES)

7. AWS Certificate Manager (ACM)

Create a certificate for:

CDN_DOMAIN

Steps (Summary)

1. Request public certificate
2. Use DNS validation
3. Add provided CNAME record to DNS
4. Wait for validation

8. S3 Bucket Configuration

8.1 Bucket

Name: S3_BUCKET_NAME (e.g. cdn.example.com)
Region: ap-southeast-2

8.2 Bucket Policy

{
  "Version": "2012-10-17",
  "Id": "PolicyForCDN",
  "Statement": [
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudfront.amazonaws.com"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::S3_BUCKET_NAME/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
        }
      }
    },
    {
      "Sid": "AllowWordPressMediaManagement",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT_ID:user/wordpress-media"
      },
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::S3_BUCKET_NAME",
        "arn:aws:s3:::S3_BUCKET_NAME/*"
      ]
    }
  ]
}

9. CloudFront Distribution

9.1 General Settings

• Alternate domain: CDN_DOMAIN
• SSL Certificate: ACM certificate (us-east-1)
• Security Policy: TLSv1.2-2021
• HTTP Version: HTTP/2
• IPv6: optional (can be disabled if not used)

9.2 Origin

Origin Domain:
S3_BUCKET_NAME.s3.ap-southeast-2.amazonaws.com

• Origin Access: Origin Access Control (OAC) (recommended)
• Do NOT expose S3 publicly

9.3 Behaviour

Note: AWS has restricted custom cache tuning unless using higher-tier plans.

10. IAM User Configuration

10.1 User

Name: wordpress-media

Used by WordPress (via AWS credentials).

10.2 Policy: S3 Access

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "WordPressMediaBucketAccess",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::S3_BUCKET_NAME",
        "arn:aws:s3:::S3_BUCKET_NAME/*"
      ]
    }
  ]
}

10.3 Policy: CloudFront Invalidation

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudFrontInvalidationAccess",
      "Effect": "Allow",
      "Action": "cloudfront:CreateInvalidation",
      "Resource": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
    }
  ]
}

This enables future cache invalidation support (not yet fully implemented).

11. AWS Credentials on Linode

Because this environment is not EC2, IAM Roles cannot be used.

Instead, credentials are stored locally:

/home/nginx/.aws/credentials

Example:

[wordpress-media]
aws_access_key_id = ACCESS_KEY
aws_secret_access_key = SECRET_KEY
region = ap-southeast-2

Important Notes

• File permissions must be restricted
• nginx/php-fpm must have access
• This is less secure than IAM Roles (to be improved in future EC2 version)

12. nginx / PHP-FPM Integration Notes

• Ensure PHP-FPM (www.conf) allows access to:
  • /home/nginx/.aws
• Adjust:
  • open_basedir
  • file permissions

Full configuration will be covered in a separate document.

13. Security Considerations

This setup follows good baseline practices, but:

• IAM user credentials are stored on disk (risk vs IAM Role)
• Bucket is restricted via:
  • CloudFront OAC
  • IAM user policy
• TLS enforced via CloudFront
• CAA records restrict certificate authorities

Future Improvements

• Migrate to EC2 with IAM Role
• Restrict IAM access by IP (LINODE_IPV4)
• Implement signed URLs if needed
• Review policies periodically

14. Key Takeaways

• This is not just a plugin install — it requires coordinated setup across:
  • DNS
  • AWS (multiple services)
  • Linux/nginx/PHP
• Region selection in AWS is not arbitrary
• Security is a balance between:
  • practicality (Linode + IAM user)
  • best practice (IAM roles, tighter policies)

15. Next Documents

Planned follow-ups:

1. Linux / nginx / PHP-FPM Configuration Details
2. WordPress mu-plugin (CDN integration code)
3. Advanced CDN behaviour & invalidation strategy