Deploy to AWS S3

Publish your Opal Editor sites to Amazon S3 static website hosting with full control over infrastructure

Amazon S3 (Simple Storage Service) provides reliable, scalable static website hosting. Opal Editor integrates with AWS S3 to deploy your sites directly to S3 buckets configured for website hosting.

Prerequisites

Before deploying to AWS S3:

• An AWS account (sign up at aws.amazon.com)
• AWS access key ID and secret access key
• An S3 bucket or permission to create one
• A completed build ready for deployment

Authentication Setup

AWS S3 requires programmatic access credentials.

1. Create IAM User

   1. Go to AWS IAM Console > Users
   2. Click “Add user”
   3. Enter username (e.g., “opal-editor”)
   4. Select “Programmatic access”
   5. Click “Next: Permissions”
2. Attach Permissions

   Attach a policy with S3 permissions. You can:

   • Use AmazonS3FullAccess for full S3 access (easier but less secure)
   • Create a custom policy with specific bucket permissions (recommended)

   Custom policy example:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:PutObject",
           "s3:GetObject",
           "s3:DeleteObject",
           "s3:ListBucket",
           "s3:PutBucketWebsite",
           "s3:PutBucketPolicy"
         ],
         "Resource": [
           "arn:aws:s3:::your-bucket-name",
           "arn:aws:s3:::your-bucket-name/*"
         ]
       }
     ]
   }
   
3. Save Credentials

   1. Complete the user creation
   2. Copy the Access Key ID
   3. Copy the Secret Access Key (shown only once!)
   4. Store both securely
4. Add to Opal Editor

   Create a new AWS API authentication in Opal Editor:

   • Enter Access Key ID as apiKey
   • Enter Secret Access Key as apiSecret

Keep your AWS credentials secure. They provide access to your AWS resources and can incur costs if misused.

Destination Configuration

Configure your S3 deployment destination:

{
  "remoteAuthId": "your-auth-id",
  "label": "My S3 Website",
  "meta": {
    "bucketName": "my-website-bucket",
    "region": "us-east-1"
  }
}

Configuration Fields

• bucketName (required): S3 bucket name
  • Must be globally unique across all AWS accounts
  • Must be lowercase
  • Can contain letters, numbers, hyphens, and periods
  • 3-63 characters long
• region (required): AWS region for the bucket
  • Default: us-east-1
  • Common regions: us-east-1, us-west-2, eu-west-1, ap-southeast-1

S3 bucket names must be globally unique. If your desired name is taken, try adding a suffix like -web or -site.

Deployment Process

1. Configure S3 bucket

   Set up your deployment:

   • Choose or create an S3 bucket
   • Select AWS region
   • Bucket will be created if it doesn’t exist
2. Build your site

   Complete a build in Opal Editor:

   • Source files are processed
   • Static HTML is generated
   • Assets are prepared
3. Automatic bucket configuration

   Opal Editor automatically:

   • Enables static website hosting
   • Configures public read access
   • Sets index document to index.html
   • Sets error document to 404.html (if exists)
4. Upload files

   Deployment uploads:

   • All files are uploaded in parallel
   • Content types are automatically detected
   • Progress is tracked in real-time
5. Access your site

   Your site is live at:

   • S3 website URL: http://{bucketName}.s3-website.{region}.amazonaws.com
   • Custom domain (if configured)

How It Works

The AWS S3 deployment agent (RemoteAuthAWSAPIAgent) manages:

1. Bucket Management: Creates bucket if needed
2. Website Configuration: Enables static website hosting
3. Public Access: Configures bucket for public read access
4. File Upload: Uploads all files with correct content types
5. URL Generation: Returns the S3 website URL

Bucket Configuration

Opal Editor automatically configures buckets:

// Automatic configuration:
- Website hosting enabled
- Index document: index.html
- Error document: 404.html (if present)
- Public read access granted
- Bucket policy for website access

File Upload

Files are uploaded with optimizations:

• Parallel uploads: All files uploaded simultaneously
• Content-Type detection: MIME types automatically set
• Public read ACL: Files accessible to public
• Progress tracking: Real-time upload status

Content Type Detection

Automatic MIME type detection:

• .html → text/html
• .css → text/css
• .js → application/javascript
• .json → application/json
• .png → image/png
• .jpg, .jpeg → image/jpeg
• .svg → image/svg+xml
• .woff, .woff2 → font/woff, font/woff2
• And many more…

Features

Static Website Hosting

S3 static website hosting provides:

• Fast content delivery
• High availability
• Automatic scaling
• Pay-per-use pricing

Bucket Versioning

Enable versioning for:

• Backup of previous versions
• Recovery from accidental deletion
• Rollback capability

