Working with Ghost

Developer Install

This guide is for getting Ghost installed on your local machine ready for contributing to Ghost or hacking core files. If you are only interested in running a Ghost site (locally or in production) or developing Ghost themes please use the general install guide instead.

Pre-requisites

Ghost uses yarn (>= 0.23.x) rather than npm to manage it's dependencies. Ensure that you have it installed and you have configured your PATH environment variable for it to work correctly. We recommend the "Installation Script" instructions because it works better with nvm but choose the best option for your development setup.

sudo for local development

sudo is not supported for local development setups, 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. git clone git@github.com:TryGhost/Ghost.git && cd ghost
    • clone Ghost and make it your working directory


  1. yarn run init
    • install required global npm packages, set up git hooks, and initiate the submodules
    • shortcut for yarn global add knex-migrator ember-cli grunt-cli && yarn install && grunt symlink && grunt init


  1. knex-migrator init
    • create and initialise your database

yarn run init - Only for initial setup!

If you run yarn run init after you have a working setup it will act like a reset and you may end up in a weird state where your submodules are not pointing at master. It's recommended to only run this command once and then forget about it 😄. See the grunt master command below if you want to get a working install 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...


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 file watching or automatic restarts
  • ensure the client files are built and/or up to date first (see grunt build)
  • useful when you want a quick startup and don't care about needing to restart manually if you change anything

`node index.js` does not build client files:

node index.js simply starts the server without building the client files. This means you may need to run grunt build first if you haven't done so already, or if you have made changes to client files.

Database commands


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

Note:

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 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

Testing

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


Troubleshooting

ERROR: (EADDRINUSE) Cannot start Ghost

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

ERROR: ENOENT

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