Skip to main content

Installation Guide

Welcome! This guide walks you through installing and running humuus, an interactive educational platform built with Next.js (frontend) and Nakama (real-time backend). You’ll set up environment variables, install dependencies, and run everything locally.

warning

This repository is not public yet. Ask the humuus team for certain environment values.

Prerequisites​

  • Node.js v16+
  • pnpm (monorepo package manager)
  • Docker & Docker Compose (for Nakama & MinIO)
  • Git
tip

Don’t have pnpm yet? npm i -g pnpm

Clone the Repository​

git clone https://github.com/techagogics/humuus.git
cd humuus

Project Overview​

humuus is a Turborepo monorepo with web and backend apps:

humuus/
├── apps/
│   ├── nakama/             # Nakama server (TypeScript runtime)
│   │   ├── src/
│   │   │   ├── models/     # Data models
│   │   │   └── workshop/   # Workshop logic
│   └── web/                # Next.js frontend
│       ├── public/         # Static assets
│       └── src/
│           ├── app/        # Next.js app router
│           ├── components/ # React components
│           │   └── nodes/  # Workshop node components
│           ├── models/     # TypeScript interfaces
│           └── services/   # API services
└── documentation/          # TypeDoc documentation build

Environment Variables​

warning

Some values are internal to the humuus team (e.g., MinIO endpoints, resource paths, Nakama HTTP key). Request these before continuing.

1) apps/web/.env.local​

Create apps/web/.env.local (or copy from an example if available):

cp apps/web/.env.local.example apps/web/.env.local 2>/dev/null || true

Content:

# NAKAMA
NEXT_PUBLIC_NAKAMA_SERVER_PORT=7350
NEXT_PUBLIC_NAKAMA_USE_SSL=false # options: true || false
NEXT_PUBLIC_NAKAMA_SERVER_HOST=localhost # don't add 'http://'
NEXT_PUBLIC_RESOURCE_LOCATION= # ask humuus team or setup local container
NAKAMA_HTTP_KEY= # nakama http key for server-to-server functions

Notes

  • NEXT_PUBLIC_NAKAMA_USE_SSL: keep false for local dev unless TLS is configured.
  • NEXT_PUBLIC_RESOURCE_LOCATION: base path for workshop/storage resources (ask team or use your local MinIO path).
  • NAKAMA_HTTP_KEY: server key for secure server-to-server requests.

2) apps/nakama/.env​

Create apps/nakama/.env (or copy from an example if available):

cp apps/nakama/.env.example apps/nakama/.env 2>/dev/null || true

Content:

NAKAMA_GRPC_PORT=7349
NAKAMA_HTTP_PORT=7350
NAKAMA_CONSOLE_PORT=7351
POSTGRES_PORT=5332
MINIO_ADDRESS= # ask humuus team or setup local container

Notes

  • MINIO_ADDRESS should point to MinIO (e.g., localhost:9000 for local). Ask the team for the canonical value.

Install Dependencies​

From the repository root:

pnpm install

This installs dependencies across the monorepo (web, nakama, docs).

Run in Development​

From the repository root:

pnpm run dev
info

Ensure Docker is running. The Nakama container should start automatically as part of the dev workflow. If your setup requires running Docker manually, follow your team’s Docker Compose instructions.

When everything is up:

tip

If ports collide, adjust the values in your .env files and restart.

For more troubleshooting go to "help".

Configure User Account as Host​

:::Requirements:

Step-by-Step Guide​

1. Open Nakama Console​

Open your browser and navigate to:

http://localhost:7350

Enter credentials:

  • Username:
  • Password:

Note: For internal employees, take a look at the password manager for the private credentials.

2. Select Account​

  1. Click on "Accounts" in the left sidebar
  2. Select an existing account from the list

⚠️ Important: Do NOT select the system account with ID 00000000-0000-0000-0000-000000000000

  1. Click on the account to open the details

3. Activate Host Permission​

In the account detail screen:

  1. Click on the "Profile" section
  2. Search for "host" in the text field
  3. Set the value to true
  4. Enter a DisplayName (e.g., "John Doe")
  5. Click "Save"

JSON example for ´Host´ Setup:

{
  "host": true
}

4. Set Up Authentication​

  1. Click on the "Authentication" section
  2. Click on "Email"
  3. Enter an email address
  4. Enter a password
  5. Click "Save" again

5. Log In as Host​

Open the web app:

http://localhost:3000

Log in with the configured credentials (Step. 4)

After successful login, click on your Account Icon, top right corner, and press "Workshops". This will direct you to the Dashboard.

http://localhost:3000/host

Troubleshooting​

Problem: "No Access to Host Dashboard"​

Solution:

  1. Check in Nakama if "host": true is set
  2. Log out and log in again

Additional Notes​

Remove Host Rights​

To revoke host rights:

  1. Open Nakama Console
  2. Select account
  3. In the Profile section, set "host": false
  4. Save

Tech stack​

  • Frontend: Next.js, React, TypeScript
  • Backend: Nakama (TypeScript runtime)
  • Storage: MinIO
  • Auth: Device-based & email
  • Monorepo: Turborepo + pnpm

Verify the Setup​

  1. Open http://localhost:3000.
  2. Create/start a workshop or load an existing JSON.
  3. On another browser/device, join via the 4-digit code.
  4. Interact (e.g., submit a quiz) and confirm real-time updates.
tip

Upload workshop JSON via the storage interface at /StoragePush in the web app.