Node.JS

Qoddi automatically builds your Node.JS apps created from the platform.
In order to do that, Qoddi uses buildpacks to detect and build your app automatically.

Before building your code

Qoddi requires several files to be placed inside the root directory of your app to be able to build it :

• package.json
• At least one .js file (your code)
• a Procfile with a start command
• In order to install dependencies, a vaild npm, yarn, or pnpm lockfile must be present.

You can fork or build this repository to see how the app creation process works.

Add-ons to run specific Frameworks

Qoddi developed specific add-ons to run popular NodeJs frameworks.

Those add-ons automatically take care of everything specifically related to a framework including the Node environment variables required to run your app, the network settings, and the post-build scripts.

As of today, add-ons are available for :

NuxtJS

Gatsby

RedwoodJS

Create your app on Qoddi

Create a new app and link it with your repository using SSH keys.

Read this article for a detailed procedure or check this video :

Default env variables

When Qoddi deploys a Node.JS app, it automatically creates two environment variables: PORT and HOST

It’s critical to verify that those variables are used inside your code or that the values inside your code match the values of those environment variables.

To access env variables from your code you can use const PORT = process.env.PORT

Using the wrong port or host value will cause your app to crash to a 502 error.

Procfile

The Procfile helps Qoddi prepare the infrastructure according to your app needs and determine the launch sequence of your app after the build. On Qoddi’s infrastructure, the Procfile always starts by web: regardless of your app type (even for a worker).

The Procfile basically contains the type of app and the initial script to run when the app starts :

web: npm start

Customizing the Build process

If your app has a build step that you’d like to run when you deploy, you can use a build script in package.json:

"scripts": {
  "start": "node index.js",
  "build": "webpack"
}

It’s critical to use the proper start command (in Procfile) and build command (inside package.json) for your app to build and run properly.

Package.json

The mandatory file package.json is where the Node.JS settings of your app are declared. Heres’ an example :

{
  "name": "flashdrive_node_app",
  "version": "1.0.0",
  "description": "Node.js on Qoddi",
  "author": "First Last <[email protected]>",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.16.1"
  }
}

Please check this article for a detailed method on how to use your domain name with Qoddi apps.

Specify a Node.JS version

Node versions adhere to semver, the semantic versioning convention popularized by GitHub. Semver uses a version scheme in the form MAJOR.MINOR.PATCH.

• MAJOR denotes incompatible API changes
• MINOR denotes added functionality in a backward-compatible manner
• PATCH denotes backward-compatible bug fixes

To specify a Node.js version, set the engines.node in the package.json file to the semantic versioning specification (semver) range or the specific version of Node you are using.

Example showing a semver range:

"engines": {
  "node": "21.01.x"
}

Example showing a specific version:

"engines": {
  "node": "21.01.1"
}

If you try to use a version that is not currently supported, the build of your app will fail.

Currently, supported versions are 20.x and 21.x

You can still build your app using an older version of Node using a specific env variable (see below)

Build with older versions of Node

While Qoddi officially supports only Node versions above Node 18.x, you can still build your app with an older version of Node. Qoddi automatically recognizes your old version of Node and builds your app accordingly.

Specify a NPM version

To specify an npm version, set engines.npm in the package.json file to the semantic versioning specification (semver) range or the specific version of npm you are using:

Example showing a semver range:

"engines": {
  "node": "18.01.x",
  "npm": "7.6.x"
}

Example showing a specific version:

"engines": {
  "node": "18.01.1",
  "npm": "7.6.3"
}

If you do not specify an npm version, your app uses the default npm packaged with the Node.js version used by your app, as specified on the Node.js releases page.

Do not include Dev Dependencies in your build

Qoddi automatically builds devDependencies and Dependencies from your package.json file. The build is pruned before being sent to the production server and, in most cases, you should always use the default behavior as some packages are required for the build to complete.

If you want to prevent the builder to include devDependencies during the build phase, create an Environment Variable NODE_ENV with the value production and relaunch your build.

Using Yarn instead of NPM

By default, the Node.js buildpack assumes you are using NPM. If you want to use Yarn instead, you must provide a yarn.lock file in your top-level app directory. For more information on the Yarn lock file, see yarn.lock in the Yarn documentation.

Fix missing dependencies

If some dependencies declared inside package.json are not available directly the build can fail. To prevent that, add npm update && inside the build sequence of package.json :

