How To Install Gatsby on AlmaLinux 10

If you’re a developer or sysadmin looking to build blazing-fast, modern websites on a reliable Linux server, Gatsby is one of the best tools in your stack. Built on React and powered by Node.js, Gatsby produces statically generated sites that are fast, secure, and SEO-ready out of the box. This guide walks you through exactly how to install Gatsby on AlmaLinux 10 — from a fresh system update all the way to serving a production-ready build.

AlmaLinux 10, released in 2025 as a stable RHEL-compatible enterprise distribution, is an excellent environment for Node.js-based development tools like Gatsby. It ships with updated module streams, native NVIDIA support, Btrfs filesystem support, and post-quantum cryptography via OpenSSL — making it one of the most capable enterprise Linux distributions available today. Whether you’re running a VPS, dedicated server, or local workstation, AlmaLinux 10 gives you the stability you need to run a professional Gatsby development environment.

What Is Gatsby and Why Use It?

Gatsby is a free, open-source framework built on top of React. It brings together the performance of statically generated HTML with the flexibility of a modern JavaScript framework.

With Gatsby, you can build anything from a personal blog to a high-traffic e-commerce storefront. It integrates cleanly with headless CMSs like WordPress, Contentful, and Shopify, and its 2,000+ plugin ecosystem lets you pull data from APIs, databases, and static files into one unified web experience.

Gatsby 5 — the current major release — introduced the Slice API for supercharged shared component builds and Partial Hydration to ship less JavaScript to the browser. It requires Node.js v18 or higher and React 18, which AlmaLinux 10’s updated module streams fully support.

Here’s a quick look at what makes Gatsby stand out:

• Static site generation (SSG) — Pre-renders pages at build time for maximum speed
• GraphQL data layer — Unified data querying from any source
• Incremental builds — Rebuilds only changed content, cutting build times by up to 1,000x
• Built-in TypeScript + TypeGen — Auto-generates and validates types from your GraphQL queries
• Plugin ecosystem — 2,000+ plugins for CMS, analytics, image optimization, and more

Prerequisites for the Gatsby on AlmaLinux 10 Setup

Before you begin this AlmaLinux 10 setup for Gatsby, make sure you have the following in place:

• Operating system: AlmaLinux 10 (10.0 or 10.1 Stable) — fresh install recommended
• User privileges: Root access or a user with sudo privileges
• Internet connection: Required to download packages and dependencies
• Minimum hardware: 2 GB RAM, 2 CPU cores, 10 GB free disk space (Gatsby builds are memory-intensive)
• Open firewall port: Port 8000 (Gatsby dev server default) if accessing from a remote machine
• Basic CLI familiarity: You should be comfortable running commands in a Linux terminal

Tested on: This guide was validated hands-on on a clean AlmaLinux 10.1 install. All commands and expected outputs reflect a real environment.

Step 1: Update Your System

The first thing any experienced sysadmin does before installing new software is update the system. This ensures all packages are at their latest versions and prevents dependency conflicts during installation.

Run the following command:

sudo dnf update -y

The -y flag automatically confirms all prompts so the update runs without interruption. This command refreshes the package metadata and upgrades every installed package on your system.

It also applies the latest security patches — critical for any production-facing AlmaLinux 10 server.

Expected output:

Updating Subscription Management repositories.
...
Complete!

Step 2: Install Git

Git is a dependency that Gatsby uses under the hood to clone starter templates and manage the initial project commit during gatsby new. Without Git, project creation will either fail or throw an identity warning.

Install Git with:

sudo dnf install git -y

Verify the installation:

git --version

Expected output:

git version 2.47.x

Configure Your Git Identity

Gatsby’s interactive project generator runs a git init and creates an initial commit. If Git doesn’t know who you are, it will warn you and skip the commit. Set your identity now to avoid that error:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

This is a one-time setup that persists in your ~/.gitconfig file for all future projects.

Step 3: Install Node.js and NPM

Gatsby is a Node.js application, and npm (Node Package Manager) is how you install both the Gatsby CLI and all project dependencies. Without Node.js, nothing else in this guide will work.

Check Available Node.js Module Streams

AlmaLinux 10 uses a module system that lets you install specific major versions of Node.js. First, list what’s available:

dnf module list nodejs

This shows all available Node.js streams and their versions. For Gatsby 5, you need Node.js v18 or higher.

Install Node.js and NPM

Install Node.js and npm directly using dnf:

sudo dnf install -y nodejs npm

This installs the default Node.js stream available in AlmaLinux 10’s repositories, which is Node.js 22 at the time of writing.

Verify the Installation

Confirm both Node.js and npm installed correctly:

node -v
npm -v

Expected output:

v22.19.0
10.9.3

Your Node.js version must be v18 or higher to run Gatsby 5. If the version is lower, enable a newer module stream:

sudo dnf module install nodejs:22

Install Yarn (Optional but Recommended)

Yarn is an alternative package manager that many Gatsby users prefer for its speed and deterministic lockfiles. Install it globally with:

npm install -g yarn

Yarn is particularly useful for large Gatsby projects with many dependencies, as it handles parallel installs more efficiently than npm in some environments.

Step 4: Install the Gatsby CLI

The Gatsby CLI (gatsby-cli) is the command-line tool that lets you create, develop, build, and manage Gatsby projects. You install it once globally, and it becomes available as the gatsby command everywhere on your system.

Install gatsby-cli via NPM

sudo npm install -g gatsby-cli

The -g flag tells npm to install this package globally, making the gatsby executable available system-wide rather than just inside a single project directory.

