App Configuration

The sherpa.sh platform supports many different types of frameworks using the same simple settings. Below are the most common settings you need to set to deploy your web app.

Default Domain

This is the domain where you're application will be reachable by your users. It is fully customizable.

By default, your web app will be assigned a subdomain under sherpa.software. This is the address where users can access your application. For example, if your app is named "myapp," it will default to myapp.sherpa.software.

You can always change this domain to suit your preferences, or use a custom domain.

Build Settings

There are different build settings depending on what type of app you are building:

• View Javascript Build Settings

• View Docker Build Settings

Javascript Applications

The commands that are run when building the production version of your app. Typically, these are the install and build commands in your package.jsonfile.

You can use the following support package managers:

• npm

• pnpm

• yarn

• bun

Need something else? Let us know.

Framework

Select your projects framework. When your app is deployed we use your framework's best practices to optimize the infrastructure for your application. This means we setup all the appropriate cache-headers, distributed caching, and scaling algorithms to ensure a fast, delightful, and personalized customer experience.

If the framework you need is not listed or supported, let us know, we'll add it faster than you think!

Install Command

How you install your node modules and packages. Typically this is a command from your package.json. For example: npm i.

Build Command

How you build your project. Like npm run build. We set NODE_ENV=production by default for all builds of javascript applications. You can override this with environment variables.

Supporting .mjs files: Your project must support .mjs file types. If you have this disabled via eslint or typescript rules, you will need to enable it for your builds to complete.

If you are unsure, you likely do not need to worry about this. Most modern JS frameworks enforce this by default.

Output Directory

The directory path where your server.jsfile lives in your build output folder. Usually you want to leave this blank. Most frameworks will output your server.js into the root directory of your build output folder.

The exception is if you are using Turborepo or have a monorepo setup that can cause the server.jsfile to be nested differently. In that case, you'll need to use this field. If unsure, you can build the project locally and look inside the build output folder for your server.jsfile.

If you run into trouble, open a chat with us and we'll be happy to help you get setup.

If your app folder is nested in your repo, that does not mean the build output folder (for example .next in Next.js projects) will be nested in your project. To build a nested application in a repo use the root directory setting.

Docker Applications

Docker Settings

Two different settings are essential for Docker applications:

• Dockerfile: The name of the Dockerfile to build your application. If your docker file is not named Dockerfile this is where you put that value.

• Port: The port that your application exposes. Set the value of the exposed port that the application listens to in the container. This can only be one port. If you have multiple services that run on different ports please put them in separate containers. If they are in the same repo, you can import the repository twice and set different Dockerfile settings.

Root Directory

Sometimes your application will be in a sub-directory of your repo. Set this value to the directory path of your application in your repo. For example if you have a NextJS app inside of your repo in the path root > projects > mynextapp , in the root directory setting you would put the value projects/mynextapp.

All Build Setting commands will run inside this folder.

Environment Variables

The values that are called by process.envin your Node app. These values will be set in the build environment as well as the production environment where your app and functions are run.

Be cautious with the variables you expose to your application’s frontend. For instance, in Next.js applications, any variable prefixed with NEXT_PUBLIC_ will be accessible in the client-side code, exposing them publicly. Always ensure sensitive data remains secure and is not included in these public-facing variables. Please refer to your framework's documentation for more info.

When you have multi-line environment variables. All new lines should be replaced with the string equivalent: `\n`.

env files

If you have .envfiles committed into your repository that are used by your build commands. There are some important distinctions to be aware of:

1. Environment variables used in during static generation or the build process itself (like database URLs used in getStaticProps) are embedded into your app's build output and don't need to be added in the sherpa.sh dashboard.

2. Environment variables used only on the client-side (those prefixed with NEXT_PUBLIC_) are also embedded in the build output and don't need to be added in the sherpa.sh dashboard.

3. However, server-side-only environment variables (those without NEXT_PUBLIC_) are NOT embedded in the build output. These will be set dynamically sherpa.sh app in order for them to be present in your deployment. It is best practice to not include these values in your Github repository anyway.

Securing Credentials: We follow security best-practices for securing your environment variables. Environment variables are stored using AES encryption on a secure server. The decryption key is stored securely in a build system with extremely limited RBAC. Credentials are only decrypted on a as-needed basis to build your project. Otherwise they are always encrypted at rest.

This approach ensures that no unauthorized sherpa.sh employees can view your secrets. It also prevents attacker from retrieving plaintext secrets in the off chance they are able to get access to our systems.

App Region

When configuring your app region, you can choose from three options:

• US East (N. Virginia),

• US West (N. California)

• EU Central (Frankfurt, Germany).

This selection determines where your application will run. You want to select the location closest to your database(s) to minimize latency to and from your data.

Depending on your project's setup, many requests will hit your content cached on our global CDN and not your application - for example with partial pre-renders, cached content will exist on the network edge and your application will do minimal work to service the request.

For further info on the architecture, please refer to our architecture documentation.

NodeJS Version

The version of Node to use for the build process and for running your application.

Branch Settings

Configure how continuous delivery works on your application.

The selected branch will be the production branch, meaning any new commit on that branch will trigger a build and deployment to your Default Domain.

A build and deployment to a preview environment will also be triggered when a new pull request is opened for a different branch. New commits on branches with open pull requests will also trigger a new build and deployment to a preview environment. You can disable automatic deployments of preview branches by disabling auto branch deployments.