Tasks before going live (error messages, documentation, improvements)

[cobbspur]

Documentation at docs.ghost.org (start with this on the 7th of July - not before please)

We are going to have a little call about the CLI documentation on the 7th of July. That's why the sub tasks here are unassigned.

@cobbspur

• differ between local and production installation ( ghost install --development ghost install local etc.)
• document database options e.g. mysql vs. sqlite (mysql user creation sudo permissions) - how to install Ghost with sqlite? e.g. ghost install --url https://kate-ghost-test.acburdine.me --db sqlite3 --dbpath ./content/data/ghost.db
• CLI prompts nginx installation/template creation -> document this and document that we are using letsencrypt. letsencrypt is accepted by browsers and is free ssl cert generation
• document install behind proxy failed.  #211
• write a little section about where the nginx config file lives and how to modify this file
• write a little section about where the ssl config file lives and how to modify this file

@AileenCGN

• document ghost doctor
• skip nginx/ssl installation via command line e.g. --nosetup, --no-setup-ssl, --no-start - document special flags (see also ghost help)
• more documentation about ghost config
• document verbose flag
• document ghost setup [service] e.g. ghost setup ssl (install extensions manually/separately/afterwards)

@ErisDS

• document how to use the CLI in a provision script - see conversation https://ghost.slack.com/archives/C04CUS2R3/p1498770776174257

@kirrg001

• environment requirements (minimum memory required), ubuntu version >= 16.X?
• never install ghost inside /root - add a 100% recommended way e.g. install node globally /usr/local/node and /usr/local/nvm and create a folder in /var/www/
• ghost-cli needs root access, if you have a custom ubuntu user, it needs to be in the sudoers group
• document the default permission requirements for the default CLI installation (=== sudo access)
• document that systemd setup is REQUIRED (otherwise use --process local)
• if ghost start is somehow not working, you can run ghost run which might help you to clarify to issue you are running in (document ghost run as best as we can)
• document that if you skip systemd, you will get "Message: Systemd process manager has not been set up. Run ghost setup linux-user systemd and try again." - that means you have to set it up. ONLY if systemd can't be used, we auto fallback (user can use --process local to force local process manager)
• if reinstalling Ghost on a instance, it's recommended to delete the existing nginx config files and the acme ssl script?
• troubleshooting: if you hit a problem/error with ssl, you have to remove ~/.acme/domain and your nginx config file rm -rf system/files/domain.config and run ghost setup nginx ssl again
• add to troubleshooting: Ghost pretends to be running but isn't and can't be stopped #292
• add to troubleshootting:Failed to get unit file state for ghost_<url>.service #293
• add to troubleshooting: if you get the error "Unit nginx.service is masked" then systemd somehow masked nginx to prevent it from starting. Then you have to execute "sudo systemctl unmask nginx.service"
• add to troubleshooting: if you install nginx apt-get install nginx and then remove it with apt-get remove nginx, the CLI can't detect that nginx is not installed anymore -> you will get a connection refused error in the browser
• what about the nginx/ssl documentation pages????

Cases to test on a droplet (start with this on the 6th of July - not before please)

The goal of this section is to test the CLI as much as possible. If you can think of cases, please test. Please test on the 6th of July.

If you find a bug while testing, please raise an issue.
If you find any documentation ideas, which are missing above, please add a sub task

@kirrg001