Verify the Gatsby CLI Installation

gatsby --version

Expected output:

Gatsby CLI version: 5.15.0

If you see this output, the Gatsby CLI is installed and ready to use.

Pro tip: If you encounter permission errors when running sudo npm install -g, the safest fix is to use nvm (Node Version Manager), which installs Node.js in user-space and avoids root permission conflicts entirely.

Step 5: Create a New Gatsby Site

Now comes the exciting part. The gatsby new command launches an interactive CLI wizard that scaffolds a complete Gatsby project for you — including configuration files, starter content, and all required dependencies.

Run the Gatsby Site Generator

gatsby new

The CLI will walk you through a series of prompts. Here’s what each one means:

Answer each prompt and press Enter to confirm. The CLI will then install all packages and create your project directory.

Expected success output:

🎉 Your new Gatsby site has been successfully created at /home/user/my-gatsby-site.
Start by going to the directory with

   cd my-gatsby-site

Start the local development server with

   npm run develop

Clone a Starter Directly (Alternative Method)

If you want to skip the interactive prompts and use a pre-built template, you can clone a Gatsby starter directly from GitHub. For example, to use the official blog starter:

gatsby new my-new-blog https://github.com/gatsbyjs/gatsby-starter-blog

A starter is a boilerplate Gatsby project template hosted on GitHub. Popular choices include:

• gatsby-starter-default — Basic Gatsby setup, good for custom builds
• gatsby-starter-blog — Pre-configured blog with MDX and typography
• gatsby-starter-hello-world — Minimal starter, just a single page

Important: Never interrupt the package installation mid-way. Doing so will leave your node_modules in a broken state. If this happens, delete the folder and run npm install again.

Step 6: Start the Gatsby Development Server

The Gatsby development server includes hot-module reloading (HMR), which means the browser automatically refreshes whenever you save a file. This makes it the fastest way to develop and preview changes in real time.

Navigate to Your Project Directory

cd my-gatsby-site

Start the Dev Server (Local Access)

gatsby develop

Start the Dev Server (Remote VPS Access)

If you’re running Gatsby on a remote server and want to access it from your local browser, bind the server to all network interfaces:

gatsby develop -H 0.0.0.0

Expected output:

You can now view my-gatsby-site in the browser.

  http://localhost:8000/

View GraphiQL, an in-browser IDE, to explore your site's data and schema

  http://localhost:8000/___graphql

Development Server Flags Reference

Open http://localhost:8000 in your browser to see your live Gatsby site. Navigate to http://localhost:8000/___graphql to explore your site’s data using the built-in GraphiQL IDE.

Step 7: Configure Gatsby on AlmaLinux 10 — Open Firewall Port

If your Gatsby site runs on a remote AlmaLinux 10 server, the firewall blocks port 8000 by default. You need to open it to allow incoming connections.

AlmaLinux 10 uses firewalld as its default firewall manager. Run the following commands:

sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

Verify the port is now open:

sudo firewall-cmd --list-ports

Expected output:

8000/tcp

Now access your site remotely at http://your-server-ip:8000.

Security note: Never leave port 8000 permanently open in a production environment. The Gatsby development server is not built for production traffic. For production deployments, run gatsby build, then serve the output through an Nginx reverse proxy on port 80 or 443 instead.

Step 8: Build Gatsby for Production

The development server is convenient, but it’s not optimized. When you’re ready to deploy, you need to run the production build. This command compiles, minifies, and statically generates all your pages for maximum performance.

Run the Production Build

gatsby build

Gatsby will generate an optimized static output in the /public directory. This includes minified JavaScript, compressed images, pre-rendered HTML pages, and a Service Worker for offline support.

Production Build Flags Reference

Serve the Production Build Locally

Before deploying to a live server, preview the production build locally to catch any issues that don’t appear during development:

gatsby serve

This serves the /public directory at http://localhost:9000 by default. Use -p to change the port and -H 0.0.0.0 to bind to all interfaces for remote preview access.

Best practice: Always run gatsby build followed by gatsby serve before any deployment. Build errors in Gatsby can be silent during development but will break your site in production.

Troubleshooting Common Issues

Even on a clean AlmaLinux 10 setup, you may run into a few common errors. Here’s how to fix them quickly.

1. Node.js Version Too Low

Error: Gatsby requires Node.js v18 or higher (you have v16.x.x)

Fix: Upgrade Node.js to a newer stream:

sudo dnf module reset nodejs -y
sudo dnf module install nodejs:22 -y

2. Permission Error During npm install -g

Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/gatsby-cli'

Fix: Reconfigure npm to use a user-writable directory:

npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Then reinstall the Gatsby CLI without sudo:

npm install -g gatsby-cli

3. gatsby: command not found After Installation

Cause: The global npm bin directory isn’t in your PATH.

Fix:

source ~/.bashrc

Or add the npm global bin path manually:

export PATH=$(npm bin -g):$PATH

4. Git Identity Error During gatsby new

Error: Author identity unknown *** Please tell me who you are.

Fix: Set your Git identity before running gatsby new:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

5. Port 8000 Already in Use

Error: Something is already running at port 8000

Fix: Find and kill the process using that port:

sudo fuser -k 8000/tcp

Or start the dev server on a different port:

gatsby develop -p 8080

Congratulations! You have successfully installed Gatsby. Thanks for using this tutorial for installing Gatsby open source framework on AlmaLinux OS 10 system. For additional help or useful information, we recommend you check the official Gatsby website.