Ghost Developer FAQs
Frequently asked questions and answers about running Ghost
API versioning
Ghost ships with a mature set of APIs. Each API endpoint has a status, which indicates suitability for production use. Read more about Ghost’s architecture. Stability Index Stable - forward compatible changes only Experimental - being actively worked on, may receive breaking changes Deprecated - scheduled for removal Accept-Version Header Accept-Version: v{major}.{minor} The ‘Accept-Version’ header allows clients to indicate the minimum version of Ghost they can operate with. It also allows Ghost to determine and communicate if any recent breaking changes are unsuitable for a given client.
Clustering, sharding, HA and other multi-server setups
Ghost doesn’t support load-balanced clustering or multi-server setups of any description, there should only be one Ghost instance per site. The recommended approach to achieve scale, performance & high availability is to put a cache and/or CDN in front of your blog; pages generated by Ghost are essentially static so there should be very little traffic hitting your Ghost server with a well configured cache. Error If you try to run Ghost on multiple nodes, you will run into errors such as Response code 405 (Method Not Allowed) - and find that the Ghost service needs to be constantly restarted for any content to reliably appear.
Filter property not working in routing
Working with more complex iterations of the filter property in the routes.yaml file can cause conflicts or unexpected behaviour. Here are the most common issues. Specify inverse filters In the current beta version of Dynamic Routing it’s necessary to specify the inverse of filters using - to ensure pagination is correct. For example: collections: /es/: permalink: /es/{slug}/ filter: tag:es /fr/: permalink: /fr/{slug}/ filter: tag:fr /: permalink: /{slug}/ filter: tag:-[fr,es] Order filters In a collection, the post lives in the first collection where it matches the filter, so it’s important to consider the order of your filters and place more generic filters towards the end.
How can I backup my site data?
Learn how to backup your self-hosted Ghost install When performing manual updates it’s always recommended to make a full backup of your site first, so if anything goes wrong, you’ll still have all your data. The fastest way to perform a backup is to use Ghost CLI to automatically generate a zip file containing all of your site data using the ghost backup command. If you need to perform a manual backup of your data, the following guide walks you through all of the steps.
How to resolve errors when running ghost start
If an error occurs when trying to run ghost start or ghost restart, try using ghost run first to check that Ghost can start successfully. The start and restart commands are talking to your process manager (e.g. systemd) which can hide underlying errors from Ghost. Find your Ghost log files in /content/logs/ to identify if the problem exists with Ghost itself, or the process manager.
Image upload issues
Image uploads can be affected by the default max upload size of 50mb. If you need more, you’ll need to increase the limit by editing your nginx config file, and setting the limit manually. Troubleshooting Log into your server Navigate to your Ghost installation folder with cd /var/www/ghost. Type: nano system/files/your-domain.conf to open your NGINX config file. Edit client_max_body_size {VALUE}M; Finally, press ctrl + x to exit. Nano will ask you if you want to save, type y for yes, and press enter to save the file.
Mail config error in Ghost with Google Cloud
There’s a known issue that Google Cloud Platform does NOT allow any traffic on port 25 on a Compute Engine instance. To fix this, explicitly set the transmission port to 2525 in order to send emails. Alternatively, we highly recommend using Mailgun which allows up to 10,000 emails per month for free.
Major Versions & Long Term Support
Major version release dates and end of life support for Ghost. Version Released End of Life Ghost 0.x 2013 Jan 2019 Ghost 1.x 2017 Jan 2020 Ghost 2.x 2018 Jan 2021 Ghost 3.x 2019 Jan 2022 Ghost 4.x 2021 Jan 2023 Ghost 5.x (Current) 2022 TBC At any one time the current major version of Ghost is under active development, whilst the previous version is maintained as the Long Term Support version (LTS).
Missing newsletter analytics
Open rates that are 0% may indicate that the connection between Ghost and Mailgun has stalled, which prevents Ghost from fetching your newsletter analytics. To recover your newsletter analytics, restart Ghost by running ghost restart from the command line. Restart Ghost as soon as possible because Mailgun logs are only kept for a limited time, after which the logs are no longer recoverable. It’s also best practice to restart Ghost when no newsletters are scheduled to be sent.
Missing SSL protocol
After installing Ghost a url for your site is set. This is the URL people will use to access your publication. Error If you see an error of ERROR: URL in config must be provided with protocol this means the URL has been set with HTTPS but the SSL protocol is missing. To fix Use ghost setup ssl in the ghost-cli to setup an SSL certificate for your publication.
Reverse proxying to Ghost
Ghost is designed to have a reverse proxy in front of it. If you use Ghost-CLI to install Ghost, this will be setup for you using nginx. If you configure your own proxy, you’ll need to make sure the proxy is configured correctly. The configuration used by Ghost CLI looks like this: location / { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Real-IP $remote_addr; proxy_set_header Host $http_host; proxy_pass http://127.0.0.1:2368; } client_max_body_size 50m; If you run into an infinite redirect loop when trying to configure your own proxy with nginx, apache, cloudfront or any other proxy and serving Ghost over HTTPS, this is due to the x-forwarded-proto header being set incorrectly.
Root user permissions fix
A fix for root user permissions problems Error We discovered that you are using the DigitalOcean One-Click install. You need to create a user with regular account privileges and migrate your installation to this user. Solution When you installed Ghost with the DigitalOcean One-Click install you probably set up your Ghost installation as a root user. As of Ghost-CLI 1.5.0, running Ghost commands as root is disallowed. Therefore you will need to migrate your current installation to a new Linux user.
Salt Incident Report: May 3rd, 2020
Analysis and retrospective of the critical Salt vulnerability on Ghost(Pro) Last Sunday, Ghost(Pro) - along with several thousand other services around the world - experienced an incident where a virus used to mine cryptocurrency was able to successfully infect servers within our private network. No customer data was accessed; however as a precaution we revoked all keys, sessions, passwords and certificates - and introduced additional firewalls throughout our network. We subsequently began work to rebuild every server in our network.
Supported Node versions
Ghost’s current recommended Node version is Node v20 LTS. Version Support Level 17.x and below Unsupported 18.x (Node v18 Hydrogen LTS) Supported 19.x Unsupported 20.x (Node v20 Iron LTS) Recommended 21.x and above Unsupported We use the recommended version of Node.js in production on Ghost(Pro), which means it’s heavily tested and the Ghost core team actively fixes issues. Running Ghost on the latest version of Node.js is not guaranteed to work, and we can’t offer support for any issues.
Supported providers for self-hosting
We recommend using Digital Ocean who provide a stable option on which Ghost can be installed and have a very active community and an official Ghost One-Click Application. Other providers which will work with Ghost include: Amazon EC2 Google Cloud Linode Vultr Dreamhost Most other VPS providers offer servers that are suitable for installing Ghost with a few exceptions: Auto-installers such as Softaculous Shared/cPanel hosting designed for PHP applications
Translation in Ghost
Creators from all over the world use Ghost. Publications abound in German, French, Spanish, Sinhalese, and Arabic—and the list keeps going! Below, we have collected together essential concepts, strategies, and known limitations when working with languages other than English in Ghost. Theme translation Ghost fully supports the ability to translate themes into different languages. This means that text in a theme is translated based on the language set in Ghost Admin.
Troubleshooting MySQL databases
If your MySQL database is not correctly configured for Ghost, then you may run into some issues. The solutions given are for self-hosted Ghost developers who are using the supported install method with ghost-cli. If you’re having problems with an unsupported custom install, check out the forum. Error ECONNREFUSED If you’re seeing an ECONNREFUSED error, which refers to port 3306, Ghost wasn’t able to connect to your MySQL server and you need to check if your server is running via the command line.
Unable to open sqlite3 database file
If the sqlite3 database file is not readable or writable by the user running Ghost, then you’ll run into some errors. Error Unable to open sqlite3 database file for read/write (exit code 236) To fix By default, this file exists in content/data/ but this path may also be configured in your config file. Ensure that the path in the config is correct and that the path is both readable and writable by the user running Ghost.
Update from Ghost 0.x versions
If you’re running Ghost 0.x versions, your site must be updated to Ghost 1.0 before it can be successfully updated to Ghost 2.0 and beyond. It’s recommended to update to the latest version of Ghost to keep your site and data secure, and gain access to the latest features in Ghost. For a successful upgrade, ensure that Ghost, Ghost CLI, and Node are all on compatible versions. Use our Node Compatibility Matrix as a reference.
Updating from deprecated Ghost-CLI
When managing your self-hosted Ghost publication using the recommended ghost-cli tooling, you should update your CLI version. If you are using a deprecated version and need to update in order to update or manage your Ghost site, some extra steps may be required. Use the following troubleshooting guide if you run into issues because you are using a deprecated version of the Ghost-CLI. Upgrading from <=1.1.3 Ghost-CLI 1.2.0 added a fix, and Ghost-CLI 1.
URL for tags and authors returns 404 errors
The tag and author taxonomies must be present in routes.yaml otherwise the URLs will not exist. By default, Ghost installs with the following: taxonomies: tag: /tag/{slug}/ author: /author/{slug}/ The permalink for tag and author can be amended, but taxonomies for tag and author must always be present for the URL for individual tags and authors to function correctly.
Using Cloudflare with Ghost
If you’ve added Cloudflare to your self-hosted Ghost publication and find that Ghost Admin doesn’t load after updates you may run into some errors in the JavaScript console: Error Open developer tools to check for errors in the JavaScript code: TypeError: n.item is not a function or Uncaught SyntaxError: Unexpected string To fix It is recommended that you add a page rule which turns off some RocketLoader, mirage2 and autominify for the path /ghost*, so these features don’t affect the Ghost admin panel.
Using nvm with local and production installs
This guide explains how to use nvm with local and production Ghost installs. Production install If nvm is installed locally in /root or /home then you’ll run into permission problems. Ghost requires a system wide installation. We recommend uninstalling nvm to avoid permission problems. A symlink from the local installation to usr/bin/node will not work. Uninstall nvm using: rm -rf $NVM_DIR ~/.npm ~/.bower unset NVM_DIR; which node; rm -rf {path_to_node_version} Open ~/.
What databases are supported in production?
MySQL 8 is the only supported database in production. As a small team developing open source software that is free to use, we provide a narrow set of environments that are officially supported to keep maintenance manageable. Ghost is built for use with Ubuntu, MySQL 8, nginx and Node.js LTS. MySQL 8 provides features that are optimal for Ghost installations, including the ability to store JSON, and features that help us deliver performance improvements.
Why do I have to set up Mailgun?
Ghost has the ability to deliver posts as email newsletters natively. A bulk-mail provider is required to use this feature and SMTP cannot be used — read more about mail config. Transactional email in Ghost can be configured to send with any SMTP, or another mail service that you prefer, using Ghost’s standard configuration setup. Bulk email delivery for newsletters is a new feature which requires a bulk mail API. Currently the only bulk mail API we support is Mailgun.