Access Logs

Track website access:

• Enable server access logging
• Analyze visitor patterns
• Monitor bandwidth usage

Cost-Effective

S3 pricing is very affordable:

• Pay only for storage used
• Pay only for bandwidth
• No minimum fees
• Free tier available (first 12 months)

Public Access Configuration

Opal Editor configures public access automatically, but you may need to:

If you see “S3BlockPublicAccessError”:

• Your AWS account has Block Public Access enabled
• This is an account-level or bucket-level setting
• You need to disable it for website hosting

To fix Block Public Access issues:

1. Check account settings

   1. Go to S3 Console
   2. Click “Block Public Access settings for this account”
   3. Check if blocking is enabled
2. Update account settings

   If account-level blocking is on:

   1. Click “Edit”
   2. Uncheck “Block all public access”
   3. Or selectively uncheck specific options
   4. Save changes
3. Check bucket settings

   For specific bucket:

   1. Select your bucket
   2. Go to “Permissions” tab
   3. Edit “Block public access”
   4. Uncheck required options

Troubleshooting

Bucket Name Already Exists

S3 bucket names are globally unique. If “Bucket already exists”:

• Try a different bucket name
• Add a unique suffix (date, random string)
• Check if you already own a bucket with that name

Solution: Choose a unique bucket name or use an existing bucket you own.

Access Denied Errors

If you see access denied:

1. Verify AWS credentials are correct
2. Check IAM user has S3 permissions
3. Ensure bucket policy allows access
4. Verify region matches bucket location

Website Not Accessible

If site doesn’t load:

1. Verify bucket is configured for website hosting
2. Check Block Public Access settings
3. Verify bucket policy allows public read
4. Ensure index.html exists in bucket
5. Check URL format is correct

Incorrect Content Types

If files serve with wrong content type:

• Verify file extensions are correct
• Check MIME type detection logic
• Manually set content type in S3 console if needed

Region Mismatch

If you see region errors:

• Ensure configured region matches bucket region
• Update region in destination configuration
• Recreate bucket in desired region if needed

Best Practices

1. Use specific IAM permissions: Create custom policy with minimal required permissions
2. Enable versioning: Protect against accidental deletion
3. Configure CloudFront: Add CDN for better performance (see below)
4. Set up custom domain: Use Route 53 or your DNS provider
5. Monitor costs: Use AWS Cost Explorer to track spending
6. Enable logging: Track access and troubleshoot issues
7. Use lifecycle policies: Automatically delete old versions to save costs

Advanced Configuration

CloudFront CDN

Improve performance with CloudFront:

1. Create CloudFront distribution

   1. Go to CloudFront Console
   2. Create new distribution
   3. Origin domain: Your S3 website endpoint
   4. Configure caching behavior
2. Configure custom domain

   1. Add alternate domain name (CNAME)
   2. Request/add SSL certificate
   3. Update DNS to point to CloudFront
3. Update deployment

   After CloudFront setup:

   • Invalidate cache after deployments
   • Configure cache behavior
   • Set TTL for different file types

Custom Domain with Route 53

Set up custom domain:

1. Register or transfer domain to Route 53
2. Create hosted zone for your domain
3. Add A record pointing to S3 bucket (or CloudFront)
4. Update destination configuration to use custom domain

Bucket Policy

Opal Editor applies this bucket policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

This allows public read access to all objects in the bucket.

CORS Configuration

If loading assets from other domains:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

Add this in S3 Console > Bucket > Permissions > CORS.

Redirect Rules

Configure redirects for:

• Redirecting www to non-www (or vice versa)
• Custom error pages
• URL rewriting

Add in S3 Console > Bucket > Properties > Static website hosting > Redirection rules.

Cost Optimization

Storage Classes

For static websites, use:

• S3 Standard: Best for frequently accessed content
• S3 Intelligent-Tiering: Automatically moves objects between tiers

Lifecycle Policies

Create lifecycle rules:

• Delete old deployment versions
• Move infrequent access files to cheaper storage
• Expire incomplete multipart uploads

Data Transfer

Reduce costs:

• Use CloudFront CDN (free tier available)
• Compress assets before deployment
• Enable S3 Transfer Acceleration for faster uploads

Monitoring

CloudWatch Metrics

Monitor your S3 bucket:

• Request metrics (GET, PUT, DELETE)
• Bandwidth usage
• Error rates
• Bucket size

Access Logs

Enable server access logging:

1. Go to bucket properties
2. Enable Server access logging
3. Choose target bucket for logs
4. Analyze access patterns

Related Resources

• AWS S3 Documentation
• S3 Static Website Hosting
• AWS CloudFront
• Publishing Overview
• Build System