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 ( 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

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

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:


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



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.