GHOST CMS - 配置 Config

Posted 2021-03-21 qduck

Config

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用户，可以使用自定义配置文件覆盖Ghost的默认行为。这为您提供了一系列选项来配置您的发布以满足您的需要。

Overview概述

When you install Ghost using the supported and recommended method using 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 -cli的方法安装Ghost时，默认情况下会为您创建一个自定义配置文件。默认情况下需要一些配置选项和许多可选配置。

三个必需的选项是在安装过程中配置的url和数据库，以及安装Ghost后需要配置的邮件。

本文将解释如何设置邮件配置，并介绍所有可用的配置选项。

Custom configuration files自定义配置文件

The configuration is managed by nconf. A custom configuration file must be a valid JSON file located in the root folder and changes to the file can be implemented using 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.

配置由nconf管理。自定义配置文件必须是位于根文件夹中的有效JSON文件，可以使用ghost restart实现对该文件的更改。

因为Node.js有内建环境的概念，所以Ghost支持两种环境:开发和生产。所有的公共Ghost出版物都是在生产模式下运行，而开发模式可以在本地测试或构建Ghost。

Check out the official install guides for development and production.

查看开发和生产的官方安装指南。

The configuration files reflect the environment you are using:

配置文件反映了你使用的环境

• config.development.json
• config.production.json

Ghost in development

If you would like to start Ghost in development, you don‘t have to specify any environment, because development is default. To test Ghost in production, you can use:

如果您想在开发中启动Ghost，您不必指定任何环境，因为development是默认的。要在生产中测试Ghost，可以使用:

NODE_ENV=production node index.js

Debugging the configuration output 调试配置输出

Start Ghost with:

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

Running Ghost with config env variables  使用配置环境变量运行Ghost

Start Ghost using environment variables which match the name and case of each config option:

使用与每个配置选项的名称和大小写匹配的环境变量启动Ghost

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

For nested config options, separate with two underscores:

嵌套的配置选项，用两个下划线分开:

database__connection__host=mysql node index.js

Configuration options

There are a number of configuration options which are explained in detail in this article. Below is an index of all configuration options:

有许多配置选项将在本文中详细解释。以下是所有配置选项的索引:

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, or socket for Ghost to listen on
privacy	Optional	Disable features set in privacy.md
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 caching settings
compress	Optional	Disable compression of server responses
imageOptimization	Optional	Configure image manipulation and processing

URL

(Required in production)

Once a Ghost publication is installed, the first thing to do is set a url. When installing using ghost-cli the install process request 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://.

SSL

We always recommend using SSL to run your Ghost publication in production. Ghost has a number of configuration options for working with SSL, and securing the URLs for the admin /ghost/ and the frontend of your publication. Without SSL your username and password are sent in plaintext.

ghost-cli prompts to setup 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.

Database

(Required in production)

Ghost is configured using MySQL by default:

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

Alternatively you can configure sqlite3:

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

Number of connections

It‘s possible to limit the number of simultaneous connections using the pool setting. The default values are a minimum of 2 and a maximum of 10, which means Ghost always maintains two active database connections. You can set the minimum to 0 to prevent this:

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

SSL

In a typical Ghost installation the MySQL database will be on the same server as Ghost itself. With cloud computing and database-as-a-service providers you might want to enable SSL connections to the database.

If your Certificate CA or the CA of your database provider is in the Mozilla trusted CA list you can enable SSL by adding "ssl": true to the database connection configuration:

"database": {
  "client": "mysql",
  "connection": {
    "host": "your_cloud_database",
    "port": 3306,
    "user": "your_database_user",
    "password": "your_database_password",
    "database": "your_database_name",
    "ssl": true
  }
}

This has been confirmed to work with Azure Database for MySQL. To find out if your provider is supported see the Mozilla Included CA Certificate List.

For Amazon RDS you‘ll need to configure the connection with "ssl": "Amazon RDS":

"database": {
  "client": "mysql",
  "connection": {
    "host": "your_cloud_database",
    "port": 3306,
    "user": "your_database_user",
    "password": "your_database_password",
    "database": "your_database_name",
    "ssl": "Amazon RDS"
  }
}

Custom or self-signed certificates are a little more advanced. You‘ll need to output your CA certificate (not your CA private key) as a single line string including literal new line characters   (you can get the single line string with awk ‘{printf "%s\n", $0}‘ CustomRootCA.crt) and add it to the configuration:

"database": {
  "client": "mysql",
  "connection": {
    "host": "your_cloud_database",
    "port": 3306,
    "user": "your_database_user",
    "password": "your_database_password",
    "database": "your_database_name",
    "ssl": {
      "ca": "-----BEGIN CERTIFICATE-----
MIIFY... truncated ...pq8fa/a
-----END CERTIFICATE-----
"
    }
  }
}

For a certificate chain, include all CA certificates in the single line string:

"database": {
  "client": "mysql",
  "connection": {
    "host": "your_cloud_database",
    "port": 3306,
    "user": "your_database_user",
    "password": "your_database_password",
    "database": "your_database_name",
    "ssl": {
      "ca": "-----BEGIN CERTIFICATE-----
MIIFY... truncated ...pq8fa/a
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFY... truncated ...wn8v90/a
-----END CERTIFICATE-----
"
    }
  }
}

