Skip to content

Update MySQL installation instructions for Ubuntu #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
steves2j wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update MySQL installation instructions for Ubuntu #33

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions install/ubuntu.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,16 @@ Next, you’ll need to install MySQL to be used as the production database.
sudo apt-get install mysql-server
```

On newer versions of Ubuntu, the root user created when you install MySQL will by default be configured to use socket-based authentication, meaning that only the root Unix user will be able to authenticate. Ghost does not support this kind of authentication, so you must change the root MySQL user to have a password. Run these commands to make the root user have a password:
On newer versions of Ubuntu, the root user created when you install MySQL will by default be configured to use socket-based authentication, meaning that only the root Unix user will be able to authenticate. Ghost does not support this kind of authentication, so you must change the root MySQL user to have a password.
Also on newer mysql servers 'mysql_native_password' plugin are deprecated you will need to add the following to the mysql config to re-enable this plugin.
```bash
#add to /etc/mysql/*/mysql.cnf
sudo vi /etc/mysql/mysql.conf.d/mysql.cnf
[mysqld]
mysql_native_password=ON
```

Comment on lines +102 to +110
Copy link

@coderabbitai coderabbitai bot Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

# First, let's read the file to see the actual content at lines 102-110
cd /tmp && find . -name "ubuntu.mdx" -type f 2>/dev/null | head -5

Repository: TryGhost/Docs

Length of output: 39

🏁 Script executed:

# List files to understand the structure
git ls-files | grep -E "ubuntu\.mdx|install.*\.mdx" | head -10

Repository: TryGhost/Docs

Length of output: 230

🏁 Script executed:

# Read the specific lines in the file
git ls-files | grep "ubuntu.mdx" | head -1 | xargs -I {} sed -n '95,115p' {}

Repository: TryGhost/Docs

Length of output: 882

🌐 Web query:

MySQL mysql_native_password configuration syntax and Ubuntu 22.04 24.04 compatibility - is mysql_native_password=ON correct for MySQL 8

💡 Result:

Short answer: It depends on the MySQL release.

  • MySQL 8.4 (upstream): the server-side plugin is built-in but disabled by default; to enable it you may start the server with --mysql-native-password=ON or add mysql_native_password=ON to the [mysqld] section of my.cnf. [1][2]

  • MySQL 8.0 (the version shipped on Ubuntu 22.04 / 24.04 packages): mysql_native_password is available (and was the legacy default prior to 8.0.4) but is not enabled/selected by default on modern 8.0.x installs (caching_sha2_password is the default authentication plugin). For compatibility you typically either set default_authentication_plugin=mysql_native_password in my.cnf or create/alter accounts with IDENTIFIED WITH 'mysql_native_password' (or ALTER USER ... IDENTIFIED BY ...). Using mysql_native_password=ON in [mysqld] is a documented 8.4 option, but on Ubuntu’s packaged MySQL 8.0.x you should instead use default_authentication_plugin or per-user IDENTIFIED WITH. [1][3][4]

Sources:
[1] MySQL Reference Manual — Native pluggable authentication; enabling with --mysql-native-password=ON / mysql_native_password=ON.
[2] Oracle MySQL docs (same section).
[3] MySQL 8.0 notes: caching_sha2_password is the preferred default; mysql_native_password is deprecated.
[4] Ubuntu package pages / docs showing Ubuntu 22.04 and 24.04 ship MySQL 8.0.x packages.

If you tell me the exact MySQL package/version you have on your Ubuntu host (output of mysql --version or apt policy mysql-server), I’ll give the precise my.cnf setting and an example.

🌐 Web query:

Ghost CMS MySQL authentication requirements mysql_native_password deprecated

💡 Result:

Short answer: Ghost (which uses Node MySQL client libraries) historically requires a MySQL account that the Node connector can authenticate with; many Ghost installs hit the MySQL 8+ problem where the server’s default caching_sha2_password auth is not supported by older Node/MySQL clients, so people either (A) create/alter the Ghost DB user to use mysql_native_password (or enable that plugin on the server) or (B) ensure the Node MySQL connector in use supports caching_sha2_password. See sources below for details and commands.

Key points and actions

  • MySQL: mysql_native_password was deprecated in MySQL 8.x (deprecated in 8.0.34, disabled by default in 8.4, removed in MySQL 9.x). You can still enable/use it on some 8.x installs but it may be unavailable in future MySQL releases. (dev.mysql.com)
  • Ghost / Node clients: older Node MySQL clients do not support caching_sha2_password; many Ghost forum threads and issues show the common fix is to ALTER the Ghost DB user to mysql_native_password (or use an updated connector that supports SHA-2). Example ALTER command: ALTER USER 'ghost'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword'; FLUSH PRIVILEGES; (forum.ghost.org)
  • If your MySQL server no longer provides mysql_native_password (e.g., MySQL 9+ or 8.4 with the plugin disabled), options are: enable mysql_native_password at server start if the MySQL build still supports it (mysqld --mysql-native-password=ON), upgrade/replace the Node MySQL connector to one supporting caching_sha2_password, or recreate the Ghost DB user with caching_sha2_password if your connector supports it. (dev.mysql.com)

References

  • MySQL docs: native pluggable authentication / deprecation details. (dev.mysql.com)
  • MySQL docs: caching_sha2_password (default since 8.0). (dev.mysql.com)
  • Ghost forum / community reports on ER_NOT_SUPPORTED_AUTH_MODE and recommended ALTER USER workaround. (forum.ghost.org)

If you want, tell me your MySQL version and Ghost/node versions and I’ll give the exact ALTER USER command or connector upgrade steps tailored to your setup.

Citations:

🏁 Script executed:

# Verify the correct MySQL config filename on Ubuntu systems
cat /etc/mysql/mysql.conf.d/* 2>/dev/null | head -20

Repository: TryGhost/Docs

Length of output: 39

🏁 Script executed:

# Check what files actually exist in that directory
find /etc/mysql -name "*.cnf" 2>/dev/null | head -20

Repository: TryGhost/Docs

Length of output: 39

🌐 Web query:

Ubuntu MySQL configuration file location /etc/mysql/mysql.conf.d/ which file mysqld.cnf vs mysql.cnf correct

💡 Result:

Short answer: use mysqld.cnf for server ([mysqld]) settings; mysql.cnf (or my.cnf) holds client or global includes. Ubuntu’s /etc/mysql/my.cnf includes both /etc/mysql/conf.d/ and /etc/mysql/mysql.conf.d/, and the server reads [mysqld] stanzas from /etc/mysql/mysql.conf.d/mysqld.cnf. [1][2][3]

If you want to confirm on your system run:
mysql --help | grep -A1 "Default options"
or inspect /etc/mysql/my.cnf to see the included directories. [3]

Critical: MySQL configuration syntax incompatible with Ubuntu 22.04/24.04 (MySQL 8.0.x) — update to use correct settings and fix filename.

The configuration guidance is technically incorrect for the target Ubuntu versions:

  1. Wrong syntax for MySQL 8.0.x: Line 108 shows mysql_native_password=ON, but Ubuntu 22.04/24.04 ship MySQL 8.0.x, which requires default_authentication_plugin=mysql_native_password instead. The mysql_native_password=ON syntax only works on MySQL 8.4+. Users following this will encounter authentication errors.

  2. Wrong filename: Line 106 uses /etc/mysql/mysql.conf.d/mysql.cnf, but MySQL reads [mysqld] settings from /etc/mysql/mysql.conf.d/mysqld.cnf.

  3. Grammar error: "plugin are deprecated" should be "plugin is deprecated" (line 103).

  4. Path/formatting confusion: The comment on line 105 (#add to /etc/mysql/*/mysql.cnf) and the command path on line 106 don't align, adding further confusion.

Update the configuration block to:

  • Use /etc/mysql/mysql.conf.d/mysqld.cnf (correct filename)
  • Use default_authentication_plugin=mysql_native_password for MySQL 8.0.x compatibility
  • Fix grammar and clarify instructions
🤖 Prompt for AI Agents 
In @install/ubuntu.mdx around lines 102 - 110, Update the documentation block
that currently references `mysql_native_password=ON`,
`/etc/mysql/mysql.conf.d/mysql.cnf`, and the phrase "plugin are deprecated":
replace the filename with `mysqld.cnf` (the correct MySQL config file name),
replace the deprecated setting `mysql_native_password=ON` with the MySQL
8.0-compatible setting `default_authentication_plugin=mysql_native_password`,
correct the grammar to "plugin is deprecated", and clarify the path/command so
it consistently instructs users to edit `/etc/mysql/mysql.conf.d/mysqld.cnf` to
add the `[mysqld]` section with the new setting.

Run these commands to make the root user have a password:

```bash
# Enter mysql
Expand Down Expand Up @@ -242,4 +251,4 @@ For troubleshooting and errors, use the site search and [FAQ section](/faq/) to

## What’s next?

You’re all set\! Now you can start customising your site. Check out our range of [tutorials](https://ghost.org/tutorials/) or the Ghost [API documentation](/content-api/) depending on which page of this choose-your-own-adventure experience you’d like to subject yourself to next.
You’re all set\! Now you can start customising your site. Check out our range of [tutorials](https://ghost.org/tutorials/) or the Ghost [API documentation](/content-api/) depending on which page of this choose-your-own-adventure experience you’d like to subject yourself to next.