Ghost Release: 3.0.0

TL;DR

Ghost 3.0 introduces a major overhaul with the new members and subscriptions system, completely revamped API architecture (v3 APIs), improved security through better separation of front-end and admin interfaces, and significant codebase cleanup by removing legacy code. This release focuses on modernizing Ghost's architecture while adding monetization capabilities through the new members system, making it a substantial upgrade for publishers looking to build sustainable businesses.

Highlight of the Release

• Introduction of members and subscriptions system for monetization
• Complete removal of legacy v0.1 API in favor of modern v3 API
• Improved security with better separation of front-end and admin interfaces
• Migration of post metadata to a separate table for better performance
• Conversion of post.page property to post.type for more flexibility

Migration Guide

Upgrading to Ghost 3.0

Prerequisites

• Update to Ghost-CLI 1.12.0 or higher before upgrading
• Ensure Node.js version is compatible (v10.13.0+, v12.10.0+ recommended)

API Changes

1. v0.1 API Removal: All v0.1 API endpoints have been completely removed. Update any custom code, themes, or integrations to use the v2 or v3 API.

2. Theme Updates:

   • Update your theme's package.json to include "engines": { "ghost-api": "v3" }
   • Use gscan to check theme compatibility: gscan /path/to/theme --v3

3. Post Type Changes:

   • The post.page property has been replaced with post.type
   • Update any custom code that references post.page to use post.type instead

4. Subscribers to Members Migration:

   • All subscribers have been automatically migrated to members
   • Update any integrations or webhooks to use the new members endpoints
   • Zapier integrations or other webhook clients need to be updated to use members

5. RSS Changes:

   • RSS pagination has been removed
   • URLs like /rss/2/ will no longer work
   • The redirect from /rss/1/ to /rss/ has been removed

6. Template Changes:

   • Ghost now throws a 400 error for missing templates rather than falling back to default.hbs
   • Ensure all templates referenced in your routes.yaml file exist in your theme

7. Admin URL Configuration:

   • If using a separate admin URL, review the new admin:redirects config option
   • When set to false, /ghost/ will 404 on the front-end and all {resource}/edit/ URLs will 404

Upgrade Recommendations

Urgency: Medium to High

Ghost 3.0 is a major release with significant architectural improvements and new features. While it contains breaking changes, the upgrade is recommended for most users due to:

1. New Monetization Options: The members and subscriptions system provides new ways to generate revenue from your content.

2. Security Improvements: Better separation of front-end and admin interfaces enhances security.

3. Performance Optimizations: Database structure improvements and code cleanup will improve performance.

4. Future-Proofing: Legacy code has been removed, making Ghost more maintainable and ready for future improvements.

Before upgrading:

• Take a complete backup of your site
• Test the upgrade on a staging environment first
• Review the migration guide to understand breaking changes
• Update any custom themes or integrations to be compatible with v3 API
• Ensure you're using Ghost-CLI 1.12.0 or higher

For sites with heavy customization or critical production environments, thorough testing is essential before upgrading.

Bug Fixes

• Fixed 404 handling for {admin url}/content/* routes
• Fixed URLs in output when accessing front-end via HTTPS
• Fixed failing regression test suite related to "frontend"
• Fixed AMP test for 'static pages'
• Fixed log usage for columnMigration command
• Fixed migration order and folder naming
• Fixed error rolling back the "remove empty strings" migration
• Fixed reading_time calculation for non-public posts
• Fixed filter in URL config for posts to properly handle member-only content

New Features

Members and Subscriptions

• Added a complete members system with subscription capabilities
• Enabled members feature by default (previously required developer experiments flag)
• Added member.added and member.deleted webhooks
• Added member email templates with refined typography and spacing

API Improvements

• Added new v3 Content and Admin APIs
• Set v3 as the default API version
• Added publicAdminApi middleware stack for better API organization

Security Enhancements

• Implemented full separation of front-end and admin apps when using a separate admin URL
• Added admin:redirects config option to disable admin redirects for better security
• Uses vhost in parent-app to properly split front-end and admin/api apps

Theme Engine Improvements

• Added access property to entries for v3+ API to support members-only content
• Updated default publication icon and assets
• Bumped gscan to v3.0.0 with improved theme validation

Security Updates

Security Improvements

• Fully separated front-end and admin app URLs for better isolation
• Added admin:redirects config option for disabling admin redirects to help mask the admin URL
• Removed all non-/ghost/ redirects to the admin to prevent confusion with member-related actions
• Fixed URLs in output when accessing front-end via HTTPS with proper proxy trust settings
• Removed all clients and client_trusted_domains related code that was no longer needed
• Removed all accesstokens and refreshtokens related code that was no longer used

Performance Improvements

Database Optimizations

• Extracted post metadata into a new post_meta table to reduce the width of the posts table
• Added migration to normalize all empty strings to NULL for better database efficiency
• Added migration for re-generating HTML of all posts for consistent rendering
• Migrated posts.page column to posts.type for more flexibility
• Updated post model queries to raw knex queries for better performance

API Performance

• Reduced API debug statements to make debugging more useful and less verbose
• Removed begin/end HTML comments from output of most cards for cleaner output
• Simplified controller checks in {{get}} helper

Impact Summary

Ghost 3.0 represents a significant evolution of the platform with both architectural improvements and new business capabilities. The introduction of the members and subscriptions system transforms Ghost from a pure publishing platform into a potential revenue generator for content creators. This is arguably the most impactful change, enabling publishers to monetize their content directly.

From a technical perspective, the removal of legacy v0.1 API code and the shift to the v3 API creates a cleaner, more maintainable codebase. The database optimizations, particularly splitting post metadata into a separate table, address long-standing performance issues with "too wide" database tables.

Security improvements through better separation of front-end and admin interfaces provide more robust protection, especially for sites using custom admin URLs. The new configuration options give administrators more control over how their Ghost installation behaves.

For developers, this release requires significant updates to custom code, themes, and integrations, but provides a more consistent and powerful API to work with going forward. Theme developers in particular will need to update their themes to be compatible with Ghost 3.0 and to take advantage of the new members features.

Overall, Ghost 3.0 balances introducing new capabilities with cleaning up technical debt, setting a foundation for future growth while providing immediate value through the members system.

Full Release Notes