# Configure Gatsby for Upsun Fixed


You now have a *project* running on Upsun Fixed.
In many ways, a project is just a collection of tools around a Git repository.
Just like a Git repository, a project has branches, called *environments*.
Each environment can then be activated.
*Active* environments are built and deployed,
giving you a fully isolated running site for each active environment.

Once an environment is activated, your app is deployed through a cluster of containers.
You can configure these containers in three ways, each corresponding to a [YAML file](https://fixed.docs.upsun.com/learn/overview/yaml):

- **Configure apps** in a `.platform.app.yaml` file.
  This controls the configuration of the container where your app lives.
- **Add services** in a `.platform/services.yaml` file.
  This controls what additional services are created to support your app,
  such as databases or search servers.
  Each environment has its own independent copy of each service.
  If you're not using any services, you don't need this file.
- **Define routes** in a `.platform/routes.yaml` file.
  This controls how incoming requests are routed to your app or apps.
  It also controls the built-in HTTP cache.
  If you're only using the single default route, you don't need this file.

Start by creating empty versions of each of these files in your repository:

```bash
# Create empty Upsun Fixed  configuration files
mkdir -p .platform && touch .platform/services.yaml && touch .platform/routes.yaml
```

Now that you've added these files to your project,
configure each one for Gatsby in the following sections.
Each section covers basic configuration options and presents a complete example
with comments on why Gatsby requires those values.

## Configure apps in `.platform.app.yaml`

Your app configuration in a  `.platform.app.yaml` file is allows you to configure nearly any aspect of your app.
For all of the options, see a [complete reference](https://fixed.docs.upsun.com/create-apps/app-reference/single-runtime-image.md).
The following example shows a complete configuration with comments to explain the various settings.

In the template, ``yarn`` is run during the build hook to install all of Gatsby’s dependencies, and then ``yarn build`` is run to build the site and output to the ``public`` subdirectory. If you would rather use ``npm`` to manage your dependencies, you can:

 - delete ``yarn`` from the build hook
 - update ``yarn build`` to ``npm run build`` in the build hook
 - delete the ``build.flavor`` block, which tells Upsun Fixed to rely solely on the build hook to define the build process for your project when set to ``none``. By default, Node.js containers run ``npm install`` prior to the build hook, so this block can be removed entirely from the configuration.
 - delete the ``dependencies`` block, which includes ``yarn``, since it is no longer needed.

All traffic is then directed to the ``public`` subdirectory once the deployment has completed via the ``web.locations`` section.

```yaml  {location=".platform.app.yaml"}
# Complete list of all available properties: https://docs.upsun.com/anchors/fixed/app/reference/

# A unique name for the app. Must be lowercase alphanumeric characters. Changing the name destroys data associated
# with the app.
name: 'app'

# The runtime the application uses.
# Complete list of available runtimes: https://docs.upsun.com/anchors/fixed/app/reference/type/
type: 'nodejs:18'

# The size of the persistent disk of the application (in MB). Minimum value is 128.
disk: 5120

# The web key configures the web server running in front of your app.
# More information: https://docs.upsun.com/anchors/fixed/app/reference/web/
web:
  # Each key in locations is a path on your site with a leading /.
  # More information: https://docs.upsun.com/anchors/fixed/app/reference/web/locations/
  locations:
    '/':
      # The directory to serve static assets for this location relative to the app’s root directory. Must be an
      # actual directory inside the root directory.
      root: 'public'
      # Files to consider when serving a request for a directory.
      index: [ 'index.html' ]
      # Whether to allow serving files which don’t match a rule.
      allow: true

# Specifies a default set of build tasks to run. Flavors are language-specific.
# More information: https://docs.upsun.com/anchors/fixed/app/reference/build/
build:
  flavor: none

# Installs global dependencies as part of the build process. They’re independent of your app’s dependencies and
# are available in the PATH during the build process and in the runtime environment. They’re installed before
# the build hook runs using a package manager for the language.
# More information: https://docs.upsun.com/anchors/fixed/app/reference/dependencies/
dependencies:
  nodejs:
    yarn: "1.22.5"

# Hooks allow you to customize your code/environment as the project moves through the build and deploy stages
# More information: https://docs.upsun.com/anchors/fixed/app/reference/hooks/
hooks:
  # The build hook is run after any build flavor.
  # More information: https://docs.upsun.com/anchors/fixed/app/hooks/compare/build/
  build: |
    yarn
    yarn build

# Information on the app's source code and operations that can be run on it.
# More information: https://docs.upsun.com/anchors/fixed/app/reference/source/
source:
  ######################################################################################################################
  ##                                                                                                                  ##
  ## This source operation is part of the Upsun Fixed process of updating and maintaining our collection of           ##
  ## templates. For more information see https://docs.upsun.com/anchors/fixed/app/reference/source/operations/ and    ##
  ## https://github.com/platformsh/source-operations                                                                  ##
  ##                                                                                                                  ##
  ##                  YOU CAN SAFELY DELETE THIS COMMENT AND THE LINES BENEATH IT                                     ##
  ##                                                                                                                  ##
  ######################################################################################################################
  operations:
    auto-update:
      command: |
        curl -fsS https://raw.githubusercontent.com/platformsh/source-operations/main/setup.sh | { bash /dev/fd/3 sop-autoupdate; } 3<&0

```

## Add services in `.platform/services.yaml`

You can add the managed services you need for you app to run in the  `.platform/services.yaml` file.
You pick the major version of the service and security and minor updates are applied automatically,
so you always get the newest version when you deploy.
You should always try any upgrades on a development branch before pushing to production.

Gatsby doesn't require services to deploy, so you don't need a `.platform/services.yaml` file for now.
You can [add other services](https://fixed.docs.upsun.com/add-services.md) if desired,
such as [Solr](https://fixed.docs.upsun.com/add-services/solr.md) or [Elasticsearch](https://fixed.docs.upsun.com/add-services/elasticsearch.md).
You need to configure Gatsby to use those services once they're enabled.

## Define routes

All HTTP requests sent to your app are controlled through the routing and caching you define in a `.platform/routes.yaml` file.

The two most important options are the main route and its caching rules.
A route can have a placeholder of `{default}`,
which is replaced by your domain name in production and environment-specific names for your preview environments.
The main route has an `upstream`, which is the name of the app container to forward requests to.

You can enable [HTTP cache](https://fixed.docs.upsun.com/define-routes/cache.md).
The router includes a basic HTTP cache.
By default, HTTP caches includes all cookies in the cache key.
So any cookies that you have bust the cache.
The `cookies` key allows you to select which cookies should matter for the cache.

You can also set up routes as [HTTP redirects](https://fixed.docs.upsun.com/define-routes/redirects.md).
In the following example, all requests to `www.{default}` are redirected to the equivalent URL without `www`.
HTTP requests are automatically redirected to HTTPS.

If you don't include a `.platform/routes.yaml` file, a single default route is used.
This is equivalent to the following:

```yaml  {location=".platform/routes.yaml"}
https://{default}/:
  type: upstream
  upstream: <APP_NAME>:http
```

Where `<APP_NAME>` is the `name` you've defined in your [app configuration](#configure-apps-in-platformappyaml).

The following example presents a complete definition of a main route for a Gatsby app:

```bash  {location=".platform/routes.yaml"}
# The routes of the project.
#
# Each route describes how an incoming URL is going
# to be processed by Upsun Fixed.
# More information: https://docs.upsun.com/anchors/fixed/routes/
"https://{default}/":
  type: upstream
  upstream: "app:http"

```