Node.js Installation

Last Updated: 2021-02-08

This guide will help you run the Grouparoo application on your local machine using Node.js.

Step 1: Install Node.js Runtime and Databases

Grouparoo is a Node.js application and requires Node.js version 12 or higher. You can download Node.js from the website or through the package manager for your operating system.

Install Node.js on MacOS
# Install Homebrew (https://brew.sh) if you don't have it
# If you have Homebrew, you'll also have Xcode Command line tools, which are needed (`sudo xcode-select --install`)

brew install node # Install Node.JS (v16 recommended)
Install Node.js on Ubuntu Linux
... or other Linux distributions that use the `apt` package manager.
# Install dependencies
sudo apt-get install curl wget build-essential python -y

# Install NVM and a modern node.js version
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash # https://github.com/nvm-sh/nvm to learn more
source ~/.bashrc # re-source the NVM shell helpers
nvm install v16 # install v16 of Node.js
nvm use v16 # use v16 of Node.js
Install Node.js on CentOS, Red Hat, or AWS Linux
... or other Linux distributions that use the `yum` package manager.
# Install dependencies
sudo yum install wget curl gcc gcc-c++ make python -y

# Install NVM and a modern node.js version
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash # https://github.com/nvm-sh/nvm to learn more
source ~/.bashrc # re-source the NVM shell helpers
nvm install v16 # install v16 of Node.js
nvm use v16 # use v16 of Node.js
Grouparoo is not supported on Windows

However, you can use the Windows subsystem for Linux to run Ubuntu and follow the steps in in the Ubuntu tab


By default, Grouparoo will run from a SQLite database and in-memory Redis, so no external dependencies are required. However, if you want to safely persists data between runs, you'll need to also install Postgres and Redis. When deploying Grouparoo, the best practice would be to use hosted versions of these databases from your cloud provider.

Install Postgres and Redis on MacOS
brew install redis # Install Redis
brew services start redis # Start Redis

brew install postgresql # Install Postgres
brew services start postgresql # Start Postgres
Install Postgres and Redis on Ubuntu Linux
sudo apt install redis-server # Install & Start Redis

sudo apt install postgresql postgresql-contrib # Install & Start Postgres
Install Postgres and Redis on CentOS, Red Hat, or AWS Linux
... or other Linux distributions that use the `yum` package manager.
sudo yum install redis # Install Redis
sudo systemctl start redis # Start Redis

Installing Postgres is a bit more complex:

Grouparoo is not supported on Windows

However, you can use the Windows subsystem for Linux to run Ubuntu and follow the steps in in the Ubuntu tab


Finally, create a Postgres database for Grouparoo to use with createdb grouparoo_development (this is not needed if you are using a SQLite database).

Step 2: Generate package.json and .env

In a new directory, run the following command to initialize a new Grouparoo application and install dependencies:

npm install -g grouparoo # Install the Grouparoo command line tool
grouparoo init . # Initialize a new Grouparoo project

This will create a package.json and .env files like these:

package.json

{
  "name": "my-grouparoo-project",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@grouparoo/core": "1.2.3",
    "@grouparoo/ui-community": "1.2.3"
  },
  "scripts": {
    "start": "cd node_modules/@grouparoo/core && ./bin/start",
    "dev": "cd node_modules/@grouparoo/core && ./bin/dev"
  },
  "grouparoo": {
    "plugins": ["@grouparoo/ui-community"]
  }
}

Grouparoo is configured by environment variables. These environment variables tell Grouparoo how to connect to your database, which URL to use, etc. In development, we can also load these variables from a .env file that lives alongside your package.json. At minimum, you will need to set the following variables:

.env

PORT=3000
WEB_URL=http://localhost:3000
WEB_SERVER=true
WORKERS=1
REDIS_URL="redis://localhost:6379/0"
DATABASE_URL="postgresql://localhost:5432/grouparoo_development"
SERVER_TOKEN="a-random-string"

Grouparoo is configured via Environment variables. Learn more about the environment variables in use by Grouparoo and see a full default configuration.

Only these 2 files (a package.json and environment variables) are needed to make an "App" for Grouparoo to run!

Step 3: Install New Plugins

Run grouparoo install [plugin] to install the plugins you may want. Plugins are how the Grouparoo application can be extended to use new Sources and Destinations. Learn more here.

If you are having trouble installing dependencies, and you are using NPM v7 or later, please see this discussion for help

Step 4: Configure & Run!

Now you're ready to run the application! You can do so via grouparoo start or npm start to start the server. You should then be able to visit http://localhost:3000 (with 3000 being the value for $PORT from .env). Note that starting the Grouparoo application will also migrate your database and generally configure things as-needed.

If everything looks good, it's time to get your application configured! Head over to the Configuration Guides.