Ghost Docker Theme Development

A generalized Docker-based Ghost CMS development environment for local theme development. Clone this repository and start developing your Ghost theme immediately with Docker.

Features

• Ghost 6 Alpine - Latest stable Ghost version
• Hot Reload - Theme changes reload automatically
• SQLite Database - No external database required for development
• Configurable - Easy port and theme name configuration
• Development Mode - Optimized for theme development with disabled security features
• Volume Persistence - Content and database persist between container restarts

Prerequisites

• Docker and Docker Compose installed
• Basic knowledge of Ghost theme development

Quick Start

1. Clone this repository:

   git clone <repository-url> my-ghost-theme
   cd my-ghost-theme

2. Configure your setup:

   cp .env.example .env

   Edit .env to set your theme name and port:

   GHOST_PORT=2368
   THEME_NAME=my-awesome-theme

3. Add your theme:

   • Place your Ghost theme files in the ./theme/ directory
   • Or clone an existing theme: git clone <theme-repo> theme

4. Start Ghost:

   docker compose up

5. Access Ghost:

   • Frontend: http://localhost:2368 (or your configured port)
   • Admin: http://localhost:2368/ghost

6. Activate your theme:

   • Go to Ghost Admin → Settings → Design → Themes
   • Upload/Activate your theme

Directory Structure

ghost-docker-theme-development/
├── docker-compose.yml          # Docker configuration
├── config.development.json     # Ghost development config
├── .env.example               # Environment variables template
├── .env                       # Your environment variables (create from .env.example)
├── .gitignore                 # Git ignore rules
├── theme/                     # Your Ghost theme files go here
│   └── .gitkeep
├── content/                   # Ghost content (auto-created, gitignored)
│   ├── data/                  # SQLite database
│   ├── images/                # Uploaded images
│   └── ...
└── README.md                  # This file

Configuration

Environment Variables

Create a .env file from .env.example and configure:

• GHOST_PORT - Port to expose Ghost on (default: 2368)
• THEME_NAME - Your theme's directory name (default: your-theme)

Ghost Configuration

The config.development.json file contains Ghost-specific settings for development:

• SQLite database configuration
• Development-friendly security settings
• Logging configuration
• Mail transport disabled for development

Common Commands

# Start Ghost in foreground (see logs)
docker compose up

# Start Ghost in background
docker compose up -d

# Stop Ghost
docker compose down

# View logs
docker compose logs -f ghost

# Restart Ghost (useful after theme changes that require restart)
docker compose restart ghost

# Remove containers and volumes (fresh start)
docker compose down -v

Development Workflow

1. Make theme changes - Edit files in ./theme/
2. Automatic reload - Ghost detects changes and reloads
3. Manual refresh - Refresh browser to see template changes
4. Full restart - Some changes (like routes.yaml) require docker compose restart ghost

Theme Development Tips

Hot Reloading

• CSS/JS changes: Automatic reload, refresh browser
• Handlebars template changes: Refresh browser required
• New files or routes.yaml: Full Ghost restart required

Theme Structure

Your theme should follow the standard Ghost theme structure:

theme/
├── index.hbs              # Homepage template
├── post.hbs               # Post template  
├── page.hbs               # Page template
├── author.hbs             # Author template
├── tag.hbs                # Tag template
├── package.json           # Theme metadata
├── assets/                # CSS, JS, images
│   ├── css/
│   ├── js/
│   └── images/
└── partials/              # Reusable template parts
    ├── navigation.hbs
    └── ...

Building Assets

If your theme uses build tools (Gulp, Webpack, etc.):

1. Install dependencies in the theme directory
2. Run build commands as needed
3. Ensure built files are in the correct locations for Ghost

Troubleshooting

Port Conflicts

If port 2368 is already in use:

1. Change GHOST_PORT in your .env file
2. Restart with docker compose down && docker compose up

Theme Not Showing

1. Check that your theme files are in ./theme/
2. Activate the theme in Ghost Admin → Settings → Design
3. Ensure theme has required files (index.hbs, package.json)

Permission Issues

The Ghost container runs as user node (UID 1000). If you encounter permission issues:

sudo chown -R 1000:1000 ./theme ./content

Database Issues

To start with a fresh database:

docker compose down -v
docker compose up

Container Won't Start

Check logs for detailed error information:

docker compose logs ghost

Advanced Configuration

Custom Ghost Config

Modify config.development.json for advanced Ghost configuration options like:

• Database settings
• Mail configuration
• Logging levels
• Custom paths

Multiple Themes

To work with multiple themes, either:

1. Change THEME_NAME in .env and swap theme directories
2. Create multiple Docker compose setups with different configurations

Contributing

Feel free to submit issues and enhancement requests!

License

This Docker setup is provided as-is for development purposes.