Ghost Story Theme - Deployment Guide

This guide covers how to deploy the Story theme to both local Docker instances and Ghost Pro.

Local Development with Docker

Prerequisites

• Docker and Docker Compose installed
• Node.js and npm installed (for building the theme)

Setup Steps

1. Build the theme assets:

   cd ghost-theme
   npm install
   npm run build
   

2. Start Ghost with Docker Compose:

   docker-compose up -d
   

3. Access Ghost Admin:
   • Open http://localhost:2368/ghost in your browser
   • Complete the initial setup (create admin account)
4. Activate the Theme:
   • Go to Settings → Design
   • Click Change theme
   • Select Story Theme from the list
   • Click Activate
5. Development Mode (with live reload):

   # In one terminal, start the build watcher
   npm run dev
      
   # In another terminal, start Docker
   docker-compose up
   

   Changes to CSS/JS will automatically rebuild and reload.

Stopping Docker

docker-compose down

To remove all data (fresh start):

docker-compose down -v

Deploying to Ghost Pro

Prerequisites

• Ghost Pro account
• Theme built and packaged

Steps

1. Build and Package the Theme:

   cd ghost-theme
   npm install
   npm run build
   npm run zip
   

   This creates theme.zip in the theme directory.

2. Upload to Ghost Pro:
   • Log in to your Ghost Pro admin panel
   • Navigate to Settings → Design
   • Click Upload a theme
   • Select the theme.zip file
   • Wait for upload to complete
3. Activate the Theme:
   • Once uploaded, the theme will appear in your theme list
   • Click Activate next to “Story Theme”
4. Verify:
   • Visit your site to ensure the theme is working
   • Check that all features (navigation, sidenotes, etc.) work correctly

Testing the Theme

Before deploying, test your theme:

npm run test

This runs gscan to check for Ghost compatibility issues.

Expected Docker Messages

When running docker-compose up, you may see some messages that look like errors but are actually normal:

• ActivityPub errors - Normal on first setup, ActivityPub tries to initialize but fails (harmless)
• 403 Authorization errors - Expected before you complete initial setup
• “Explore URL not set” warning - Just a configuration notice

See DOCKER_NOTES.md for details. These don’t affect functionality - Ghost is working correctly!

Troubleshooting

Theme not appearing in Ghost

• Ensure package.json is in the theme root
• Check that all required template files exist
• Verify the theme structure matches Ghost requirements

Styles not loading

• Run npm run build to compile assets
• Check that built/css/story-styles.css exists
• Verify asset paths in default.hbs

JavaScript not working

• Ensure built/js/story-navigation.js exists
• Check browser console for errors
• Verify the script is loaded in default.hbs

Docker issues

• Ensure port 2368 is not in use
• Check Docker logs: docker-compose logs ghost
• Try rebuilding: docker-compose up --build

Production Build

For production deployment:

NODE_ENV=production npm run build
npm run zip

This creates an optimized, minified build suitable for production.