Deploy Templates

Feathers.js API Deploy Template

The Feathers.js API Deploy Template for Adaptable.io makes it simple to deploy an app based on the popular open source framework Feathers.js. In just a few clicks, Adaptable deploys all the cloud-based resources you need to run your full-stack Feathers app, including:

  • Building your app into Serverless Containers
  • Fully-managed Serverless Database (MongoDB, PostgreSQL, or MS SQL Server)
  • Autoscaling
  • Load Balancing
  • HTTPS (SSL/TLS)

»Using this template

The easiest way to take this template for a test drive is to create and deploy a new app with the Feathers Chat Starter.

Or, for step-by-step instructions on how to deploy your existing Feathers app with this template, check out the App Guide for Deploying a Feathers.js API App.

»About this template

This deploy template uses the Adapt.js infrastructure description language, which is based on React. It is open source and is available on GitHub.

»Template settings

»Base Directory

Specifies a sub-directory within your GitHub repo that will be used as the root of the app to be deployed.

Use this setting if you're deploying an app that is part of a monorepo or your app's package.json file is not in the root of your GitHub repo.

Default: <unset> (Uses package.json in the repository root directory)

example

You have a monorepo with source code for multiple apps. The package.json file for the app you want to deploy is located in your repo at apps/my-app/package.json.

In this case, Base Directory should be set to apps/my-app.

»Node.js Version

Sets the major version of Node.js to use for your app. The same Node.js version will be used for both building the container image and for running your app instances.

Each time you deploy a new app revision on Adaptable, the latest version of Node.js that the template supports within your chosen major version will be used to build and run your app.

The template currently supports only major Node.js versions in Active LTS or Maintenance LTS status. If you require a different version of Node.js, contact Adaptable support.

To find the major version of Node.js you're currently using in your development environment, use the command node -v and take only the first number.

Default: 16

example

You ran node -v on your development system and see that you're using v16.15.1.

In this case, you should set Node.js Version to 16.

»Build Scripts

Many Node.js apps require one or more build steps before they can be deployed in a production environment. Apps that use frameworks like React or Vue or transpilers like TypeScript or Babel typically need to run such a build step.

This setting allows you to specify build steps to run each time a new container image is built from your app source code. This template only supports running build scripts that are specified in the scripts property of your app's package.json. See the npm documentation for information on how to set up scripts. Any scripts you specify will be run using the detected package manager.

Set this setting to the name of a script from package.json to run at build time. Multiple build scripts can be specified by separating them with a comma. They will be run in the order you specify.

Default: <unset> (No scripts will be run during image build)

example

You need to run two scripts to fully build your app: compile, followed by minify.

In this case, Build Scripts should be set to compile,minify.

»Start Script

The name of the script from package.json that will be run to execute your app. Currently, this setting is always set to start and cannot be changed.

important

Your app is required to have a script named start in your package.json.

For more information on setting up a start script for your app, see the npm documentation.

Default: start (Cannot be changed)

»Runtime Environment Variables

You can specify your own custom environment variables that will be available to your app while it is running. For more information on setting custom environment variables, see Customizing Your App Environment.

The template also automatically provides several pre-set environment variables to your app at runtime:

  • ADAPTABLE_TRUST_PROXY_DEPTH: When this variable is set, it indicates that the app is behind one or more reverse proxies. The value is an integer number of proxies that your app may trust in the X-Forwarded-For HTTP request header. If this variable is set, the X-Forwarded-Proto and X-Forwarded-Host HTTP request headers may also be trusted.

  • DATABASE_URL: This is the URL that your app should use to contact the database provisioned alongside your app. It will include the database protocol, port, and hostname, as well as the username, password, and specific database to connect to. It may also have additional query parameters containing database options. This URL can often be used directly by a library such as Sequelize. If you manually parse this URL, be aware that all special characters in each portion of the URL have been URL-encoded and should be decoded before use.
    Example: postgres://dbuser:secret@database-1.adaptable.io:1234/my-app-db?option=enabled

  • EXTERNAL_HOSTNAME: This is the externally visible host and domain name for your app.
    Example: my-app.adaptable.app

  • EXTERNAL_URL: This is the externally visible URL where your app users can contact your app. This will always begin with https://.
    Example: https://my-app.adaptable.app

  • NODE_ENV: This will always be set to production.

  • PORT: The TCP port that your app must listen on to receive incoming network requests. Your app is required to listen on this port. See containerized app requirements for more information.

