|Docs

Deploy a Gatsby App

deploymentfrontendgatsby

Gatsby is a React-based static site generator that builds fast websites from data sources like Markdown, CMSes, and APIs. Gatsby produces a directory of static HTML, CSS, and JavaScript files that can be served by any web server.

This guide covers how to deploy a Gatsby app to Railway in three ways:

  1. From a GitHub repository.
  2. Using the CLI.
  3. Using a Dockerfile.

Create a Gatsby app

Note: If you already have a Gatsby app locally or on GitHub, skip to Deploy the Gatsby app to Railway.

Ensure Node is installed, then create a new Gatsby site:

Follow the prompts to choose your preferred options.

Run the Gatsby app locally

Open http://localhost:8000 to see your site.

Deploy the Gatsby app to Railway

Railway offers multiple ways to deploy your Gatsby app. Gatsby builds produce static files in the public/ directory, so all deployment methods use a web server (Caddy) to serve those files.

Deploy from the CLI

  1. Install the Railway CLI:
  2. Initialize a Railway Project:
    • Run the command below in your Gatsby app directory.
    • Follow the prompts to name your project.
    • After the project is created, click the provided link to view it in your browser.
  3. Deploy the Application:
    • Use the command below to deploy your app:
    • This command will scan, compress and upload your app's files to Railway. You'll see real-time deployment logs in your terminal.
    • Once the deployment completes, go to View logs to check if the service is running successfully.
  4. Set Up a Public URL:
    • Navigate to the Networking section under the Settings tab of your new service.
    • Click Generate Domain to create a public URL for your app.

Deploy from a GitHub repo

To deploy a Gatsby app to Railway directly from GitHub:

  1. Create a New Project on Railway:
    • Go to Railway to create a new project.
  2. Deploy from GitHub:
    • Select Deploy from GitHub repo and choose your repository.
      • If your Railway account isn't linked to GitHub yet, you'll be prompted to do so.
  3. Deploy the App:
    • Click Deploy to start the deployment process.
    • Once deployed, a Railway service will be created for your app, but it won't be publicly accessible by default.
  4. Verify the Deployment:
    • Once the deployment completes, go to View logs to check if the server is running successfully.
  5. Set Up a Public URL:
    • Navigate to the Networking section under the Settings tab of your new service.
    • Click Generate Domain to create a public URL for your app.

Use a Dockerfile

  1. Create a Dockerfile in your Gatsby app's root directory.

  2. Add the content below to the Dockerfile:

    The Dockerfile uses a multi-stage build: Node builds the site, then Caddy serves the public/ directory.

  3. Add a Caddyfile to the app's root directory:

    Note that the root directive points to public (Gatsby's build output directory) instead of dist.

  4. Either deploy via the CLI or from GitHub.

Railway automatically detects the Dockerfile, and uses it to build and deploy the app.

Note: Railway also supports deployment from public and private Docker images.

Client-side routes

Gatsby supports client-only routes for pages that handle routing in the browser. The try_files {path} /index.html directive in the Caddyfile ensures these routes work correctly on refresh. For more details on configuring this, see Configure SPA Routing.

Build memory

Gatsby builds can be memory-intensive for large sites with many pages or image processing. If the build fails with an out-of-memory error, increase the Node.js heap size:

Add this as a service variable in Railway.

Next steps