• test: mysql is not installed
• test: access denied to mysql (wrong credentials)
• test without nginx, without ssl, without systemd (skip everything)
• test without nginx, without ssl, with systemd -> blog starts
• general test: ghost ls, ghost run, ghost stop etc.
• test: install ghost without nginx, install nginx afterwards, call ghost setup nginx on the folder
• adduser something, with sudoers group
• What if a self hoster creates a DO droplet and out of habits, he installs nginx and sets it up + configures it. Then he installs the CLI, runs ghost install and if the nginx prompt occurs, he decides for "yes i want that the CLI takes this over"? Which is a double configuration/installation of nginx. Or, he only installs nginx manually without configuring it and the he runs the CLI and prompts with "yes orkay!" --> based on the result, please add messages to the CLI like If you have already configured nginx for your ghost instance you can skip this step. If the user creates a nginx config file by it's own and let the CLI create another one, the CLI can't detect this. Only if the file name is the same (test this as well) see Detect manual nginx setup #310
• test installing the CLI without nginx/ssl - ensure you are getting prompt and you answer with "no" for both services
• test installing the CLI with nginx, without ssl
• test installing the CLI with nginx, with ssl
• test installing the CLI with sqlite (ghost install --url https://kate-ghost-test.acburdine.me --db sqlite3 --dbpath ./content/data/ghost.db)
• test the CLI with all kinds of special flags e.g. nosetup (check the code base for more helpful flags) or use ghost help install or ghost help setup - all special flags are listed
• install Ghost on a droplet with the CLI with systemd (the default installation process), reboot your droplet and check if the ghost instance was rebooted automatically, if not raise an issue and link to https://www.digitalocean.com/community/tutorials/how-to-configure-a-linux-service-to-start-automatically-after-a-crash-or-reboot-part-2-reference#systemd-configuration-files-unit-files
• [ ] use an expired letsencrypt cert and start Ghost - double check in the browser - then regenerate and see if you are running into any problems can't simulate. can't expire a cert explicitly.
• [ ] test the letsencrypt cron job (manually decrease the renew time to 5minutes or something)!!! can't simulate. can't renew script within 5minutes or hours.
• skip Ghost-CLI would like to generate a ssl parameters file

General Improvements

@AileenCGN

• if your Ghost config is invalid (because you have modified manually) it shows Config file is not valid JSON - could we show what is not valid? And also show a hint where to find the config file.
• add default max upload size in nginx, Nginx config client_max_body_size #231 - add this property to the nginx template

@cobbspur

• show after Ghost installation how to setup mail via the CLI and show a link to the general documentation of mail configuration on docs.ghost.org

@ErisDS

• be able to configure mail via ghost config - make it very simple, just copy existing config logic and rename the properties to store mail configuration
• ensure systemd enable gets called, so that ghost restarts after server shutdown

@acburdine

• run ghost update if there is no newer version available, you will get "No valid versions found.", which is 100% confusing.
• lets encrypt (ssl certs) needs a cron job as certs expire every 90 and need renewal every 60 - so as soon as the ssl cert is generated
• better error handling related to the ssl lib we are using (better catch, better error messages) e.g. people experienced ERR_SPDY_PROTOCOL_ERROR, but they had no clue what this means - ask @acburdine if this is interfering with SSL handling #190
• people think ghost --version prints the version of the ghost blog - try to improve by printing Ghost-CLI version is: ....

Real bugs

@acburdine

• "A ProcessError occured" on keygetification for letsencrypt - we somehow broke something - related to ssl cert generation. (double check with @acburdine) + ghost service nginx-ssl <email> errors (but ghost setup works)
• print more context of the error on ghost start -> e.g. show where debug file of the CLI lives, show where to find the ghost log file and show more details of the error itself e.g. nginx/ssl (test before again)
• server.host vs. server.ip (double check with @acburdine) - this bug was reported in slack and somebody wanted to create a PR, but i didn't see the PR.

Error messages in the CLI

@AileenCGN

• print troubleshooting CLI docs link if any error occurs - CLI is not using Ignition errors, see Use Ignition errors #239, so we are hacking it inside
• optimise the error message from Working directory is not a valid Ghost installation #236 - so if somebody calls ghost update in a LTS folder we can detect this by checking if config.js exists or something else, which is specific to LTS

[acburdine]

They may not all have issues but they're all on my radar.

[kirrg001]

I've cleaned this issue up, reordered and structured the list.

[ErisDS]

Just for reference, I'm waiting on the following tasks:

• be able to configure mail via ghost config - make it very simple, just copy existing config logic and rename the properties to store mail configuration
• ability to do --no-ssl (which doesn't exist but is a documentation task here) and the ability to do ghost service nginx-ssl <email> which performs the ssl task, but currently errors.
• systemd enable service gets called
• lets encrypt (ssl certs) needs a cron job as certs expire every 90 and need renewal every 60 - so as soon as the ssl cert is generated
• fix for ssl params issue Nginx ssl params config is wrong #230

(priority is in that order)

[cobbspur]

Note for

create an overview on top of the CLI documentation, which steps the CLI is doing while installing Ghost on production (e.g. by default the CLI sets up nginx, ssl, mysql for you. Therefor....)

I have added this in the Ghost install section for now and it is probably going to need editing after the prompts in CLI are reviewed

[ErisDS]

I wasn't sure which part of the linked conversation was relevant- that was to do with docker which I know nothing about! Everything I could think of that is relevant to running Ghost programatically via configuration management or a script, is documented here: https://docs.ghost.org/v1.0.0/docs/using-ghost-cli-programatically - it has some TODOs for adding links to other bits of docs when it is ready.

[ErisDS]

I think there are a few features that aren't well known enough to be documented yet:

• ghost setup ssl --sslstaging

Uses letsencrypt's staging server - wish I knew that one existed before! Haha

• ghost start --enable

Passing enable with enable the process manager (systemd) so that the process restarts on boot. I believe this is the default option when ghost start is called as part of an install/setup

cc @acburdine can you confirm that?

• ghost stop --disable

Similarly, passing disable to ghost stop turns this off.

• --quiet and --verbose

• ghost log --follow

• ghost setup --pname

[kirrg001]

@ErisDS I've updated the docs 👍

[kirrg001]

All of the tasks here are marked as finished. I am going to close this issue now.
Please raise a new issue if you discover a bug 👍