Apps that use a PostgreSQL database will also have the following environment variables set:

  • PGDATABASE: The name of the database to connect to.

  • PGHOST: The hostname of the database cluster.

  • PGPASSWORD: The password to use when connecting to the database. Note that this environment variable may contain special characters.

  • PGPORT: The TCP port number to connect to.

  • PGUSER: The username to use when connecting to the database.

Apps that use a Microsoft SQL Server database will also have the following environment variables set:

  • MSSQL_DATABASE: The name of the database to connect to.

  • MSSQL_HOST: The hostname of the database cluster.

  • MSSQL_PASSWORD: The password to use when connecting to the database. Note that this environment variable may contain special characters.

  • MSSQL_TCP_PORT: The TCP port number to connect to.

  • MSSQL_USER: The username to use when connecting to the database.

note

Runtime environment variables are not available during your app's build process.

»Build Environment Variables

You can specify your own custom environment variables that will be available to your app during the image build process. For more information on setting custom environment variables, see Customizing Your App Environment.

note

Build environment variables are only available during the build process, not during normal app runtime.

»Resources created

When this template is used to deploy your app, it creates the following Adaptable Cloud resources:

»Serverless database

The first time your app is deployed, the template creates a fully-managed serverless database that your app can use to store its data.

This template supports MongoDB, PostgreSQL, and Microsoft SQL Server.

Connection information for the database is provided directly to your running app via the DATABASE_URL environment variable.

tip

When using an Adaptable MongoDB database, your Feathers services should use either the feathers-mongoose or feathers-mongodb database adapters.

When using an Adaptable PostgreSQL or MS SQL Server database, your Feathers services should use either the feathers-sequelize or feathers-knex database adapters.

»Load balancer

The template creates an HTTPS load balancer that sits in front of your app. This means that your deployed app immediately supports TLS encryption and advanced protocols like HTTP/2 and HTTP/3 without having to change your app source code.

»Container image

The template automatically builds your app source code from your GitHub repo into a Kubernetes-compatible container image each time you push to your selected branch on GitHub.

It uses Cloud Native Buildpacks to build the image, then pushes it to your app's private container registry.

If your app requires one or more custom build steps to be run during the image build process, see Build Scripts. To provide environment variables that can be accessed during the image build process, see Build Environment.

»Serverless containers

After the template builds your app into a container image, it deploys that image to the Adaptable Container Service, which is a highly scalable serverless platform based on Kubernetes.

»Package manager

The template supports using either npm or yarn package managers. If your app repo contains a yarn.lock file in the same directory as your package.json, then yarn will be used to install dependencies and run any scripts. Otherwise, npm will be used.

»Pre-flight checks

This template includes a set of pre-flight checks that are performed before your app is deployed. These checks help ensure your app meets certain requirements and can identify some common issues before deployment.

»Check: package.json exists

To deploy a Node.js app, the template must be able to locate the package.json file that corresponds to the app you are deploying.

By default, the template looks for package.json in the root of your GitHub repo. If your app's package.json is in a sub-directory of your repo, you need to set Base Directory to the directory that contains package.json.

If this check fails:

  • Confirm you are deploying the correct GitHub repo and correct branch which contains a package.json file for your Node.js app.

  • Confirm your app's package.json file is in the root directory of your GitHub repo or you have set Base Directory to the directory path within the repo where your package.json file is located.

»Check: Build script exists

This checks that the names of any Build Scripts you specified in the settings exist as keys in the scripts property of your app's package.json file. If you did not set the Build Scripts setting, this check always passes.

