App Guides

Deploying a Feathers.js API App

This guide will help you deploy your Feathers.js API app to the Adaptable Cloud. In just a few clicks, Adaptable deploys all the cloud-based resources you need to run your 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)

»Step 1: Get your app ready

Before you get started deploying your existing app, you may want to review the Adaptable containerized app requirements.

»Set up your production config

Adaptable provides environment variables to your app with information about its hostname, what port to listen on, and how to connect to the fully-managed database that is deployed alongside your app.

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.

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"
}

»Set up a start script

Make sure your app has a script named start defined in your app's package.json. Adaptable will run the start script to execute your app.

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

»Test your changes

To confirm your changes work as expected, try running your app in your development environment with the PORT environment variable set:

PORT=1234 npm run start

You should be able to connect locally to your app at http://localhost:1234

»Push to GitHub

Make sure that any changes you made to your project from the steps above have been committed to git and pushed to your GitHub repo.

»Step 2: Connect to GitHub

Start by clicking the button below:

If you're not already signed in, click Sign in with GitHub.

Signing into GitHub

If you haven't yet connected any of your GitHub repositories to Adaptable, click Connect GitHub Repository.

Connecting a GitHub repo

Choose which scope you'd like to connect Adaptable to. You can connect Adaptable to your personal GitHub scope or to an organization you're a member of.

Install Adaptable on GitHub

And finally, click the Install & Authorize button.

Authorize Adaptable on GitHub

»Step 3: Choose a GitHub repo to deploy

Now you should see a list of GitHub repos where you've authorized Adaptable. Choose the repo you'd like to deploy to the Adaptable Cloud.

If you don't see the repo you're looking for, click Add more GitHub repositories to authorize Adaptable on more of your repos or GitHub organizations.

List of GitHub repos

Then choose which branch you'd like to deploy. Once connected, Adaptable will deploy your repo each time you push to this branch.

List of repo branches

»Step 4: Choose a Deploy Template

Since you're deploying a Feathers app, choose the Feathers.js API Template.

Choosing a deploy template

»Step 5: Review settings

The default settings for the Deploy Template are shown. For more information on each setting, click the help icon next to the setting or see the template documentation. To change a setting, click Change next to the setting you wish to change.

When you're satisfied with the settings, click Next.

Reviewing template settings

»Step 6: Choose an app name

Choose a name for your app project on Adaptable. This name will be used to create a URL for your project like https://YOURAPPNAME.adaptable.app, so it must be unique among all other app names on Adaptable.

Enter your chosen app name and click Next.

Choosing an app name

»Step 7: Pre-flight checks

Adaptable will now perform some basic checks on your GitHub repo to ensure it's ready to deploy.

Most of the checks can be performed automatically. However, this screen asks you to manually confirm that your app listens for HTTP requests on the port specified by the environment variable PORT. (See Step 1 above.) Click the square checkbox to confirm.

For more information on any of the checks, see Pre-flight checks. If the checks do not pass or you have more questions on them, contact our support team for help.

When the checks have passed, click Deploy App to start deploying your new app.

Performing pre-flight checks

»Deployed!

Once deployment is complete, your app will be running at https://YOURAPPNAME.adaptable.app. Click the Visit App button to connect to your app.

Deployment complete
tip

Now that your app is set up on Adaptable, each time you push to the branch you selected on your GitHub repo, Adaptable will automatically deploy your code changes.

To manage settings for your app and to monitor app logs, click the App Status button. Or to see all your Adaptable apps, go to your Dashboard.

»Having trouble?

If your app didn't build or deploy successfully, click View Logs next to the failed step to see the related logs. If you need to make any code changes, you can push to your GitHub repo to update your app and Adaptable will re-deploy it. Monitor additional deploys by clicking the App Status button.

If you're still having trouble deploying, contact our support team for help.

»Additional info

»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.

»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.