Edit: In Nov 2022 I discovered that Ghost decided to make its platform more friendly to other OS and platforms such as Debian, so I went back to the platform (after using Wordpress for a while). This post may be somewhat out of date then. You may want to read more about it here.
The update looked promising. New editor with improved functionality, automatic updates, and of course the fact that it was the first non-beta release.
However, when I visited the Ghost install website, I was shocked to find that ghost 1.0 required not only a concrete web server (Nginx), but also a concrete operating system too (Ubuntu):
While I have worked with Ubuntu and Nginx in the past, and I love both, the server where I have my blog hosted happens to run on Debian + Apache2.
However, being brother Linux distros, I thought that probably those were just mere recommendations. After all, a blog running on a web server should be system agnostic, shouldn’t it? If wordpress can run on a Windows machine, the next generation of open source blogs can certainly run on a Debian box, right?
The “Not So Open” Blogging Platform
Being a major release update, you can’t update to Ghost 1.X directly. You need to create a new install and import the previously exported data from your old one. As it turns out, the installation via the ghost-cli expects you to have that exact Ubuntu+Nginx environment. Otherwise, it fails.
There are two types of installations available, the “production install” and the “local install”. Supposedly, if you have a different environment, you should opt for the latter. However, the Ghost team makes it clear that a local install is not suitable for production.
Thus, the only chance for us, non-Ubuntu users is going for the production install and trying to fix things. Let’s see how to do this for Debian Jessie (8.9) and Apache 2.4.
Installing Ghost Via The CLI Interface.
If you are updating your Ghost installation from Ghost 0.11.X, I suppose you already have node, a ghost user and the ghost-cli package installed. If not, follow the first steps of the installation guide.
Preparing the MySQL Database
After that, you need to install and configure MySQL. Ghost 0.11.X used SQLite3 by default, so you probably haven’t setup MySQL yet. First, install the required packages as root.
# aptitude install mysql-server
Then, initialize and secure your installation:
Finally, login into MySQL and create the database, user and proper permissions for the ghost user:
# mysql -u root -p (insert password here) mysql> create database yourblogname; mysql> CREATE USER 'yourbloguser'@'localhost' IDENTIFIED BY 'yourpassword'; mysql> grant create,delete,insert,select,update,alter ON yourblogname.* TO 'yourbloguser'@'localhost'; mysql> flush privileges;
Launching the Ghost Install Process
Next, we can create a directory and call ghost-cli to start the installation process:
# mkdir /var/www/html/yourghostblog # chown ghost:ghost /var/www/html/yourghostblog # cd /var/www/html/yourghostblog # ghost install
You will be greeted with a beautiful “you are about to destroy the world” warning message:
Type “Yes” anyway. We Debian users love danger, don’t we?
Initial Configuration Questions
Then, you will be asked some questions about your setup.
? Enter your blog URL: http://yourblogname.com ? Enter your MySQL hostname: localhost ? Enter your MySQL username: yourbloguser ? Enter your MySQL password (skip to keep current password): [hidden] ? Enter your Ghost database name: yourblogname
Next, it will ask you specific questions about the installation. Here is where the limitations of the new Ghost release come to the fore. You should answer this:
? Do you wish to setup Nginx? No i Setting up Nginx [skipped] Task ssl depends on the 'nginx' stage, which was skipped. i Setting up SSL [skipped]
Great, so no Nginx means no SSL configuration, of course. Next, it asks you about MySQL.
? Do you wish to setup "ghost" MySQL user? Yes MySQL user is not root, skipping additional user setup i Setting up "ghost" mysql user [skipped]
Errr… well, thanks for that. Next, Systemd.
Do you wish to setup Systemd? Yes ✓ Creating Systemd service file at /var/www/html/yourblogname/system/files/ghost_yourblogname-com.service Running sudo command: ln -sf /var/www/html/yourblogname/system/files/ghost_yourblogname-com.service /lib/systemd/system/ghost_yourblogname-com.service ✓ Setting up Systemd
As you can see, the installation incorrectly creates a symbolic link on /lib/systemd/system/, when it should go into /etc/systemd/system. This means that your ghost blog won’t launch on a system reboot.
Finishing the Installation
Finally, the installation process asks you to start ghost, but don’t hold your breath, it will throw an error:
? Do you want to start Ghost? Yes ✓ Validating config ✓ Starting ghost x Starting ghost A ProcessError occurred Error occurring running command '/bin/sh -c sudo systemctl enable ghost_yourblogname-com --quiet Exit code: 1
Obviously, the file cannot be found because it’s not in the right place.
However, you should be able to start the Ghost installation manually by running a
ghost run on the blog directory. Try it now and navigate to that URL in your browser. You should be able to reach the blog, yay!
Making Sure Ghost Keeps On Running
In order to keep Ghost alive in our Debian boxes, we need to copy the file, or create a new one in /etc/systemd/system. I created one called
/etc/systemd/system/ghost.service, with this content.
[Unit] Description=Ghost systemd service for blog: yourblogname Documentation=https://docs.ghost.org [Service] Type=simple WorkingDirectory=/var/www/html/yourblogname User=1001 Environment="NODE_ENV=production" ExecStart=/usr/bin/nodejs /usr/bin/ghost run Restart=always [Install] WantedBy=multi-user.target
The installation guide instructs you to run
ghost start and
ghost stop to start and stop the ghost instance respectively. However, those commands won’t run, they will throw an error.
/usr/lib/node_modules/ghost-cli/node_modules/yargs/yargs.js:1079 else throw err ^ Error: unknown at module.exports.sync (/usr/lib/node_modules/ghost-cli/node_modules/execa/index.js:298:26) at handleShell (/usr/lib/node_modules/ghost-cli/node_modules/execa/index.js:100:9)
Apparently, the only command that runs is
/usr/bin/ghost run, that will create a new instance of Ghost directly.
The best way to test that it’s working is rebooting your server. Upon start, you should be able to see the node instance on port 2368, and navigate to your blog in a browser.
Proxy Redirection For Apache
If you were running Ghost previously, I assume you already had a proxy in place to redirect apache requests to your Ghost port. If not, you just need to setup an entry in
/etc/apache2/sites-available/ with this content:
<VirtualHost *:80> # Domain name ServerName yourblogname.com ServerAlias www.yourblogname.com #HTTP proxy/gateway server ProxyRequests off ProxyPass / http://127.0.0.1:2368/ ProxyPassReverse / http:/127.0.0.1:2368/ </VirtualHost>
Additionally, you may want to add an HTTPS entry to port 443 with your certificates.
No, You Won’t Be Able To Update Ghost
Unfortunately, the fact that ghost commands are broken means that you cannot run the command that’s supposed to update your Ghost installation:
This command will throw the exact same error that
ghost start or
ghost stop. This is certainly a big deal breaker, because you won’t be able to update your ghost installation anymore.
Unfortunately, the Ghost team has decided that they won’t be offering support to anyone without Ubuntu+Nginx. I really hope they will change their minds, because otherwise I really need to consider going back to WordPress again. Yes, it’s slow and clumsy, but I can update it by just clicking a button.
Update Your Theme And Import Your Content Back
Once you have the installation ready, and you are certain that it will survive a system reboot, you need to update your theme. Fortunately, the guys at Ghost put together a page where you can check if your theme is ready for the new version. If the author of your theme hasn’t already updated it to Ghost 1.0, there’s also a page with detailed instructions on how to update the theme yourself.
Luckily for me, the author of the Boo theme updated it for the new release. I don’t know if I would like to go through the process of manually updating it myself.
Finally, you should update your content back. This is as simple as coping the contents of the
/content/images folder from your old installation, and using the
Import Content feature of the “Labs” section of the admin interface.
The Ghost team decided to limit the first big release of Ghost to just Ubuntu and Nginx users. That is a huge step backward and an unfortunate decision in my humble opinion.
Having installed and worked with Ghost 0.11.X happily in my Debian+Apache2 box in the past, I cannot understand why they decided to implement such an opinionated installation mechanism. Nowadays, it’s certainly not that hard to implement a universal installer for most Linux distributions.
With this decision, they are neglecting a large number of users, including me.
As a result, I wrote this post to share with you how to update to Ghost 1.0 in Debian and Apache. I hope it can be helpful even for other Linux distributions like Mint or CentOS.
However, the process is inherently broken, as you won’t be able to properly update your Ghost installation ever. Thus, I recomend you to wait and share your discomfort with the guys at Ghost, hoping that they will change their minds and implement a more universal installer for us, Linux and MacOS users.
Nevertheless, if you have found a way of making the whole installation process work correctly, including
ghost stop and
ghost update, please let me know.