Reactium in Production

Reactium is designed to be easy to deploy to production.

Reactium is meant to be easy to build React apps, just like React Create App, appropriate to deploy to production in a wide set of circumstances, without the need to "eject" the app. That being said, the base case is well suited to deploying as a full Reactium project, using Heroku (basically effortless), using containers (see the Reactium Dockerfile), or a traditional CI/CD pipeline to a Node.js environment.

Production Build

To build the production assets, with the front-end images, styles, and Javascript bundles minified and gzip compressed, use the npm build script.

npx reactium install # installs build dependencies
npm run build # builds all front-end assets
npm prune --production # after build is complete, remove all development dependencies

After this, the minimum assets needed in the running Node.js 18+ environment will be:

1. package.json file

2. node_modules directory

3. reactium_modules directory

4. src directory

Running in Production

After deploying the above production build assets into your final environment, your environment should start the project using the npm start script (as normal convention for Node.js projects).

npm start

Environment Variables

The most common production use-case need is to be able to configure the running port for the server.

Set the PORT environment variable, if you need the server to run on something other than the default. Set this appropriately for your operating system, shell, etc. On Linux, this can also be provided on start.

PORT=8080 npm start

The default running port is 3030

Special Port Environments

In some deployment environments, you will not have direct control over the environment variable that provides the running port. Reactium also supports APP_PORT by default, as well as allowing administrators to specify by environment variable where Reactium should expect to find the running port.

# Specify where the port will be found in your environment
PORT_VAR=<YOUR_ENVIRONMENT_PORT_VAR> npm start 

See the Reactium Core - Environment Variables for additional environment variables.

Deploying only Front-End to CDN

If you have deployed your front-end javascript bundles from your public/assets/js directory into a CDN (such as cloud-front), you must let Reactium know where to find these files, so the entry minimal loading main.js bundle is able to find and load other bundles as needed to run the web application.

Running Reactium Server

If you deployed your public Javascript to a CDN, and still want to run the Reactium Node.js server, add your CDN path to the Javascript files, using the WEBPACK_RESOURCE_BASE environment variable.

WEBPACK_RESOURCE_BASE=https://cdn.example.com/path/to/js/ npm start

Running a different server

You can also let the Reactium main.js bundle know where to find other bundles in your HTML template directly, by adding the following to your HTML template:

<script>
    window.resourceBaseUrl = "https://cdn.example.com/path/to/js/";
</script>
<script src="https://cdn.example.com/path/to/js/main.js" />

This will work only if the src/app/main.js contains the default __webpack_public_path__ line. This file can be modified, but should contain the following for this to work:

__webpack_public_path__ = window.resourceBaseUrl || '/assets/js/';

Running with Actinium API Server

Dev/Ops should be aware that by default, when running Reactium with an Actinium server to provide the application's API, the Reactium server will automatically proxy any requests (server to server) with prefix /api to the Actinium instance. By default, it expects this server to be running on the same host on port 9000.

/api proxies to http://127.0.0.1:9000/api to be precise.

If you wish to proxy API requests to a different Actinium host and port (this is recommended), you will need to provide this as an environment variable to specify this base URI.

REST_API_URL=https://api.example.com/api npm start

You will need to allow server to server connection on the appropriate port to facilitate this proxy. Allow ingress to your API server from your Reactium server on whatever port you chose to run your API server on. This proxy will simplify Cross-Origin Resource Sharing (CORS) for your web app.

Direct API URL (Not Proxied)

If you do not wish to (or can not) proxy /api requests from server to server, you can configure the client to connect directly to the Actinium server.

PROXY_ACTINIUM_API=off REST_API_URL=https://api.example.com/api npm start

You will need to configure Actinium to handle Cross-Origin Resource Sharing (CORS) for your web app. By default, Actinium instructs the client to be permissive of other origins.

Deploying to Heroku

As was mentioned in the introduction, deploying Reactium (and most Node.js applications) to Heroku, is basically effortless. If your project codebase is hosted on Github (or Heroku's git), simply create a new application in the Heroku dashboards, connect your repository to Heroku on the Deploy tab, select which branch you wish to deploy from, and your are basically done. Pushing to this branch will automatically deploy the app.

Configuring Heroku to Deploy Reactium

Make sure the heroku-prebuild npm script exists in your package.json: (it will be by default)

"scripts": {
    "heroku-prebuild": "npx reactium install",
    "local": "gulp local",
    "start": "node src/index.mjs",
    "build": "cross-env NODE_ENV=production gulp"
  }

Running TLS over HTTP/2

If you plan to serve Reactium directly from your environment, place your OpenSSL certificate and key in a secure location on your server, and only allow your server's process to read these files. (lock down the permissions on this directory) Then instruct Reactium to start the server in TLS mode:

export REACTIUM_TLS_MODE=on
export REACTIUM_TLS_KEY=/path/to/server.key
export REACTIUM_TLS_CERT=/path/to/server.crt
export TLS_PORT=3443 # default TLS port
npm start

There can be some performance improvements to your application, in terms of delivering assets to the client running in direct TLS mode over HTTP/2.

HTTP/2 asset delivery benefits may be prevented / reversed if you have a HTTPS reverse-proxy or Application Load-Balancer (ALB) in front of your Reactium server. If this is your desired configuration, run Reactium over HTTP and terminate your TLS at the proxy/ALB instead.

Binding 80 and 443

Reactium will allow you to bind port 80 and 443, if you start Reactium as the root (or Windows Administrator) user.

You will need to provide deescalated user and group for the server to change the process to immediately after binding the listening ports.

Running as root user

export REACTIUM_TLS_MODE=on
export REACTIUM_TLS_KEY=/path/to/server.key
export REACTIUM_TLS_CERT=/path/to/server.crt
export PORT=80 # port 80 requires root
export TLS_PORT=443 # port 443 requires root
export REACTIUM_RUN_AS=webapp # or your desired user
export REACTIUM_RUN_AS_GROUP=webapp # or your desired group
npm start

This will start the server in plain text HTTP over port 80 and encrypted HTTP/2 over TLS on port 443, using the root user, and then will immediately steps the process down from root to the selected user/group, making it safer to run in production.

root or Administrator is required to bind ports 0 to 1000 on all operating systems.

This is supported on Windows, Linux, and Mac OS, however permission deescalation is only supported currently on Linux or Mac OS (BSD).

You will probably want to forgo running on port 80 or 443 in Windows, as the running server will be able to do anything to your entire system. Use a reverse proxy to Windows to achieve PORT 80 / 443 instead.