Guides
Setup CDN
A Content Delivery Network (CDN) is essential for optimizing your Maglev site's performance and user experience. This guide explains why using a CDN is crucial and how to configure it with Maglev.
Why Use a CDN?
Using a CDN in front of your assets provides several key benefits:
- Faster Loading Times: CDNs serve assets from servers geographically closer to your users, reducing latency
- Better Performance: Static assets (images, CSS, JavaScript) are cached and served from edge locations
- Reduced Server Load: Your main server handles fewer asset requests, improving overall performance
- Global Reach: Users worldwide experience consistent, fast loading times
- Cost Efficiency: Reduced bandwidth costs and improved scalability
How Maglev Handles CDNs
Maglev includes built-in CDN support through the asset_host
configuration. When configured, Maglev automatically prepends the CDN URL to asset URLs, ensuring all assets are served through your CDN.
The asset_host
configuration works with three different types of values:
- String: A static CDN URL
- Proc: A dynamic function that returns the CDN URL
- Nil: Falls back to the Rails application's
asset_host
value (default behavior and if defined)
Important Note: Theme section screenshot URLs (displayed in the Maglev editor UI) are not handled by Maglev's asset_host
configuration. These assets use the Rails application's asset_host
configuration instead, as they are served through the main Rails application rather than the Maglev engine.
CDN Configuration
Static CDN URL
For simple setups with a single CDN endpoint:
config/initializers/maglev.rb
Maglev.configure do |config| # ... other configuration ... # Static CDN URL config.asset_host = 'https://cdn.yourdomain.com' # ... other configuration ... end
Environment Variable Configuration
For flexible deployment across different environments, use environment variables:
config/initializers/maglev.rb
Maglev.configure do |config| # ... other configuration ... config.asset_host = ENV['MAGLEV_CDN_URL'] # ... other configuration ... end
Environment-Specific CDNs
config/initializers/maglev.rb
Maglev.configure do |config| # ... other configuration ... config.asset_host = case Rails.env when 'production' 'https://cdn.yourdomain.com' when 'staging' 'https://staging-cdn.yourdomain.com' when 'development' nil end # ... other configuration ... end
Dynamic CDN URL
For more complex setups where you need different CDNs per environment or site:
config/initializers/maglev.rb
Maglev.configure do |config| # ... other configuration ... # Dynamic CDN URL based on environment config.asset_host = ->(site) do if Rails.env.production? "https://cdn.#{site.domain}" elsif Rails.env.staging? "https://staging-cdn.#{site.domain}" else nil # No CDN in development end end # ... other configuration ... end
Multi-Site CDN Support
config/initializers/maglev.rb
Maglev.configure do |config| # ... other configuration ... config.asset_host = ->(site) do case site.domain when 'maindomain.com' 'https://cdn.maindomain.com' else 'https://default-cdn.com' end end # ... other configuration ... end
CDN Providers
Popular CDN Services
- Cloudflare: Free tier available, excellent performance
- AWS CloudFront: Integrated with AWS services
- BunnyCDN: Cost-effective, high-performance
- Fastly: Enterprise-grade, real-time purging
- KeyCDN: Global network, competitive pricing
Example: Cloudflare Setup
- Sign up for Cloudflare and add your domain
- Configure DNS to point to Cloudflare's nameservers
- Enable CDN in the Cloudflare dashboard
- Configure Maglev to use your Cloudflare domain:
config/initializers/maglev.rb
Maglev.configure do |config| # ... other configuration ... config.asset_host = 'https://cdn.yourdomain.com' # ... other configuration ... end
Testing CDN Configuration
Verify CDN is Working
- Check your Maglev configuration to ensure
asset_host
is set - Upload an image through the Maglev editor
- Inspect the HTML to verify the CDN URL is prepended
- Test asset loading from different geographic locations
Debug CDN Issues
If assets aren't loading through your CDN:
- Verify the
asset_host
configuration is correct - Check that your CDN is properly configured
- Ensure DNS is pointing to your CDN
- Check CDN cache settings and purging
Performance Optimization Tips
CDN Best Practices
- Use HTTPS: Always serve assets over HTTPS for security
- Set proper cache headers: Configure appropriate cache expiration times
- Enable compression: Use gzip or brotli compression for text assets
- Monitor performance: Use tools like WebPageTest or Lighthouse
- Purge cache strategically: Only purge when necessary to maintain performance
Cache Headers
Configure your CDN to set appropriate cache headers:
Cache-Control: public, max-age=31536000
This tells browsers to cache assets for one year, significantly improving performance for returning visitors.
Troubleshooting
Common Issues
Assets not loading through CDN:
* Check asset_host
configuration
* Verify CDN is properly configured
* Ensure DNS is pointing to CDN
Mixed content warnings:
* Ensure all CDN URLs use HTTPS
* Check for any HTTP references in your content
Cache invalidation:
* Use CDN purging tools when updating assets
* Consider using cache-busting techniques for critical updates
Getting Help
If you encounter issues with CDN setup:
- Check your CDN provider's documentation
- Verify Maglev configuration syntax
- Test with a simple static CDN URL first
- Consult the Maglev community for support
A properly configured CDN can improve your Maglev site's loading speed by 50-80% and significantly enhance user experience, especially for international visitors.