{"_id":"59365227e16643001bac5045","category":{"_id":"59365227e16643001bac5033","version":"59365226e16643001bac5030","project":"543026235eceb608003fde5f","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-06-05T13:44:53.935Z","from_sync":false,"order":2,"slug":"contributing","title":"Contributing"},"project":"543026235eceb608003fde5f","user":"5736eb0b1a48812200566f0d","parentDoc":null,"version":{"_id":"59365226e16643001bac5030","project":"543026235eceb608003fde5f","__v":1,"createdAt":"2017-06-06T06:56:38.999Z","releaseDate":"2017-06-06T06:56:38.999Z","categories":["59365227e16643001bac5031","59365227e16643001bac5032","59365227e16643001bac5033","59365227e16643001bac5034"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-05T13:08:43.311Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"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](doc:getting-started-guide) instead.\",\n  \"title\": \"Developer Install\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Pre-requisites\"\n}\n[/block]\n- **[Node.js](https://nodejs.org)** (See [Supported Node Versions](doc:supported-node-versions))\n- **[Yarn](https://yarnpkg.com)**\n\nGhost uses [`yarn`](https://yarnpkg.com) (**>= 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](https://yarnpkg.com/en/docs/install#alternatives-tab) because it works better with `nvm` but choose the best option for your development setup.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"`sudo` is **not** supported for local development setups, if your environment requires `sudo` when installing npm packages we highly recommend fixing that before continuing.\",\n  \"title\": \"sudo for local development\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Initial Setup\"\n}\n[/block]\nThese commands only need to be run *once*, they're designed to get your Ghost install up and running quickly ๐Ÿš€\n<br>\n\n1. <pre><strong>git clone git:::at:::github.com:TryGhost/Ghost.git && cd ghost</strong></pre>\n    - clone Ghost and make it your working directory\n\n<br>\n\n2. <pre><strong>yarn run init</strong></pre>\n    - install required global npm packages, set up git hooks, and initiate the submodules\n    - shortcut for `yarn global add knex-migrator ember-cli grunt-cli && yarn install && grunt symlink && grunt init`\n\n<br>\n\n3. <pre><strong>knex-migrator init</strong></pre>\n    - create and initialise your database\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"yarn run init - Only for initial setup!\",\n  \"body\": \"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](#grunt-master) command below if you want to get a working install up to date.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Day-to-day Development Commands\"\n}\n[/block]\n### Running Ghost\n\nThere are a number of ways to start Ghost, each with their own benefits and trade-offs...\n\n<br>\n<pre><strong>grunt dev</strong></pre>\n\n- the most general way of running Ghost in development mode\n- builds admin client files on start\n- watches server files and restarts on changes\n- watches admin client files and performs a quick rebuild on changes including live-reload\n\n<br>\n<pre><strong>grunt dev --server</strong></pre>\n\n- same as above but doesn't build the client files on start or watch the client files for changes\n- ensure the client files are built and/or up to date first (see [`grunt build`](#grunt-build))\n- useful to minimise startup time and preserve system resources if you know you won't be modifying any client files\n\n<br>\n<pre><strong>grunt prod</strong></pre>\n\n- builds admin client files for production\n- does not (!) watch for changes to server files or admin client files\n- start Ghost with `npm start --production`\n\n<br>\n<pre><strong>node index.js</strong></pre>\n\n- simply starts the Ghost server with no file watching or automatic restarts\n- ensure the client files are built and/or up to date first (see [`grunt build`](#grunt-build))\n- useful when you want a quick startup and don't care about needing to restart manually if you change anything\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"`node index.js` does not build client files:\",\n  \"body\": \"`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.\"\n}\n[/block]\n### Database commands\n\n<br>\n<pre><strong>knex-migrator reset</strong></pre>\n\n- if you want to reset your database you can run this command followed by `knex-migrator init`\n\n<br>\n<pre><strong>knex-migrator init</strong></pre>\n\n- initialises your database\n- it populates the tables and inserts all fixtures\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"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`\"\n}\n[/block]\n### Keeping up to date\n\n<pre id=\"grunt-master\"><strong>grunt master</strong></pre>\n\n- checks out the master branch and pulls from upstream for Ghost, Ghost-Admin, and Casper to bring everything up to date\n- runs `yarn install` for each submodule so that you can run `grunt dev` straight away\n- 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.:\n    - `grunt master --upstream=origin`\n\n<br>\n<pre id=\"grunt-build\"><strong>grunt build</strong></pre>\n\n- builds the admin client files\n- useful if you've just updated the client and don't want the overhead of building/watching client files by using `grunt dev`\n\n\n## Testing\n\nBy default the tests run with SQlite. If you would like to run your tests with MySQL, \nthen add `NODE_ENV=testing-mysql ` in front of the grunt command.\n\n<br>\n<pre><strong>grunt test-all</strong></pre>\n\n- run all server tests \n\n<br>\n<pre><strong>grunt test-unit</strong></pre>\n\n- run all server unit tests\n\n<br>\n<pre><strong>grunt test-integration</strong></pre>\n\n- run all server integration tests\n\n<br>\n<pre><strong>grunt test-routes</strong></pre>\n\n- run all server route tests\n\n<br>\n<pre><strong>grunt test:core/test...</strong></pre>\n\n- run a single test\n- path can be absolute or relative\n- terminal auto completion can be very useful\n- alternatively: use `.only` on your test to run a single test\n\n<br>\n<pre><strong>grunt lint</strong></pre>\n- runs jshint and jshintrc across all of the server files\n\n<br>\n[block:api-header]\n{\n  \"title\": \"Troubleshooting\"\n}\n[/block]\n### ERROR: (EADDRINUSE) Cannot start Ghost\n\nThis error means that Ghost is already running, and you need to stop it.\n\n### ERROR: ENOENT\n\nThis error means that the mentioned file doesn't exist.\n\n### ERROR Error: Cannot find module\n\n`yarn` has not completed successfully. \nPlease remove your node_modules and re-run `yarn`.\n\n### Error: Cannot find module './build/default/DTraceProviderBindings'\n\nThis warning can happen if you switch node versions. You can resolve this warning by reinstalling your node_modules.","excerpt":"","slug":"working-with-ghost","type":"basic","title":"Working with Ghost"}

Working with Ghost


[block:callout] { "type": "warning", "body": "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](doc:getting-started-guide) instead.", "title": "Developer Install" } [/block] [block:api-header] { "title": "Pre-requisites" } [/block] - **[Node.js](https://nodejs.org)** (See [Supported Node Versions](doc:supported-node-versions)) - **[Yarn](https://yarnpkg.com)** Ghost uses [`yarn`](https://yarnpkg.com) (**>= 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](https://yarnpkg.com/en/docs/install#alternatives-tab) because it works better with `nvm` but choose the best option for your development setup. [block:callout] { "type": "danger", "body": "`sudo` is **not** supported for local development setups, if your environment requires `sudo` when installing npm packages we highly recommend fixing that before continuing.", "title": "sudo for local development" } [/block] [block:api-header] { "title": "Initial Setup" } [/block] These commands only need to be run *once*, they're designed to get your Ghost install up and running quickly ๐Ÿš€ <br> 1. <pre><strong>git clone git@github.com:TryGhost/Ghost.git && cd ghost</strong></pre> - clone Ghost and make it your working directory <br> 2. <pre><strong>yarn run init</strong></pre> - 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` <br> 3. <pre><strong>knex-migrator init</strong></pre> - create and initialise your database [block:callout] { "type": "warning", "title": "yarn run init - Only for initial setup!", "body": "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](#grunt-master) command below if you want to get a working install up to date." } [/block] [block:api-header] { "title": "Day-to-day Development Commands" } [/block] ### Running Ghost There are a number of ways to start Ghost, each with their own benefits and trade-offs... <br> <pre><strong>grunt dev</strong></pre> - 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 <br> <pre><strong>grunt dev --server</strong></pre> - 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`](#grunt-build)) - useful to minimise startup time and preserve system resources if you know you won't be modifying any client files <br> <pre><strong>grunt prod</strong></pre> - builds admin client files for production - does not (!) watch for changes to server files or admin client files - start Ghost with `npm start --production` <br> <pre><strong>node index.js</strong></pre> - 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`](#grunt-build)) - useful when you want a quick startup and don't care about needing to restart manually if you change anything [block:callout] { "type": "warning", "title": "`node index.js` does not build client files:", "body": "`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." } [/block] ### Database commands <br> <pre><strong>knex-migrator reset</strong></pre> - if you want to reset your database you can run this command followed by `knex-migrator init` <br> <pre><strong>knex-migrator init</strong></pre> - initialises your database - it populates the tables and inserts all fixtures [block:callout] { "type": "info", "title": "Note:", "body": "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`" } [/block] ### Keeping up to date <pre id="grunt-master"><strong>grunt master</strong></pre> - 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` <br> <pre id="grunt-build"><strong>grunt build</strong></pre> - 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. <br> <pre><strong>grunt test-all</strong></pre> - run all server tests <br> <pre><strong>grunt test-unit</strong></pre> - run all server unit tests <br> <pre><strong>grunt test-integration</strong></pre> - run all server integration tests <br> <pre><strong>grunt test-routes</strong></pre> - run all server route tests <br> <pre><strong>grunt test:core/test...</strong></pre> - 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 <br> <pre><strong>grunt lint</strong></pre> - runs jshint and jshintrc across all of the server files <br> [block:api-header] { "title": "Troubleshooting" } [/block] ### 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.