If this check fails:

  • If the error message says There is a syntax error in 'package.json', it will typically give the line number where the error occurs in the file. If you recently modified your package.json, examine the recent changes for possible mistakes. You can check your package.json file for errors on your local development system by re-installing with your package manager (npm install or yarn install).

  • Confirm you are deploying the correct GitHub repo and correct branch which contains the scripts in your package.json file.

  • If your app's package.json is not in the root directory of your GitHub repo, confirm that the Base Directory setting points to the directory with the correct package.json file.

  • Confirm that the Build Scripts setting contains only the name of the script you wish to run with no extra whitespace and is not prefixed by npm run. If you wish to run multiple scripts, separate them with only a comma and no whitespace.

  • The error message should contain the name of the script that could not be found. Confirm the name in the error message exactly matches a property name within the scripts object of your package.json and that the corresponding value is not the empty string ("").

  • For more information on setting up scripts for your app, see the npm documentation.

»Check: Start script exists

This checks that your app's package.json file contains a scripts object with a key named start and the value of that key is not the empty string ("").

If this check fails:

  • If the error message says There is a syntax error in 'package.json', it will typically give the line number where the error occurs in the file. If you recently modified your package.json, examine the recent changes for possible mistakes. You can check your package.json file for errors on your local development system by re-installing with your package manager (npm install or yarn install).

  • Confirm you are deploying the correct GitHub repo and correct branch which contains the start script in your package.json file.

  • If your app's package.json is not in the root directory of your GitHub repo, confirm that the Base Directory setting points to the directory with the correct package.json file.

  • Confirm that your package.json contains a top-level scripts object and that object has a key named start and the value of that key is not the empty string ("").

  • For more information on setting up scripts for your app, see the npm documentation.

»Check: Template settings validated

This checks that your Adaptable app's settings object matches the structure required by the template. Normally, Adaptable checks this each time you modify your app's settings and will not allow you to save invalid settings.

If this check fails:

»Check: HTTP Listener on PORT

In order to run your app on the Adaptable Container Service, it must be an app that listens for HTTP requests. More specifically, it must listen on IP address 0.0.0.0 on the TCP port specified by the PORT environment variable.

tip

To correctly set this up for a Feathers app, follow the instructions for setting up your Feathers.js production config.

This check cannot be done automatically by analyzing your app's source code, so the first time your app is deployed on Adaptable, you'll be asked to click the checkbox that confirms that your app will listen on the port specified by PORT.

If you have a different kind of app that you'd like to deploy or if you need help getting your app set up correctly, we can help! Contact Adaptable's friendly support team for more information.

»Feathers.js production config

To use these environment variables in Feathers, edit your config/production.json file and ensure the following properties are set exactly like the ones below. Note that you only need one of either mongo, postgres, or mssql, corresponding to the type of database you wish to use on Adaptable.

{
"host": "EXTERNAL_HOSTNAME",
"port": "PORT",
"mongo": "DATABASE_URL",
"postgres": "DATABASE_URL",
"mssql": "DATABASE_URL"
}

»Additional app requirements

»Containerized app requirements

In order to run your app on the Adaptable Container Service, it must meet a few requirements. Most web-based apps shouldn't have trouble meeting these requirements.

  • Your app must listen for HTTP requests on 0.0.0.0 on the TCP port specified by the PORT environment variable. (Contact support if this is difficult for your app.)

  • Your app must be stateless. Although your app can write to local disk storage, that storage is a memory file system and will be lost when your app is scaled down or updated. Local disk storage is also not shared between multiple autoscaled instances of your app. This means your app cannot use local file-based databases, such as NeDB or SQLite.

  • Your app cannot perform background activities outside the scope of request handling. Your app's CPU allocation is set to zero when your app is not processing a network request.

  • You should not perform HTTPS/TLS in your app itself. Adaptable automatically provides HTTPS/TLS via our highly scalable load balancing tier.

  • When your app starts, it must listen for HTTP requests within 4 minutes of being started.