Mail

(Required in production)

The most important piece of configuration once you‘ve been through the install process is to setup mail. Mail configuration allows Ghost to send emails such as lost password and user invite emails, or member signup emails if you‘re running a membership publication with Ghost.

Ghost uses Nodemailer 0.7 under the hood, and tries to use the direct mail service if available - but a more reliable solution is to setup mail using an external service.

Setup an email sending account

Choose an external email service and sign up and verify your account. We highly recommend using Mailgun which allows up to 10,000 emails per month for free.

Configure mail with Mailgun

Mailgun allows you to use your own domain for sending transactional emails. Otherwise you can use a subdomain that Mailgun provide you with (also known as the sandbox domain, limited to 300 emails per day). You can change this at any time.

Make a note of your domain information

Once your domain is setup, find your new email service SMTP username and password that has been created for you (this is not the ones you used to sign up for Mailgun with). You can find this under "Domain Information" and make a note of the following details:

• Default SMTP login
• Default password

Update your config.production.json file

Open your production config file in any code editor and paste the username and password you just copied into the defined fields, for example:

"mail": {
    "transport": "SMTP",
    "options": {
        "service": "Mailgun",
        "auth": {
            "user": "[e-mail]",
            "pass": "1234567890"
        }
    }
}

Once you are finished, hit save and then run ghost restart for your changes to take effect. It is possible to reuse your settings for a development environment if you have both, by making the same changes to config.development.json.

Secure connection

According your Mailgun settings you may want to force secure connection and the SMTP port.

"mail": {
    "transport": "SMTP",
    "options": {
        "service": "Mailgun",
        "host": "smtp.eu.mailgun.org",
        "port": 465,
        "secureConnection": true,
        "auth": {
            "user": "[e-mail]",
            "pass": "1234567890"
        }
    }
}

Amazon SES

It‘s also possible to use Amazon Simple Email Service. Use the SMTP username and password given when signing up and configure your config.[env].json file as follows:

"mail": {
    "transport": "SMTP",
    "options": {
        "host": "YOUR-SES-SERVER-NAME",
        "port": 465,
        "service": "SES",
        "auth": {
            "user": "YOUR-SES-ACCESS-KEY-ID",
            "pass": "YOUR-SES-SECRET-ACCESS-KEY"
        }
    }
}

From address

By default the ‘from‘ address for mail sent from Ghost is set to the title of your publication, for example <[e-mail]>. To override this to something different, use:

"mail": {
    "from": "[e-mail]",
}

A custom name can also optionally be provided:

"mail": {
    "from": "‘Acme Support‘ <[e-mail]>",
}

Try to use a real, working email address - as this greatly improves delivery rates for important emails sent by Ghost (Like password reset requests and user invitations). If you have a company support email address, this is a good place to use it.

Admin URL

Admin can be used to specify a different protocol for your admin panel or a different hostname (domain name). It can‘t affect the path at which the admin panel is served (this is always /ghost/).

"admin": {
  "url": "http://example.com"
}

Server

The server host and port are the IP address and port number that Ghost listens on for requests. By default, requests are routed from port 80 to Ghost by 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:

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

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

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

Privacy

All features inside the privacy.md file are enabled by default. It is possible to turn these off in order to protect privacy:

• Update check
• Gravatar
• RPC ping
• Structured data

For more information about the features, read the privacy.md page.

To turn off all of the features, use:

"privacy": {
    "useTinfoil": true
}

Alternatively, configure each feature individually:

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

Paths

The configuration of paths can be relative or absolute. To use a content directory that does not live inside the Ghost folder, specify a paths object with a new contentPath:

"paths": {
    "contentPath": "content/"
},

When using a custom content path, the content directory must exist and contain sub directories for data, images, themes, logs and adapters.

If using an Sqlite database, you‘ll also need to update the path to your database to match the new location of the data folder.

Referrer Policy

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.

Logging

Configure how Ghost should log, for example:

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

level

The default log level is info which prints all info, warning and error logs. Set it to errorto only print errors.

rotation

Tell Ghost to rotate your log files. By default Ghost keeps 10 log files and rotates every day. Rotation is enabled by default in production and disabled in development.

transports

Define where Ghost should log to. By default Ghost writes to stdout and into file for production, and to stdout only for development.

path

Log your content path, e.g. content/logs/. Set any path but ensure the permissions are correct to write into this folder.

Spam

Tell Ghost how to treat spam requests.

Caching

Configure caching for sitemaps, redirects or assets.

Compress

The compression flag is turned on by default using "compress": true. Alternatively you can turn it off with "compress": false.

Image optimisation

When uploading images into the Ghost editor, they are automatically processed and compressed by default. This can be disabled in your config.[env].json file using:

"imageOptimization": {
  "resize": false
}

Image compression details:

• Resize the image to 2000px max width
• JPEG‘s are compressed to 80% quality.
• Meta data removed

The original image is kept with the suffix _o.

Summary

You‘ve explored how to configure a self-hosted Ghost publication with the required config options, as well as discovered how to make use of the optional config options that are available in the config.[env].json file.

If you run into any issues when configuring your publication, try searching this site to find information about common error messages and issues.