Prerequisites

info

These prerequisites are only necessary for running the backend on your development machine or deploying to the cloud. They're not required for everyone on the project since running the backend is only needed in specific scenarios.

The prerequisites you installed when you got started were to be able to run Redwood without Kubernetes, but to be able to deploy to a Kubernetes cluster you need to install a few more things. Deploying to Kubernetes is required for deploying to the cloud, but it's also useful for testing locally before deploying to the cloud.

• NodeJS
• Pulumi Infrastructure as Code (IaC)
• Windows Subsystem for Linux (WSL)
• Rancher Desktop

NodeJS

NodeJS is used for the entire backend infrastructure as well as the deployment scripts. It's required when deploying to a Kubernetes cluster, locally or remotely.

Installing Node

warning

We require NodeJS v20; note that other versions are not currently compatible with Redwood.

While you can install NodeJS v20 using the official installer from https://nodejs.org, we prefer to use NVM (Node Version Manager). Both will work just fine; NVM just makes it easy to switch and upgrade your version of NodeJS. If you want to install using NVM but already have NodeJS installed using the official installer from https://nodejs.org, you will need to uninstall it before using NVM.

• NVM for Windows: https://github.com/coreybutler/nvm-windows/releases/latest/nvm-setup.exe
• NVM for Mac/Linux: https://github.com/nvm-sh/nvm#install--update-script

Once you have NVM installed, you can run the following command to install NodeJS v12:

Windows

nvm install 20
nvm use 20

Mac/Linux

nvm install 20

Then make sure you can use the node executable:

node --version

Installing Yarn

Once you have installed NodeJS, you need to install yarn, which is used to install dependencies and run scripts for the backend. We use version 1.22.19, which you can download by running the following command:

npm install --global [email protected]

If you're an advanced NodeJS user and use corepack, you can run corepack prepare in the root of the Redwood Backend directory to switch to the correct version of yarn.

Pulumi

There are multiple frameworks to define IaC; we use Pulumi which is built on top of the popular framework Terraform. Pulumi allows us to write the IaC as NodeJS/TypeScript instead of having to learn the declarative scripting language Terraform uses.

Pulumi also has a backend service (Pulumi Cloud) that keeps track of the versions that are deployed to determine the iterative changes that are necessary when trying to deploy. Having this as a service is very helpful if you need multiple people to be able to deploy. pulumi.com provides managed hosting for Pulumi Cloud with a fairly comprehensive free tier, but you can also self-host.

info

You can opt out of Pulumi Cloud completely by using pulumi login --local. You'll still need to install the Pulumi CLI, but the Pulumi state is stored locally on your machine and is not synced anywhere. The "Pulumi Organization Name" that's mentioned in these docs will need to be organization when using the local state provider.

You can also use object storage backends for your state.

These are viable options for getting started quickly, but there are many reasons to use Pulumi Cloud. Our docs assume you're using self-hosted or Pulumi-hosted Pulumi Cloud.

1. Install the Pulumi CLI
2. Create a Pulumi Cloud account
   note

   We recommend using Pulumi's free SaaS offering to start with; you can choose to self-host after you've familiarized yourself more with Redwood and Pulumi.

3. Create or join an Organization on Pulumi

WSL

note

This is only required for deploying to a local Kubernetes cluster on a Windows machine. We recommend testing locally before deploying to the cloud, but this step could be skipped if you're only deploying to the cloud.

WSL, or Windows Subsystem for Linux, is an extra runtime that will run Linux simultaneously in the background as you run Windows. We use this to be able to replicate the production environment for the backend closely, and it makes development much simpler.

Please follow the official Microsoft guide on how to install WSL. The Linux distribution you use is flexible; we recommend Ubuntu which is the default with the wsl --install command provided in the linked guide.

Rancher Desktop

note

This is only required for deploying to a local Kubernetes cluster on a Windows machine. We recommend testing locally before deploying to the cloud, but this step could be skipped if you're only deploying to the cloud.

Rancher Desktop (not to be confused by Rancher), is an easy to use tool that provides Docker and Kubernetes to the WSL environment. We use Docker to create containers of each backend service, which we then run in a Kubernetes cluster. It's okay if these terms are confusing; by design, Redwood handles getting things running in these more complicated environments so you can learn the subjects later if/when it's needed. Simply put, Rancher Desktop helps us replicate a scalable server environment for the backend.

note

If you are already using Docker Desktop, you may be able to enable Kubernetes within Docker Desktop and use that. It's not officially supported, but it should work. You would need to find instructions on how to enable Kubernetes on Docker Desktop.

1. Find an installer for Rancher Desktop at https://rancherdesktop.io/.

2. Running Rancher Desktop for the first time will ask what version of Kubernetes and the Container Engine you want. We currently test on the latest version of v1.27 and dockerd (moby) respectively.

   note

   We don't use the latest v1.28 version of Kubernetes yet as it requires more testing.

   

3. Run the application once it's installed. From here, open the Preferences under the File menu:

   

4. Under the WSL > Integrations tab, make sure the distribution you're using is checked:

   

5. Under the Container Engine tab, select dockerd (moby) under the General sub-tab:

   

6. Finally under the Kubernetes tab, make sure Enable Kubernetes is checked and the Kubernetes version is the latest v1.27 version. Make sure Enable Traefik is not checked.

   

7. Click Apply.

info

Rancher Desktop doesn't start automatically with Windows, so you may have to run it manually after a reboot.