Node.js Installation

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.

• MacOS
• Linux - Ubuntu
• Linux - CentOS, Red Hat, and AWS Linux
• Windows

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

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.

• MacOS
• Linux - Ubuntu
• Linux - CentOS, Red Hat, and AWS Linux
• Windows

brew install redis # Install Redis
brew services start redis # Start Redis

brew install postgresql # Install Postgres
brew services start postgresql # Start Postgres

sudo apt install redis-server # Install & Start Redis

sudo apt install postgresql postgresql-contrib # Install & Start Postgres

sudo yum install redis # Install Redis
sudo systemctl start redis # Start Redis

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"
  },
  "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="sqlite://grouparoo_development.sqlite"
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: Configure Grouparoo & Install Plugins

Run grouparoo config to configure Grouparoo in your browser. You will be guided though the process of setting up everything you need, including installing new Plugins. Plugins are how the Grouparoo application can be extended to use new Sources and Destinations. Learn more here.

Running grouparoo config will start the config server which you can see by visiting 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.

Head over to the Configuration Guides to learn more about configuring Grouparoo. If you are having trouble installing dependencies, and you are using NPM v7 or later, please see this discussion for help

Step 4: Deploy and Run Grouparoo

Now that you have configured Grouparoo, you can commit your changes into git and deploy Grouparoo. There are many ways to run Grouparoo in production, and you can learn about them here, or choose to run Grouparoo via Grouparoo Cloud.