Working with Ghost

This guide is for getting a local development clone of Ghost setup on your local machine. If you are only interested in running a Ghost site or developing Ghost themes please use the general install guide instead.


We recommend installing Node.js via nvm using their install script and installing Yarn via their install script.

We use yarn, rather than npm for managing our dependencies & running scripts. You will need it installed in order to work on Ghost.

no sudo for local development

if your environment requires sudo when installing npm packages we highly recommend fixing that before continuing.

Initial Setup

These commands only need to be run once, they're designed to get your Ghost install up and running quickly 🚀

  1. Clone Ghost and make it your working directory:

    git clone && cd Ghost

  2. Install global npm packages

    yarn global add knex-migrator grunt-cli ember-cli bower

  3. Run the first-time setup & install tasks:

    yarn setup

    • install dependencies, initialise the database, set up git hooks & initialise submodules
    • shortcut for yarn install && knex-migrator init && grunt symlink && grunt init
    • runs a first build of the admin, and can take a very long time :hourglass+:
    • should only ever be run once!
  4. You're ready! Once you see a "done" message you can start Ghost:

    grunt dev

yarn setup - run it once!

If you run yarn setup after you have a working setup it will act like a reset and you may end up in a bad state . Only run this command once and then forget about it 😄.

See the grunt init & grunt master command for keeping up-to-date.

Day-to-day Development Commands

Running Ghost

There are a number of ways to start Ghost, each with their own benefits and trade-offs. All of these will, by default, serve Ghost from http://localhost:2368./

grunt dev

  • the most general way of running Ghost in development mode
  • builds admin client files on start
  • watches server files and restarts on changes
  • watches admin client files and performs a quick rebuild on changes including live-reload

grunt dev --server

  • same as above but doesn't build the client files on start or watch the client files for changes
  • ensure the client files are built and/or up to date first (see grunt build)
  • useful to minimise startup time and preserve system resources if you know you won't be modifying any client files

grunt prod

  • builds admin client files for production
  • does not (!) watch for changes to server files or admin client files
  • start Ghost with npm start --production

node index.js

  • simply starts the Ghost server with no client build, file watching or automatic restarts
  • useful when you want a quick startup and don't care about needing to restart manually if you change anything
  • does not build client files & may leave you with a blank admin panel (see grunt build)

Database commands

Ghost uses it's own tool called knex-migrator for managing database migrations.

knex-migrator reset

  • if you want to reset your database you can run this command followed by knex-migrator init

knex-migrator init

  • initialises your database
  • it populates the tables and inserts all fixtures


If you want to reset your production database you can use NODE_ENV=production knex-migrator reset followed by NODE_ENV=production knex-migrator init

Keeping up to date

grunt init

  • re-initialises the submodules, if you have problems with them

grunt master

  • checks out the master branch and pulls from upstream for Ghost, Ghost-Admin, and Casper to bring everything up to date
  • runs yarn install for each submodule so that you can run grunt dev straight away
  • by default this will use upstream as the name of your upstream remote, if you use an alternative naming scheme for your remotes you can pass a flag --upstream=<remote_name>, e.g.:
    • grunt master --upstream=origin

grunt build

  • builds the admin client files
  • useful if you've just updated the client and don't want the overhead of building/watching client files by using grunt dev


By default the tests run with SQlite. If you would like to run your tests with MySQL,
then add NODE_ENV=testing-mysql in front of the grunt command.

grunt test-all

  • run all server tests

grunt test-unit

  • run all server unit tests

grunt test-integration

  • run all server integration tests

grunt test-routes

  • run all server route tests

grunt test:core/test...

  • run a single test
  • path can be absolute or relative
  • terminal auto completion can be very useful
  • alternatively: use .only on your test to run a single test

grunt lint

  • runs jshint and jshintrc across all of the server files


ERROR: (EADDRINUSE) Cannot start Ghost

This error means that Ghost is already running, and you need to stop it.


This error means that the mentioned file doesn't exist.

ERROR Error: Cannot find module

yarn has not completed successfully.
Please remove your node_modules and re-run yarn.

Error: Cannot find module './build/default/DTraceProviderBindings'

This warning can happen if you switch node versions. You can resolve this warning by reinstalling your node_modules.

Working with Ghost