Skip to main content

Deploy with Fly.io

Time to complete: 15-30 minutes.

Fly.io is a platform that allows you to deploy your app to a global network of servers with a single command. This makes it easy to scale your app and ensure that it is always available.

The following will be a tailored guide on how to deploy your Ralph Storefront with Fly.io. To see the full documentation on how to deploy with Fly.io, visit their official documentation.

Pre-requisites

Steps

1. Install flyctl on your machine

First things first you will need to install the Fly CLI. This is done differently depending on your operating system. Follow the guide for your system here.

2. Create an account on Fly.io

To deploy your app with Fly.io you will need to create an account. To do that you can run the following command in your terminal:

fly auth signup

If you already have an account you can login with:

fly auth login

3. Prepare your Dockerfile

To deploy your app with Fly.io you will need have a Dockerfile in the root of your project. This file will contain the instructions on how to build your app. Here is an example of a Dockerfile for a Ralph Storefront:

Dockerfile
# syntax = docker/dockerfile:1

# Adjust NODE_VERSION as desired
ARG NODE_VERSION=16.20.0
FROM node:${NODE_VERSION}-slim as base

LABEL fly_launch_runtime="Nuxt"

# Nuxt app lives here
WORKDIR /app

# Arguments
ARG API_KEY
ARG API_ENDPOINT
ARG IMAGE_SERVER
ARG AUTH_ENDPOINT
ARG SIGN_ENDPOINT
ARG BASE_URL
ARG FALLBACK_CHANNEL_ID
ARG FALLBACK_MARKET_ALIAS
ARG DOMAINS
ARG DEFAULT_LOCALE
ARG RALPH_ENV

# Set environment variables
ENV NODE_ENV="production"
ENV API_KEY=${API_KEY}
ENV API_ENDPOINT=${API_ENDPOINT}
ENV IMAGE_SERVER=${IMAGE_SERVER}
ENV AUTH_ENDPOINT=${AUTH_ENDPOINT}
ENV SIGN_ENDPOINT=${SIGN_ENDPOINT}
ENV BASE_URL=${BASE_URL}
ENV FALLBACK_CHANNEL_ID=${FALLBACK_CHANNEL_ID}
ENV FALLBACK_MARKET_ALIAS=${FALLBACK_MARKET_ALIAS}
ENV DOMAINS=${DOMAINS}
ENV DEFAULT_LOCALE=${DEFAULT_LOCALE}
ENV RALPH_ENV=${RALPH_ENV}

# Throw-away build stage to reduce size of final image
FROM base as build

# Install packages needed to build node modules
RUN apt-get update -qq && \
apt-get install --no-install-recommends -y build-essential node-gyp pkg-config python

# Install node modules
COPY --link .npmrc package-lock.json package.json ./
RUN npm ci --include=dev

# Copy application code
COPY --link . .

RUN npm install -g node-prune

# Build application
RUN npm run build \
&& node-prune \
&& mkdir output \
&& cp -r package.json nuxt.config.js node_modules .nuxt static scripts config output

# Remove development dependencies
RUN npm prune --omit=dev

# Final stage for app image
FROM base

# Copy built application
COPY --from=build ./app/output ./

# Start the server by default, this can be overwritten at runtime
EXPOSE 3000
ENV HOST=0
ENV NUXT_HOST=0.0.0.0
CMD ["npm", "run", "start"]

4. Prepare your fly.toml

You will also need a fly.toml file in the root of your project. This file will contain the configuration for your app. Here is an example of a fly.toml file for a Ralph Storefront. Make sure to replace {name-of-your-storefront} with your own app name and *** with your own values for your env variables:

fly.toml
app = '{name-of-your-storefront}'
primary_region = 'lhr'

[build.args]
API_ENDPOINT='***'
API_KEY='***'
AUTH_ENDPOINT='***'
BASE_URL='https://{name-of-your-storefront}.fly.dev'
DEFAULT_LOCALE='***'
FALLBACK_CHANNEL_ID='***'
FALLBACK_MARKET_ALIAS='***'
IMAGE_SERVER='***'
RALPH_ENV='***'
SIGN_ENDPOINT='***'

[http_service]
internal_port = 3000
force_https = true
auto_stop_machines = true
auto_start_machines = true
min_machines_running = 0
processes = ['app']

[[vm]]
memory = '1gb'
cpu_kind = 'shared'
cpus = 1

You can read the full reference for how you can set up your fly.toml file here.

5. Launch your app

Now that you have your Dockerfile and fly.toml file ready you can launch your app. To do that you can run the following command in your terminal:

fly launch

When it's done you will get a URL to your app which you can visit to see your app live.

6. Deploy changes

When you have made changes to your app and want to deploy them you can run the following command in your terminal:

fly deploy

Automatic deployments with GitHub Actions

If you want to automate your deployments you can use GitHub Actions. To do so follow these steps:

1. Get a fly token

To deploy your app with GitHub Actions you will need to get a Fly API token. You can get one by running the following command in your terminal:

fly auth token

Copy your auth token and save for next step.

2. Add your Fly API token to GitHub Secrets

Go to your GitHub repository and navigate to Settings -> Secrets. Click on New repository secret and add a new secret with the name FLY_API_TOKEN and the value of your Fly API token.

3. Create a GitHub Actions workflow

Here is an example of a GitHub Actions workflow that will deploy your app to Fly.io on every push to the master branch:

.github/workflows/fly.yml
name: Deploy to Fly.io
on:
push:
branches:
- master
jobs:
fly:
name: Deploy app
runs-on: ubuntu-latest
concurrency: deploy-group
steps:
- uses: actions/checkout@v4
- uses: superfly/flyctl-actions/setup-flyctl@master
- run: flyctl deploy --remote-only
env:
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Deploy a PR preview with GitHub Actions

Another cool feature you can add to your GitHub Actions workflow is to deploy a preview of your app on every pull request. This is an example of how you can do that:

.github/workflows/fly-review.yml
name: PR deploy to Fly.io
on:
pull_request:
types: [opened, reopened, synchronize, closed]

env:
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
FLY_REGION: lhr
FLY_ORG: personal

jobs:
fly:
runs-on: ubuntu-latest
outputs:
url: ${{ steps.deploy.outputs.url }}
concurrency:
group: pr-${{ github.event.number }}
environment:
name: review
url: ${{ steps.deploy.outputs.url }}
steps:
# Add a comment to the PR to indicate that the preview is being deployed.
- name: Add loading comment to PR
id: loading_comment_to_pr
uses: marocchino/sticky-pull-request-comment@v1
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
number: ${{ github.event.issue.number }}
header: fly
message: |
Deploying preview...
# Checkout the code.
- name: Get code
uses: actions/checkout@v4
# Deploy the app to Fly.io.
- name: Deploy PR app to Fly.io
id: deploy
uses: superfly/fly-pr-review-[email protected]
# Add a comment to the PR with the preview URL.
- name: Add comment to PR
id: comment_to_pr
uses: marocchino/sticky-pull-request-comment@v1
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
number: ${{ github.event.issue.number }}
header: fly
message: |
Preview URL: ${{ steps.deploy.outputs.url }}

Conclusion

Now you have your Ralph Storefront deployed with Fly.io. For more information on all the features Fly.io has to offer, visit their official documentation.