"scripts": {
  "start": "node index.js",
  "build": "npm update && webpack"
}

Debug and Access Logs

The log page inside your App settings only provides limited logs and is erased after each app reboot or rebuild.

Launch a Console Command

Please check this article on how to launch a command directly to your running app. This can be used to perform database migrations, launch local scripts, or perform database backups.

Ephemeral Disk

Contrary to Marketplace apps that can use Qoddi’s virtual disks features to store and retrieve persistent data, apps that are created from code use an immutable file system.

You can write data locally, for instance, to process files temporarily during your application life, but the data written into your app’s disk is not persistent and gets wiped out after your app restart.

All apps restart at least once every 24 hours, to apply a new setting or to deploy a new build.

To store data and keep it persistent you can use external services like Amazon S3 or Wasabi, an S3 compatible storage service with very affordable pricing.

Define environment variables

Note: Environment variables set in your app settings are injected during the build process. If the build of your app needs to use an env variable make sure to set it before requesting the build.

Qoddi lets you externalize the configuration of your app: the Qoddi cluster will automatically inject the data when the app starts or restart.

Environment variables can include any external data your app needs to run like external resources, databases addresses, encryption keys, etc…

To add an environment variable, access your app settings and click “Add ENV Variable” :

Enter the key (like DATABASE_USER) and the value and click “Add”. Qoddi will automatically add your environment variable and restart your app after a one-minute delay (to let you add more env variables if necessary without restarting the app each time a new variable is added).

Add a domain name

Please check this article for a detailed method on how to use your domain name with Qoddi apps.

Provision a database

Qoddi’s Marketplace includes all popular datastore engines including Mysql, Postgres, MongoDB, and Redis.
To add a database to your app, click on Marketplace and select the database you want to run, then create the new app database inside the same stack as your Node.JS app.

Once the app is running, visit the database app’s settings and retrieve the “internal name” :

Use this internal name as you would use a server address, for instance for MySQL this name replaces the usual “localhost”. Some scripts require you to add the database port at the end of the server address. Qoddi uses a common port for each database software, for MySQL it will be 3306 and you can write it like that inside your scripts: internal-name:3306
Postgres usually uses credentials sent inside the login URL, like that : postgres://<user>:<password>@<internalname>:5432/<database>

The login and password information is available inside the Environment Variables of the database app.

Note: Qoddi’s datastores run on a private and encrypted network. Therefore SSL support is deactivated for all datastores available on Qoddi. Ensure that your code doesn’t require using SSL before deploying your app.

Run Database migration

Qoddi runs on a high availability infrastructure that separate the builders into another, private network with a dedicated registry. This is mainly to achieve the highest level of isolation between apps, builders and data centers.

Qoddi’s builders cannot access the datastores inside a stack so database initialization and migration cannot be performed during the build phase and the build itself may fail because of that.

To run a database initialization or migration you need to add the sequence inside the Procfile before the initialization command:

web: yarn db migration && yarn serve

The command above is just an example, you need to use the migration and start commands related to your app. A Procfile is mandatory to be able to run database migrations.

Reach your app from another app

Inside your app stack, you can reach any other Qoddi app member of this stack on any port. Qoddi automatically routes the traffic internally and opens the appropriate port. By opposition, your app is only reachable on ports 80/443 from outside of Qoddi.

To reach your app internally, retrieve the internal name from your app settings page:

This name can be used to reach your app from another app inside the same stack. Use it in any form that works with your script:

http://<internalname>
<internalname>
http://<internalname>:port
mongodb://<login>:<password>@<internalname>:port

Note: https:// is not available, all the traffic inside apps is already encrypted by the cluster.

Encryption

Qoddi uses at rest encryption for the app virtual disks, build images, and encrypted transport from inside the cluster. To make sure the traffic is encrypted between your app and the browser of your users you can set up SSL certificates for any domain name connected to the app (including the FlashDrive’s default domain name).

Scale your App

From your app settings you can scale your app vertically and horizontally: by upgrading the app size (refer to our pricing for app sizes details) or by adding more nodes.

Additional nodes will run another copy of your app inside another Qoddi’s server located inside the same cluster (same geographical location). Traffic is automatically sent to the least occupied node by Qoddi’s load balancer.

Was this helpful?

YesNo

19 / 1