How do I configure Ghost (blog)?

After running Ghost for the first time, you’ll find a file called config.js in the root directory of Ghost, along with index.js. This file allows you to set environment level configuration for things like your URL, database, and mail settings. If you haven’t yet run Ghost for the first time, you won’t have this file yet. You can create one by copying the config.example.js file and calling it config.js – that’s what Ghost does when it starts.

As part of installing Ghost, you will need to configure the url and mail settings. To configure your Ghost settings, open config.js in your favourite editor (if you don’t have one, we recommend brackets, and start changing the settings for your desired environment. If environments aren’t something you’ve come across yet, please read of the about environments section below.

Configuration options

Ghost has a number of configuration options which you can add to change things about how Ghost works. The first two options, url and mail need to be edited when you first start your Ghost blog, in order for it to function correctly.

URL

One of the first things you’ll need to do after installing a Ghost blog, is set the URL for your blog inconfig.js. This URL must match the URL you will use to access your blog, if it is not set correctly you may get the error Access Denied from url as well as finding that RSS and other external links do not work correctly.

url should be set to the full URL for your blog including http:// or if you are using SSL for your blog and want both the admin and frontend to always be served securely, use https://. See the section on SSL configuration for more information about how to configure your URL if you want to use SSL for just the admin or only for secure requests.

If you want to Ghost to appear on a subpath or subdirectory of your domain, e.g.http://my-ghost-blog.com/blog/ the full path needs to be specified in the url field. This option is only available when self-hosting Ghost.

If you get the error Access Denied from url: someurl.com. Please use the url configured in config.js, this means there is a mismatch between the url configured in your config.js, and the url you used to access your blog’s admin panel. To solve this you must either update your config.js file so the url is correct, or change to using the url already configured in config.js when accessing the admin panel.

Note: As with any config.js change, once you’ve updated your url field so that your url is correct, you’ll need to restart Ghost for it to take effect.

Email

Possibly the most important piece of configuration is setting up email so that Ghost can let you reset your password if you forget it. We have a separate guide to email configuration which will guide you through this process. This includes documentation on mail.from which allows you to customise the email address which mail is sent from.

SSL

Ghost has a number of configuration options for working with SSL, and securing the URLs for the admin (/ghost/) and the frontend of your blog. SSL is very important for the admin panel, without SSL your username and password are sent in plaintext. SSL ensures your details are kept private.

For details of how to setup SSL, please follow our SSL Guide

If you just setup SSL for your blog, and leave your url starting with http://, Ghost will serve requests made via HTTPS securely, and leave plain HTTP requests alone. Insecure and secure requests will both be available, and there will be no redirects from one to the other.

If you setup SSL for your blog and change your url to https://, Ghost will serve all requests securely, all requests made via plain HTTP will be redirected to HTTPS. Your blog will always be secure.

If you only want to serve your admin panel (i.e. /ghost/) via SSL, then you can leave your url as starting with http:// and instead set the following option:

forceAdminSSL: true

This will force any HTTP requests for the admin to be redirected via HTTPS. If you would prefer to reject insecure requests (403 error), rather than redirect them, you can enforce this by setting forceAdminSSL as follows:

forceAdminSSL: {redirect: false}

If you’d like to serve the SSL version of your blog from a different URL to the one configured in urlyou can do so by configuring an alternative:

url: http://myblog.com,
urlSSL: https://secure.myblog.com

Database

By default, Ghost comes configured to use an SQLite database, which requires no configuration.

Alternatively Ghost can also be used with a MySQL database by changing the database configuration. You must create a database and user first, you can then change the existing sqlite3 config to something like:

database: {
  client: 'mysql',
  connection: {
    host     : '127.0.0.1',
    user     : 'your_database_user',
    password : 'your_database_password',
    database : 'ghost_db',
    charset  : 'utf8'
  }
}

You can also limit the number of simultaneous connections should you wish, by using the pool setting.
The default values are min: 2, max: 10, which means Ghost will always maintain 2 active database connections. You can set min: 0 to prevent this.

database: {
  client: ...,
  connection: { ... },
  pool: {
    min: 2,
    max: 20
  }
}

Ghost can also be used with PostGreSQL. Support for Postgres is currently second class compared to SQLite & MySQL – there is a build run against it, but very minimal manual testing. At present we are considering downgrading support to ‘community’ – this means we will permit the builds to fail, accept patches, but not manage support or any manual testing within the core team. Therefore using pg with Ghost should only be done if you’re comfortable patching issues.

More details about the database configuration can be found in the knex library documentation.

Server

The server host and port are the IP address and port number that Ghost should listen on for requests. In the majority of cases this will not need to be changed, with requests being routed from port 80 to Ghost by either nginx (recommended) or apache.

server: {
    host: '127.0.0.1',
    port: '2368'
}

Unix Sockets

Ghost can also be configured to listen on a unix socket by changing the server config to something like:

server: {
    socket: 'path/to/socket.sock'
}

The default permissions are 0660, but this can also be configured by expanding the socket config:

server: {
    socket: {
        path: 'path/to/socket.sock',
        permissions: '0666'
   }
}

Gzip Compression

As of Ghost 0.5, gzip compression is enabled by default. This results in significant improvements to page load speed. You can disable this feature with the following option:

compress: false

Privacy

As of Ghost 0.5.2, there are a set of configuration options available to turn off all of the features listed in the PRIVACY.md file. All of these feature are enabled by default, but users may choose to turn them off in order to protect their privacy.

If you simply want to turn off all of these features, you can do so by adding the following to your config.js (please note once the useTinfoil flag is set to true, no other privacy flags will take effect):

privacy: {
    useTinfoil: true,
}

Alternatively, you can configure each of the features individually.

privacy: {
    useUpdateCheck: false,
    useGoogleFonts: false,
    useGravatar: false,
    useRpcPing: false,
    useStructuredData: false
}

Update Check

Ghost 0.4 introduced an automatic update check service to let you know when a new version of Ghost is available (woo!). Ghost.org collects basic anonymous usage statistics from update check requests. For more more information, see the update-check.js file in Ghost core.

See PRIVACY.md#automatic-update-checks for more details.

Disable with:

privacy: {
    useUpdateCheck: false
}

Please be sure to subscribe to emails from Ghost, or the dev blog, so that you are still informed about new versions.

Google Fonts

See PRIVACY.md#google-fonts for more details.

Disable with:

privacy: {
    useGoogleFonts: false
}

Please Note this will not disable any Google Fonts used by your theme.

Gravatar

See PRIVACY.md#gravatar for more details.

Disable with:

privacy: {
    useGravatar: false
}

RPC Ping

See PRIVACY.md#rpc-pings for more details.

Disable with:

privacy: {
    useRpcPing: false
}

Structured Data

See PRIVACY.md#structured-data for more details.

Disable with:

privacy: {
    useStructuredData: false
}

File Storage

Some platforms such as Heroku do not have a persistent file system. As a result of this, any uploaded images are likely to go missing at some point. It is possible to disable Ghost’s file storage features:

fileStorage: false

When file storage is disabled, Ghost’s image upload tools will prompt you to enter a URL by default, thereby preventing you from uploading files that will go missing.

Paths

If you wish to use a content directory that does not live inside the Ghost folder, then you can do this by specifying a paths object with a new contentPath:

paths: {
    contentPath: path.join(__dirname, '/path/to/content/dir/')
},

Please note that if you are using an SQLite database, you will also need to update the path to your database to match the new location of the data folder. The content directory must contain sub directories for apps, data, images and themes or Ghost may fail to start. In future it’s intended that Ghost will offer more fine-grained control via the paths object.

About Environments

Node.js, and therefore Ghost, has the concept of environments built in. Environments allow you to create different configurations for different modes in which you might want to run Ghost. By default Ghost has two main built-in modes: development and production. There are also configurations for several testing environments in the config.js file. You do not need to remove configuration you aren’t using.

The differences between the two modes mean that development is geared towards developing and debugging Ghost, whereas production is intended to be used when you’re running Ghost as a real live blog. You’ll find the log output is different in the two modes, the level of concatenation and minification of assets like js and css is higher in production mode, development mode provides more warnings about potential problems with themes and possibly the most noticable difference is that theme template files are cached in production mode so you’ll want to use development mode when creating themes. Essentially, production mode gives priority to performance, whereas development mode gives priority to information.

As Ghost progresses, these differences will grow and become more apparent, and therefore it will become more and more important that any public blog runs in the production environment. This perhaps begs the question, why development mode by default, if most people are going to want to run it in production mode? Ghost has development as the default because this is the environment that is best for debugging problems, which you’re most likely to need when getting set up for the first time.

Using Environments

In order to set Ghost to run under a different environment, you need to use an environment variable. For example if you normally start Ghost with node index.js you would use:

NODE_ENV=production node index.js

Or if you normally use forever:

NODE_ENV=production forever start index.js

Or if you’re used to using npm start you could use the slightly easier to remember:

npm start --production

Why use npm install –production?

We have been asked a few times why, if Ghost starts in development mode by default, does the installation documentation say to run npm install --production? This is a good question! If you don’t include --production when installing Ghost, nothing bad will happen, but it will install a tonne of extra packages which are only useful for people who want to develop Ghost core itself. This also requires that you have one particular package, grunt-cli installed globally, which has to be done with npm install -g grunt-cli, it’s an extra step and it’s not needed if you just want to run Ghost as a blog.