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
└── packages/               # Shared configs (ESLint, TypeScript, TypeDoc)

Environment Variables​

All variables live in one file at the repository root. There are no per-app .env files — pnpm install symlinks apps/web/.env.local to it, and the Docker stack reads it directly.

cp .env.example .env

.env.example documents every variable, including how to generate the secrets. For local development the defaults work; two values are worth a look:

  • NEXT_PUBLIC_RESOURCE_LOCATION — base URL for all workshop media, images, video and sound alike. The trailing slash is required. Ask the team for the shared endpoint, or point it at a local file server.
  • CREATE_TEST_USERS=true — seeds two host-capable accounts on boot, which saves you the manual setup described further down.
Editing .env later

apps/web/.env.local is a symlink, so Next.js picks changes up immediately. The containers read their values at start, so run docker compose -f docker-compose-dev.yaml up -d nakama after an edit. Only changes to apps/nakama/nkconfig.yml additionally need --build.

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:

The documentation site is not started by default

pnpm run dev brings up Postgres, Nakama and the web app. Docusaurus sits behind a compose profile because building it is by far the most expensive part of starting the stack — and a change to the root package.json invalidates its install layer, which then re-downloads every dependency.

pnpm run dev:docs     # http://localhost:3001
tip

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

For more troubleshooting go to "help".

Configure User Account as Host​

You may not need this

With CREATE_TEST_USERS=true in your .env, Nakama seeds two accounts on boot that already hold host rights — alice@example.com / AliceTestPass123! and bob@example.com / BobTestPass123! (see apps/nakama/src/neededAccounts.ts). Sign in with either and skip the rest of this section.

The manual route below is what you need for an account of your own, or on an environment where seeding is off.

Requirements

  • Docker containers must be running (pnpm run dev:services)
  • Nakama console reachable at http://localhost:7351
  • Web app running at http://localhost:3000
  • Console login: the values you set for NAKAMA_CONSOLE_USERNAME and NAKAMA_CONSOLE_PASSWORD in .env

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.