Gatsby на Ubuntu 24.04: пошаговая установка

MAATRIX

Gatsby собирает React-приложение в набор статических HTML, JS и CSS файлов — после сборки серверу не нужен работающий Node.js процесс, сайт отдаётся как обычная статика. Это делает его быстрым и дешёвым в хостинге, но сама установка тулчейна и сборка на VPS имеют нюансы: от версии Node.js до памяти, которая нужна webpack во время build. Разберём весь путь на Ubuntu 24.04 — от чистого сервера до сайта под SSL.

Что понадобится перед установкой

Минимальные требования для комфортной работы:

• VPS на Ubuntu 24.04 LTS, минимум 2 vCPU и 2 ГБ RAM — сборка Gatsby (особенно с большим количеством страниц или тяжёлыми GraphQL-запросами к CMS) активно использует память через webpack, и на 1 ГБ без свопа процесс может падать с ошибкой JavaScript heap out of memory;
• доступ по SSH с правами sudo;
• домен, уже направленный A-записью на IP сервера (для SSL это обязательно);
• базовое знакомство с npm — Gatsby целиком построен на экосистеме Node.js.

Если сервер совсем свежий, сразу обновите пакеты и поставьте базовые утилиты:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential

Пакет build-essential нужен, потому что часть npm-зависимостей Gatsby (например, sharp для обработки изображений) собирает нативные модули из исходников при установке.

Устанавливаем Node.js через NodeSource

Gatsby требует актуальную LTS-версию Node.js — ставить нужно не из стандартного репозитория Ubuntu (там обычно устаревшая сборка), а через официальный репозиторий NodeSource. На конец августа 2026 года актуальны Node.js 20.x и 22.x LTS; уточните текущую активную LTS-ветку на nodejs.org и подставьте нужную цифру вместо 20 в команде ниже:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Проверьте версии:

node -v
npm -v

Если предпочитаете не привязываться к системному Node.js, разумная альтернатива — nvm (Node Version Manager): он ставится в домашнюю директорию пользователя и позволяет держать несколько версий Node.js параллельно, что удобно, если на сервере крутится несколько проектов с разными требованиями:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

Оба варианта рабочие — NodeSource проще для одного статического сайта на выделенном сервере, nvm удобнее, если сервер шарится между проектами.

Устанавливаем Gatsby и создаём проект

Актуальный способ — не ставить gatsby-cli глобально (устаревающий подход), а использовать npm init gatsby или напрямую npx, который скачивает нужную версию CLI на лету и не оставляет на сервере глобальный пакет, за версией которого потом надо следить:

npx gatsby new my-site https://github.com/gatsbyjs/gatsby-starter-default

Команда задаст несколько вопросов в интерактивном режиме (CMS, стилизация, TypeScript) — для чистого старта можно смело выбирать варианты по умолчанию, стартер gatsby-starter-default даёт минимальный рабочий проект.

Если вы разворачиваете уже готовый проект (например, писали сайт локально и заливаете на сервер через git), последовательность другая:

git clone https://github.com/your-account/your-gatsby-site.git my-site
cd my-site
npm install

npm install подтянет зависимости из package.json и package-lock.json — тут и происходит основная нагрузка на CPU/RAM, особенно если в проекте есть gatsby-plugin-sharp или gatsby-plugin-image: они компилируют sharp под платформу сервера.

Собираем production-версию сайта

Переходим в директорию проекта и запускаем сборку:

cd ~/my-site
npm run build

По умолчанию это выполняет gatsby build и кладёт результат в директорию public/ — это и есть готовый статический сайт, который дальше просто нужно отдать через веб-сервер. Никакого постоянно работающего Node.js процесса для production не требуется — в этом ключевое отличие Gatsby от, например, Next.js с SSR.

Проверить сборку локально перед деплоем можно командой:

npm run serve

Она поднимает gatsby serve на порту 9000 — используйте это только для проверки, не как production-режим (это отладочный HTTP-сервер, не рассчитанный на реальную нагрузку).

Если сборка падает с нехваткой памяти на слабом VPS, самый быстрый обходной путь — временный swap-файл:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Это не ускорит сборку, но не даст процессу упасть на пике потребления памяти — актуально для планов с 1–2 ГБ RAM.

Настраиваем Nginx для отдачи статики

Так как public/ — это готовый набор файлов, Nginx нужен просто как раздатчик статики, без проксирования в Node.js. Установите его, если ещё не стоит:

sudo apt install -y nginx

Скопируйте результат сборки в директорию сайта:

sudo mkdir -p /var/www/my-site
sudo cp -r ~/my-site/public/* /var/www/my-site/
sudo chown -R www-data:www-data /var/www/my-site

Конфиг виртуального хоста /etc/nginx/sites-available/my-site:

server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/my-site;
    index index.html;

    location / {
        try_files $uri $uri/ /404.html;
    }

    location /static/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
}

Обратите внимание на try_files $uri $uri/ /404.html — Gatsby генерирует отдельную страницу 404.html, и без этой директивы несуществующие маршруты будут отдавать голый Nginx 404 вместо стилизованной страницы сайта. Директория /static/ хранит хэшированные по содержимому JS/CSS-бандлы — их безопасно кешировать надолго, имя файла меняется при каждом изменении содержимого.

Активируйте конфиг и проверьте синтаксис:

sudo ln -s /etc/nginx/sites-available/my-site /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Если после правок конфига Nginx не подхватывает изменения — это отдельная и частая проблема, разобранная в статье про Nginx, который не видит изменения конфига. Общий подход к раздаче статических сайтов на VPS, включая базовые настройки безопасности, — в статье про установку статического сайта на VPS.

Подключаем SSL через Let's Encrypt

Для бесплатного автопродлеваемого сертификата используем Certbot с плагином Nginx:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Certbot сам добавит блок с ssl_certificate, настроит редирект с 80 на 443 порт и пропишет параметры TLS. После выпуска проверьте автопродление (по умолчанию системный таймер уже настроен пакетом, но не лишним будет убедиться руками):

sudo certbot renew --dry-run

Подробный разбор установки и частых проблем с Let's Encrypt — в статье про установку Let's Encrypt SSL на VPS. Если хочется вообще не думать про Certbot и обновление сертификатов вручную, альтернативный путь — Caddy, у которого автоматический HTTPS встроен по умолчанию; сравнение подходов есть в статье про установку Caddy с авто-SSL на Ubuntu 24.04.

Для деплоя новых версий сайта после правок достаточно повторить npm run build локально или на сервере и заново скопировать public/ в /var/www/my-site — простой bash-скрипт с rsync вместо cp избавит от риска оставить старые файлы:

rsync -av --delete ~/my-site/public/ /var/www/my-site/

Флаг --delete синхронизирует директорию полностью, удаляя файлы, которых больше нет в новой сборке (актуально, если вы переименовывали или удаляли страницы).

Частые вопросы