For self-hosted Ghost users, a custom configuration file can be used to override Ghost’s default behaviour. This provides you with a range of options to configure your publication to suit your needs.
ghost-cli
, a custom configuration file is created for you by default. There are some configuration options which are required by default, and many optional configurations.
The three required options are url
and database
which are configured during setup, and mail
which needs to be configured once you’ve installed Ghost.
This article explains how to setup your mail config, as well as walk you through all of the available config options.
ghost restart
.
Since Node.js has the concept of environments built in, Ghost supports two environments: development and production. All public Ghost publications run in production mode, while development mode can be used to test or build on top of Ghost locally.
config.development.json
config.production.json
config.local.json
config.development.json
so you can use both at the same time.
Name | Required? | Description |
---|---|---|
url | In production | Set the public URL for your blog |
database | In production | Type of database used (default: MySQL) |
mail | In production | Add a mail service |
admin | Optional | Set the protocol and hostname for your admin panel |
server | Optional | Host and port for Ghost to listen on |
privacy | Optional | Disable features set in privacy.md |
security | Optional | Disable security features that are enabled by default |
paths | Optional | Customise internal paths |
referrerPolicy | Optional | Control the content attribute of the meta referrer tag |
useMinFiles | Optional | Generate assets URL with .min notation |
storage | Optional | Set a custom storage adapter |
scheduling | Optional | Set a custom scheduling adapter |
logging | Optional | Configure logging for Ghost |
spam | Optional | Configure spam settings |
caching | Optional | Configure HTTP caching settings |
compress | Optional | Disable compression of server responses |
imageOptimization | Optional | Configure image manipulation and processing |
opensea | Optional | Increase rate limit for fetching NFT embeds from OpenSea.io |
tenor | Optional | Enable integration with Tenor.com for embedding GIFs directly from the editor |
twitter | Optional | Add support for rich Twitter embeds in newsletters |
portal | Optional | Relocate or remove the scripts for Portal |
sodoSearch | Optional | Relocate or remove the scripts for Sodo search |
comments | Optional | Relocate or remove the scripts for comments |
ghost-cli
, the install process requests the URL during the setup process.
Enter the URL that is used to access your publication. If using a subpath, enter the full path, https://example.com/blog/
. If using SSL, always enter the URL with https://
.
/ghost/
and the frontend of your publication. Without SSL your username and password are sent in plaintext.
ghost-cli
prompts to set up SSL during the installation process. After a successful SSL setup, you can find your SSL certificate in /etc/letsencrypt
.
If you see errors such as access denied from url
, then the provided URL in your config file is incorrect and needs to be updated.
"ssl": "Amazon RDS"
:
\n
(you can get the single line string with awk '{printf "%s\\n", $0}' CustomRootCA.crt
) and add it to the configuration:
config.production.json
ghost restart
for your changes to take effect. These same credentials can be used for development environments, by adding them to the config.development.json
file.
Mailgun provides a sandbox mode, which restricts emails to authorized recipients. Once sandbox mode is enabled, add and verify the email addresses you want to send emails to prior to testing.
config.production.json
with the following for a secure connection:
ghost restart
for your changes to take effect.
config.[env].json
file as follows:
mail.from
as the default email address:
Email type | Address used | Examples |
---|---|---|
Member notifications | Support, Default | Signup/sign links, comment replies |
Newsletters | Newsletter, Default | Configurable per newsletter |
Staff notifications | Default | Recommendations, signups |
origin-when-crossorigin
is the default. Read through all possible options.
storage
, caching
, sso
, and scheduling
.
Use the adapters
configuration block with “storage”, “caching”, “sso,” or “scheduling” keys to initialize a custom adapter. For example, the following configuration uses storage-module-name
to handle all storage
capabilities in Ghost. Note that the active
key indicates a default adapter used for all features if no other adapters are declared.
cache
adapter only for the imageSizes
feature, configure the cache adapter as follows:
custom-redis-cache-adapter
only for the imageSizes
cache feature with these values:
content/images
or an alternative custom content path that’s been configured.
To use a custom storage adapter, your custom configuration file needs to be updated to provide configuration for your new storage module and set it as active:
images
- storage of image files uploaded through POST '/images/upload'
endpointmedia
- storage of media files uploaded through POST '/media/upload'
and POST/media/thumbnail/upload
endpointsfiles
- storage of generic files uploaded through POST '/files/upload'
endpointstorage
inside content/adapters
content/adapters/storage
, create a file or a folder: content/adapters/storage/my-module.js
or content/adapters/storage/my-module
— if using a folder, create a file called index.js
inside it.save
- The .save()
method stores the image and returns a promise which resolves the path from which the image should be requested in future.exists
- Used by the base storage adapter to check whether a file exists or notserve
- Ghost calls .serve()
as part of its middleware stack, and mounts the returned function as the middleware for serving imagesdelete
read
get
helpers. Note that this adapter requires Redis to be set up and running in addition to Ghost.
To use the Redis cache adapter, change the value for the cache adapter from “Memory” to “Redis” in the site’s configuration file. In the following example, image sizes and the tags Content API endpoint are cached in Redis for optimized performance.
ttl
value is in seconds.
imageSizes
feature supports full customization. Configuration is as follows:
cache
block should have 2 items:
"imageSizes"
, which contains the name of your custom caching modulekey
that reflects the name of your caching module, containing any config your module needscache
inside content/adapters
content/adapters/cache
, create a file or a folder: content/adapters/cache/my-cache-module.js
or content/adapters/cache/my-cache-module
- if using a folder, create a file called index.js
inside it.get
- fetches the stored value based on the key value (.get('some_key')
). It’s an async method - the implementation returns a Promise
that resolves with the stored value.set
- sets the value in the underlying cache based on key and value parameters. It’s an async method - the implementation returns a Promise
that resolves once the value is stored.keys
- fetches all keys present in the cache. It’s an async method — the implementation returns a Promise
that resolves with an array of strings.reset
- clears the cache. This method is not meant to be used in production code - it’s here for test suite purposes only.level
info
which prints all info, warning and error logs. Set it to error
to only print errors.
rotation
transports
path
content/logs/
. Set any path but ensure the permissions are correct to write into this folder.
useLocalTime
false
.
caching
configuration is available for responses containing public
value in Cache-Control
header. Each key under caching
section contains maxAge
property that controls the max-age
value in Cache-Control
header. For example, the following configuration:
Cache-Control: public, max-age=10
header with all Content API responses, which might be useful to set for high-volume sites where content does not change often.
The following configuration keys are available with default maxAge
values:
"maxAge": 0
, controls responses coming from public Ghost pages (like the homepage)"maxAge": 0
, controls responses coming from Content API"maxAge": 3600
, controls responses for robots.txt
files"maxAge": 3600
, controls responses for sitemap.xml
files"maxAge": 86400
, controls responses for sitemap.xsl
files"maxAge": 86400
, controls responses coming from */.wellknown/*
endpoints"maxAge": 86400
, controls responses for OPTIONS
CORS requests"maxAge": 31536000
, controls responses for public assets like public/ghost.css
, public/cards.min.js
, etc."maxAge": 31536000
, controls 301 redirect responses"maxAge": 31536000
, controls redirects coming from custom redirects"compress": true
. Alternatively, you can turn it off with "compress": false
.
config.[env].json
file using:
_o
.
"url": false
.
"url": false
.
"url": false
.