Debug ghost theme locally

This guide tells you how to setup a local dev environment of ghost theme.

Ghost caches Handlerbar for better performance. So modification of Handlebars cannot be loaded immediately unless restart. The way to solve the problem is to set the environment to development. In dev mode, Handlebars are not cached.

And for css files, modify the files under themes/your-theme will take effects after page refreshment. So you just need to mount the theme folder you are working on to the container theme folder. That makes changes outside reflect inside. And yarn dev to watch files update and build immediately.

With the 2 steps, you don’t need to zip the theme and upload it to test. Modification will show up upon refreshment. See below.

 CopyCopied!version: "3"

services:
  ghost:
    image: ghost
    container_name: ghost
    volumes:
      - ghostdata:/var/lib/ghost/content
      - /Users/slee/Downloads/alto:/var/lib/ghost/content/themes/alto
    environment:
      - NODE_ENV=development
      - url=http://localhost:8081
      - database__client=mysql
      - database__connection__host=mysql
      - database__connection__user=ghost
      - database__connection__password=ghostpwdtest
      - database__connection__database=ghostdb
    ports:
      - "8081:2368"
    depends_on:
      - mysql
    restart: unless-stopped

  mysql:
    image: mysql
    container_name: mysql
    volumes:
      - ghostdb:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=rootpwdtest
      - MYSQL_DATABASE=ghostdb
      - MYSQL_USER=ghost
      - MYSQL_PASSWORD=ghostpwdtest
    expose:
      - "3306"
    restart: unless-stopped

volumes:
  ghostdb:
  ghostdata:

In the above docker compose file, host theme folder alto is mounted into the container and env is set to development. Next, run yarn dev under alto to watch file modification, refresh page to see the new updates.

Note: if you add new hbs template files, you need to restart the container by docker-compose restart ghost to make it work.