Installing Ghost via the Ghost-CLI

If you install Ghost via the CLI, you don't have to create a custom configuration file. The CLI does this for you and asks you for the minimum required information. See screenshot below. After the installation was successful, you will find a custom configuration file. Continue reading to learn where the configuration files live and which properties can be set.

Custom configuration files

You are able to add a custom configuration file to override Ghost's default behaviour. Ghost's configuration is managed by nconf. A custom configuration file must be a valid JSON file and must be located in the root folder.

development environment
production environment

config.development.json

config.production.json

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.

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

Ghost in production

It's highly recommended to use the Ghost CLI to install and start Ghost in production.

Ghost in development

If you would like to start Ghost in development, you don't have to specify any environment, because development is default.

If you would like to test starting Ghost in production, you can use:

NODE_ENV=production node index.js

Debugging the configuration output

If you'd like to debug the configuration output, you can start Ghost with:

DEBUG=ghost:*,ghost-config node index.js

Running Ghost with config env variables

You're able to start Ghost using env variables for each config option like this:

URL=http://ghost.local:2368 node index.js

For nested config options, you'd need to separate them with two underscores:

DATABASE__CONNECTION__HOST=mysql node index.js

Warning

Arrays as in LOGGING__TRANSPORTS=[...] are currently not supported. This is a known issue.

Configuration options

Ghost has a number of configuration options which you can add to change things about how Ghost works.

Name
Required
Description

url

only in production

Set the public URL for your blog

adminUrl

no

You can specify a separated admin url.

mail

only in production

Add a mail service so that Ghost can send emails such as forgotten password and user invite emails

database

only in production

The type of database that Ghost uses. This is configured to sqlite3 by default and does not need editing

server

no

Host and port, or socket for Ghost to listen on

privacy

no

Disable the Ghost features listed in PRIVACY.md, e.g. update check, rpc ping, and google fonts

paths

no

Customise Ghost's internal paths, e.g. to the content directory

maintenance

no

Transform your blog into maintenance mode.

referrerPolicy

no

Control the content attribute of the meta referrer tag.

useMinFiles

no

Generate assets url with .min notation.

storage

no

Set a custom storage adapter, read more here Using a custom storage module

scheduling

no

Set a custom scheduling adapter, read more here Using a custom scheduling module

logging

no

Configure logging for Ghost.

spam

no

Configure spam settings.

caching

no

Configure caching settings.

URL

One of the first things you should do after installing a Ghost blog, is set the url for your blog. 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://.

Subpath

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 your config file, this means there is a mismatch between the url configured, and the url you used to access your blog's admin panel. To solve this you must either update your config file so the url is correct, or change to using the url already configured in your config file when accessing the admin panel.

Note

As with any config 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.

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.

If you installed Ghost via the Ghost CLI, you can setup SSL easily. Check out the SSL setup instructions in the CLI knowledge base.

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:

"adminUrl": "https://example.com"

This will force any HTTP requests for the admin to be redirected via HTTPS.

Mail

Possibly the most important piece of configuration is setting up mail so that Ghost can let you reset your password if you forget it. We have a separate Mail Configuration which will guide you through this process.

Database

By default, Ghost comes configured to use MySQL.

MySQL

"database": {
  "client": "mysql",
  "connection": {
    "host": "127.0.0.1",
    "user": "your_database_user",
    "password": "your_database_password",
    "database": "your_database_name"
  }
}

Sqlite3

Alternatively you can configure sqlite3.

"database": {
  "client": "sqlite3",
  "connection": {
    "filename": "content/data/ghost-test.db"
  },
  "useNullAsDefault": true,
  "debug": false
}

Note

The default charset is utf8mb4 and can't be overridden.

Number of connections

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

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

Privacy

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

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,
    "useGravatar": false,
    "useRpcPing": false,
    "useStructuredData": false
}

Update Check

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

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.

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
}

Paths

The configuration of paths can be relative or absolute.

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": "content/"
},

Note

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.

Note

If you configure a custom content path, the content directory must exist and contain sub directories for data, images, themes, logs and adapters, otherwise Ghost might fail to start.

Maintenance Mode

To set maintenance mode:

"maintenance": { 
  "enabled": true 
}

This will serve 503 HTTP response.

Referrer Policy

You can set the value of the content attribute of the meta referrer HTML tag by adding referrerPolicy to your config. origin-when-crossorigin is default.

Read through all possible options here.

Logging

You can configure how Ghost should log.

"logging": {
  "path": "something/",
  "level": "info",
  "rotation": {
    "enabled": true,
    "count": 15,
    "period": "1d"
  },
  "transports": ["stdout", "file"]
}
Name
Description

level

The default log level is info, which will print all info, warning and error logs.Info logs are for example requests.

You can set it to error to only print errors.

rotation

You can tell Ghost to rotate your log files.

By default, it's true for production and false for development environment.

Read more about log file rotation here.

transports

The transport define where Ghost should log to.

By default, Ghost will write to stdout and into file for production and to stdout only for development.

e.g. ["file", "stdout"]

path

By default, Ghost logs into your content path e.g. content/logs/.

You can set any path here. But note: the permissions must be correct to write into this folder.

Spam

You can tell Ghost how to treat spam requests.

See spam configuration in Ghost.

Caching

Caching for sitemaps, redirects or assets can be configured via the caching property.
See caching configuration in Ghost.

Config