Install on Ubuntu

note

While the following guide will show you how to install HuddleUp on a single server running Ubuntu, it is not required to do so exactly. There are different ways to install and serve HuddleUp. However, we will currently only document this approach.

This guide will show you how to install HuddleUp on a single server running Ubuntu. We will use PM2 for keeping our backend running and running the build process for the frontend.

Preparations

• Make sure you have shell access to the server and your user has sudo rights
• You need two domains pointing to the IP of the server, these can also be subdomains
  • One for the frontend (we'll use huddle.huddle-up.org)
  • One for the backend (we'll use api.hudde.huddle-up.org)

Install requirements

First, make sure all package mirrors and installed packages are up to date.

sudo apt update

sudo apt upgrade -y

Now, let's install the dependencies.

curl -fsSL https://deb.nodesource.com/setup_14.x | sudo bash -

sudo apt install -y nginx postgresql postgresql-contrib nodejs certbot python3-certbot-nginx

sudo npm install -g pm2@latest yarn

Configure PostgreSQL

Next, we will create a PostgreSQL admin user and another user for HuddleUp. We will use admin as the username for the administrator and huddleup for the application user. You can of course choose different ones, if you want to.

First switch to the PostgreSQL system user.

sudo -i -u postgres

Next, create the admin user. When prompted, choose the following answers:

• Name of role: admin
• Password: Choose a strong password and save it somewhere safe!
• Superuser? y

createuser --interactive -P

Repeat the process for the application user. When prompted, choose the following answers:

• Name of role: huddleup
• Password: Choose a strong password (not the same as admin) and save it somewhere safe!
• Superuser? n
• Allow to create databases? y
• Allow to create roles? n

We will finalize the database setup in a further step.

We're done with Postgres for now, so we will switch back to your main user.

exit

Create a system user

Next we will create a system group and user for HuddleUp.

First, create the system user group:

sudo addgroup huddleup

Next, create the system user. The following command will create a user named huddleup, with huddleup as its primary group, add it to the www-data group, create a home directory for it and set its default shell to bash.

sudo useradd -g huddleup -G www-data -m -s /usr/bin/bash huddleup

If you want to be able to login as the system user, set its password with the following command. Again, use a unique, strong password and store it somewhere safe.

sudo passwd huddleup

Setup the database

Now, we'll finish the database setup. The next two commands will create a database called huddleup and then enable the uuid extension, which is required by HuddleUp.

sudo -u huddleup createdb huddleup

# When prompted for a password, use the one assigned to the database admin user

psql -h localhost -d huddleup -U admin -W -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'

Download the application

Now it's time to download HuddleUp and prepare its environment.

First create a folder in /var to install the application in it and set huddleup as the owner of it.

sudo mkdir /var/huddleup && sudo chown huddleup:huddleup /var/huddleup/

Now, switch to the huddleup user and clone the HuddleUp repository.

sudo -i -u huddleup

cd /var/huddleup

git clone --depth 1 --branch v1.0 https://github.com/huddle-up/huddle-up.git

Next, we will install the package dependencies.

cd huddle-up

yarn && yarn bootstrap

Configure HuddleUp

Now it's time to configure HuddleUp. We'll just put some examples here, for more information on the configuration of HuddleUp, see here.

All configuration files are located in the config/ folder of the application. For this example, we'll use the public Jitsi Meet instance.

note

The domain and the OpenID Connect provider in this example do not exist. You will have to replace them with your own specific values.

Client

Create a .env file in the config/client folder of the application. You can duplicate the .env.example in that folder, or create new one.

/var/huddleup/huddle-up/config/client/.env

# == BASE ==

REACT_APP_HOST=https://huddle.huddle-up.org

REACT_APP_API_URI=https://api.huddle.huddle-up.org

# == i18n ==

REACT_APP_I18N_DEFAULT_LOCALE=de

REACT_APP_I18N_AVAILABLE_LOCALES="en,de"

# == AUTH ==

REACT_APP_HOST=https://huddle.huddle-up.org

REACT_APP_API_URI=https://api.huddle.huddle-up.org

REACT_APP_I18N_DEFAULT_LOCALE=en

REACT_APP_OIDC_CLIENT_ID=someclientidprovidedbytheprovider

REACT_APP_OIDC_CLIENT_SECRET=someclientsecretprovidedbytheprovider

REACT_APP_OIDC_ISSUER=some.openidconnectprovider.test

REACT_APP_OIDC_REDIRECT_URI=https://huddle.huddle-up.org/login/callback

REACT_APP_OIDC_PROVIDER_NAME=Email

REACT_APP_OIDC_PROVIDER_ICON=email

Backend

Create a .env file in the config/client folder of the application. You can duplicate the .env.example in that folder, or create new one. Treat the HU_AUTH_SECRET like a password and make sure it is strong enough.

/var/huddleup/huddle-up/config/api/.env

# == BASE ==

HU_PORT=4000

HU_HOST=https://api.huddle.huddle-up.org

# == DATABASE ==

HU_DB_USERNAME=huddleup

HU_DB_PASSWORD=huddleupdbuserpassword

HU_DB_DATABASE=huddleup

HU_DB_HOST=localhost

HU_DB_PORT=5432

# == INTERNAL AUTH ==

HU_AUTH_SECRET=JaqYL5rvacnpNy9uDV8muubcGE4pQNUS

# == EXTERNAL AUTH (OIDC) ==

HU_AUTH_OIDC_ISSUER_DOMAIN=some.openidconnectprovider.test

# This is identical to your client id used in the frontend

HU_AUTH_OIDC_AUDIENCE=someclientidprovidedbytheprovider

# == JITSI ==

HU_JITSI_HOST=https://meet.jit.si

Building the Application

After having written the configuration, we can build the application.

note

This process can take a while for the first time.

Folder: /var/huddleup/huddle-up

yarn build

Running migrations

Before we can start the backend for the first time, we have to create the database schema.

Folder: /var/huddleup/huddle-up

yarn migrate

Setup PM2

To keep the backend running, and start it up automatically if you reboot the system we will be using PM2. We have already installed it in the first step, so we only have to set it up.

We will use the ecosystem file feature of PM2 to declare the task in a easy to manage file. To do this, create a file in the parent directory of the application.

/var/huddleup/pm2.config.yaml

apps:

- script: /var/huddleup/huddle-up/apps/api/dist/main.js

name: 'api'

watch: true

Now we can start the backend for the first time!

pm2 start pm2.config.yaml

You can check for the status of the process with pm2 status and the huddle-up/logs logs folder for errors.

To make sure that PM2 starts HuddleUp on a server reboot, we'll add it to the startup processes. Run the following command and copy the output.

pm2 startup

Run the output as root and the automatic startup should be registered.

Setup Nginx

First, if you're still in the huddleup user session, exit it.

exit

For serving the client and forwarding requests to the backend, we will use Nginx. In a first step, we will setup the hosts for the two applications. Once these are set up, we'll setup HTTPS with Let's Encrypt.

Basic Configuration

Client Host

Create a new Nginx configuration for the frontend at /etc/nginx/sites-available/000-stage.huddle-up.org.conf with following content:

/etc/nginx/sites-available/000-stage.huddle-up.org.conf

server {

listen 80;

listen [::]:80;

root /var/huddleup/huddle-up/apps/client/build;

index index.html;

server_name huddle.huddle-up.org;

location / {

try_files $uri $uri/ /index.html =404;

}

}

Enable it by linking it into the sites-enabled folder and reloading nginx.

sudo ln -s /etc/nginx/sites-available/000-stage.huddle-up.org.conf /etc/nginx/sites-enabled/000-stage.huddle-up.org.conf

service nginx restart

Backend Host

We'll do the same for the backend at `

/etc/nginx/sites-available/000-api.stage.huddle-up.org.conf

upstream api_upstream {

server 127.0.0.1:4000;

keepalive 64;

}

server {

listen 80;

listen [::]:80;

server_name api.huddle.huddle-up.org;

location / {

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header Host $http_host;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

proxy_pass http://api_upstream/;

proxy_redirect off;

proxy_read_timeout 240s;

}

}

Enable it by linking it into the sites-enabled folder and reloading nginx.

sudo ln -s /etc/nginx/sites-available/000-api.stage.huddle-up.org.conf /etc/nginx/sites-enabled/000-api.stage.huddle-up.org.conf

sudo service nginx restart

Lets Encrypt

To use HTTPS for connecting to the applications, we'll setup SSL certificates with Let's encrypt. We can let certbot do the nginx configuration for us. When asked whether to always redirect, choose 'Yes'.

sudo certbot --nginx -d huddle.huddle-up.org

sudo certbot --nginx -d api.huddle.huddle-up.org

Finally, restart nginx for applying the changes.

sudo service nginx restart

And you're done! You should be able to use your HuddleUp installation now.