How to Install Ghost CMS on a Local Machine: Step-by-Step Guide

Step 1: Installing Prerequisites

Before installing Ghost CMS, ensure that the necessary tools are set up on your machine.

1.1. Install Node.js and npm

Ghost runs on the Node.js platform, so you need to install Node.js first. Go to the official Node.js website and download the latest LTS (Long-Term Support) version. Ghost only supports LTS versions of Node.js, so this is essential.

Once Node.js is installed, verify that it’s installed correctly by running the following commands in your terminal:

node -v
npm -v

If Node.js is not installed, then you can use these instructions.

1.2. Install Ghost-CLI

The easiest way to install Ghost CMS is by using the Ghost-CLI, a command-line tool that simplifies installation and management. You can install it globally on your machine using npm:

npm install ghost-cli@latest -g

To check if Ghost-CLI was installed successfully, run:

ghost -v

This should display the Ghost-CLI version.

Step 2: Installing Ghost

With all the prerequisites set up, you can now install Ghost itself.

2.1. Set up a folder for Ghost

First, create a directory where you want to install Ghost:

mkdir ghost-local
cd ghost-local

2.2. Install Ghost

Inside your chosen directory, run the following command to install Ghost:

ghost install local

The local flag tells Ghost to install in development mode on your local machine. Ghost-CLI will handle most of the configuration and setup automatically.

During the installation, Ghost will:

  • Download the necessary Ghost files.
  • Set up the database connection.
  • Start the Ghost server locally.

Once the installation is complete, you should see a message indicating that Ghost has started, along with a local URL, such as:

Ghost was installed successfully! To complete setup of your publication, visit: 
http://localhost:2368/ghost/

Step 3: Access Ghost Admin Panel

To start using Ghost CMS, open your browser and go to http://localhost:2368/ghost. This will take you to the Ghost admin panel, where you can create an admin account and start building your site.

Step 4: Managing Ghost

Here are some useful Ghost-CLI commands for managing your local Ghost instance:

Start Ghost: If Ghost is not running, start it with:

ghost start

Stop Ghost: To stop the Ghost server, use:

ghost stop

Restart Ghost: To restart Ghost, use:

ghost restart

Uninstall Ghost: If you want to uninstall Ghost from the current directory, run:

ghost uninstall

Step 5: Troubleshooting

If you encounter any issues during installation, the Ghost-CLI typically provides clear error messages. Some common problems and solutions include:

5.1. Port in use

If you get an error that port 2368 is already in use, you can either stop the conflicting service or change Ghost’s default port using:

ghost config server.port 2369

5.2. Permission issues

If you encounter permission errors, ensure you are running commands with appropriate privileges. You may need to prefix commands with sudo (for Unix-based systems).

5.3. Node.js Version Incompatibility

When installing or running Ghost CMS, one common issue is using an unsupported version of Node.js. Ghost only supports specific Node.js versions that are officially compatible. If your system has an incompatible version of Node.js installed, you will see an error message like the one below:

The version of Node.js you are using is not supported.
Supported: ^12.22.1 || ^14.17.0 || ^16.13.0 || ^18.0.0 || ^20.11.1
Installed: 22.7.0

This error indicates that your currently installed Node.js version (e.g., 22.7.0) is not compatible with Ghost. To resolve this, you’ll need to switch to one of the supported versions: ^12.22.1, ^14.17.0, ^16.13.0, ^18.0.0, or ^20.11.1. The best way to manage Node.js versions is by using nvm (Node Version Manager). You can find installation instructions for nvm here. After installing, use nvm to install a compatible Node.js version:

nvm install 20.11.1
nvm use 20.11.1

Conclusion

You’ve successfully installed Ghost CMS on your local machine! Now, you can start developing and testing your website locally. Once you’re ready to deploy your site to production, the process is similar but with additional steps for setting up a production environment with a hosting provider.

Ghost’s flexibility and focus on content make it an excellent choice for blogs and content-driven websites. Enjoy building your new site!

Useful Links

Here are some helpful resources to assist you with installing and managing Ghost CMS:

These resources will help ensure a smooth installation and management process for your Ghost CMS setup.

YouTube Video:

How to install Ghost CMS on a local machine.