Knowledge Base

Ghost-CLI is a tool designed to provide a straightforward install, run and update process for Ghost. In particular, it does the following:

  • Configures NGINX
  • Sets up MySQL
  • Configures systemd
  • Handles user management and permissions
  • Configures Ghost
  • Allows access to Ghost log files
  • Provides a management console to start/stop Ghost
  • Repairs broken installations
  • Updates Ghost to the latest version

NGINX

NGINX is used to serve every Ghost publication. The CLI generates a NGINX config file for your domain and saves it in:

cd /var/www/ghost;
cat system/files/your-domain.conf`

The file your-domain.conf will be linked to /etc/nginx/sites-available/your-domain.conf to active the configuration for the blog.

Warning

If you modify this file, please run sudo service nginx restart.

SSL

You can setup SSL via the CLI very easily. The CLI will generate a free SSL certificate from Let’s Encrypt if you want. The CLI will also update your NGINX config file to serve the port 443.

How to find your ssl configuration

After a successful ssl setup, you can find your ssl certificate in ls -la ~/.acme/.
Furthermore you can find more details about the SSL configuration in these NGINX files:

cd ghost-installation-folder; 
cat system/files/your-domain.conf
cat system/files/ssl-params.conf

Let's Encrypt

Let’s Encrypt provides SSL certificates that are accepted by browsers, free of charge! This is provided by the non-profit Internet Security Research Group (ISRG). The Ghost-CLI will offer you to generate a free ssl certificate as well as renew it every 60 days.

Difference between systemd and local process manager

systemd is the default way of starting/stopping applications on Ubuntu. The advantage is that if Ghost crashes, systemd will restart your instance, as well as it will start Ghost after server reboot. This is the default and recommended option installing Ghost.

Alternatively, you can use the local process manager. In this case the CLI would spawn a process for Ghost. Read here how.

Permissions

File Ownership

Ghost-CLI will create a new system user and user-group called ghost during the installation process. The ghost user will be used to run your Ghost process in systemd.

This means that Ghost will run with a user that has no system-wide permissions or a shell that can be used (similar to other services such as NGINX).

The <install-directory>/content/ folder is owned by the ghost user. Modification to files in the <install-directory>/content/ folder requires sudo.

It is advisable to execute all tasks (image upload, theme upload etc.) using the admin UI to prevent accidental permissions changes. Changing file ownership or adding files that are not fully accessible (owned) by ghost can impact the stability of the installation.

File Permissions

There are no specific file permission requirements for ghost-cli, we are using the default Linux file permissions which are:

  • For normal users default directory permissions are 775 and default file permissions are 664.
  • For root users default directory permissions are 755 and default file permissions are 644.

Running ghost install as the non-root user will result in directories created with 775 (drwxrwxr-x) permissions and file with 664 (-rw-r--r--) permissions.

These file permissions don't need to be changed. The only change that is executed by ghost-cli is changing ownership, file permissions stay untouched.

If permissions were changed, the following two commands will revert file and directory permissions to the ones of a non-root user.

sudo find /var/www/ghost/* -type d -exec chmod 775 {} \;
sudo find /var/www/ghost/* -type f -exec chmod 664 {} \;

Codebase

yargs

The CLI makes use of a library called yargs for processing the arguments that are passed in. It's is really quite a cool library and offers lots of features. Yargs generates ghost help for us, and there are tonnes of options to allow us to improve the output.

Each command (e.g. ghost start) is an instance of the Command class. This is mostly a wrapper around yargs for taking arguments in, and around lib/ui, which contains a bunch of features such as prompt, log, etc. that allows output to be written in a consistent way.

Note

Yargs supports the concept of adding --no-{something} to a flag, which negates it. So for every flag like --enable or --setup-ssl, you can pass --no-enable and --no-setup-ssl. The CLI will be passed the original flag with a false value.

stages

All CLI command are composed of stages. Each stage self registers itself for a command. So for example ghost install contains the stage "setup", whereas ghost setup contains "ssl" and "nginx". That means you can disable "setup" using ghost install --no-stetup, as well as disabling "ssl" for the setup command with ghost setup --no-setup-ssl - very flexible.

Knowledge Base