Operating System CentOS

How to Install Hexo on AlmaLinux 9 or Rocky Linux 9 and Serve It With Nginx

Install Hexo on the RHEL 9 family with a supported Node.js stream, write your first post, build the static site and serve it with Nginx.

Hexo is a static site generator built on Node.js: you write posts in Markdown, Hexo turns them into plain HTML files, and any web server can deliver them. This guide installs Hexo on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, creates a blog, and publishes the generated site with Nginx. CentOS 7 reached end of life in June 2024, and its Node.js packages are far too old for current Hexo, so use a RHEL 9 family system instead.

Requirements

  • A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 and a regular user with sudo rights. The examples use a user named deploy.
  • Node.js. Hexo 8 needs Node.js 20.19.0 or newer; the version table in the Hexo documentation lists the minimum for each Hexo release.
  • Git, which hexo init uses to fetch the starter site.
  • A domain name pointing at the server if the blog is public. The examples use example.com.

Step 1: Install Node.js and Git

The default nodejs package in the RHEL 9 family is version 16, which is too old. Newer releases are provided as module streams in the AppStream repository. List them, enable a stream that satisfies Hexo, and install it:

sudo dnf module list nodejs
sudo dnf module enable nodejs:24
sudo dnf install nodejs git

If your system does not offer the 24 stream yet, nodejs:22 also meets the requirement. Check the result:

node --version
npm --version

Step 2: Install the Hexo command-line tool

The Hexo documentation advises against installing npm packages as root. Point npm's global directory at your home directory so that no sudo is needed, then install hexo-cli. Run these as the deploy user:

npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g hexo-cli

Confirm that the command is available:

hexo version

If you prefer not to install anything globally, Hexo can also live entirely inside the project: run npm install hexo in the site folder and call it as npx hexo <command>.

Step 3: Create the blog

hexo init clones the starter site with the default Landscape theme into a new folder and installs its dependencies:

cd ~
hexo init blog
cd blog
npm install

The folder now contains _config.yml (site settings), source/_posts (your Markdown posts), themes and scaffolds (templates for new posts). Open _config.yml and set at least the site details and the public address; url must start with http:// or https://:

title: My Blog
author: Your Name
language: en
timezone: UTC
url: https://example.com

Step 4: Write a post and preview it

Create a post. Put the title in quotation marks if it contains spaces:

hexo new "My first post"

Hexo creates source/_posts/My-first-post.md with a front-matter block at the top. Write your text in Markdown below it. To preview, start the built-in server, which watches for changes and listens on port 4000:

hexo server

The preview server binds to all addresses by default, but port 4000 is closed in firewalld, so the safest way to look at it is an SSH tunnel from your own computer:

ssh -L 4000:localhost:4000 deploy@203.0.113.10

Then open http://localhost:4000/ in your browser. Stop the server with Ctrl+C. It is a development tool; do not use it to serve the live site.

Step 5: Generate the static site

Build the HTML. hexo clean removes the previous output and cache so the build starts fresh:

hexo clean
hexo generate

The finished site is in the public folder. Nothing in it needs Node.js at run time.

Step 6: Serve the site with Nginx

Install Nginx and create a web root owned by your user, so that publishing does not require root:

sudo dnf install nginx rsync
sudo mkdir -p /var/www/blog
sudo chown deploy:deploy /var/www/blog

Copy the generated files into it. The trailing slashes matter, and --delete removes pages that no longer exist:

rsync -a --delete ~/blog/public/ /var/www/blog/

Create /etc/nginx/conf.d/blog.conf:

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    root /var/www/blog;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

SELinux is enforcing on these systems and Nginx may only read files labelled as web content. Files under /var/www receive that label by default; restorecon makes sure of it. Then test the configuration, start Nginx and open the firewall:

sudo restorecon -R /var/www/blog
sudo nginx -t
sudo systemctl enable --now nginx
sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload

Visit http://example.com/ to see the blog. For a public site, add a TLS certificate next and keep url in _config.yml in step with the scheme you serve.

Updating the site

Publishing a new post is always the same three commands, run as deploy in ~/blog:

hexo new "Another post"
hexo generate
rsync -a --delete ~/blog/public/ /var/www/blog/

Keep the ~/blog folder (without node_modules and public) in a Git repository so the sources are backed up. To update Hexo and its plugins, run npm outdated and npm update in the project folder; the Hexo project only fixes bugs in its latest version, so staying current is worthwhile. After a Node.js stream change, delete node_modules and run npm install again.

Frequently asked questions

Do I have to build the site on the server?

No. Many people run Hexo on their own computer and only upload the public folder, for example with rsync -a --delete public/ deploy@203.0.113.10:/var/www/blog/. In that case the server needs Nginx only, not Node.js. Hexo also has deployer plugins such as hexo-deployer-git, driven by hexo deploy.

Why does npm fail with an EACCES error?

That happens when npm install -g tries to write to a system directory as a normal user. Do not fix it with sudo; set a per-user prefix as in step 2, or use a version manager that installs Node.js in your home directory.

Can I use hexo server -s in production?

Static mode serves only the public folder without watching for changes, but it is still a single Node.js process with no TLS, caching or access control. A real web server such as Nginx or Apache is the better choice and costs nothing extra, since the output is plain files.

How do I change the theme?

Install or clone a theme into the themes folder (or add it as an npm package if the theme supports that), set theme: in _config.yml to its name, then run hexo clean and hexo generate. The Hexo documentation covers themes, configuration and deployment in detail.

Share story:

Continue reading other guides on How VPS.