Installing the App

Step-by-step installation guide: clone repository, configure environment variables, install dependencies, set up OAuth credentials, and run locally.

This guide walks you through setting up and running the newsletter app locally.

Step 1: Clone the Repository

git clone https://github.com/humanity-developers/connect-sdk-examples.git
cd connect-sdk-examples/newsletter-app

Step 2: Install Dependencies

bun install

Step 3: Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Fill up the following configuration:

# ===========================================
# Humanity Protocol OAuth Configuration
# ===========================================
HUMANITY_CLIENT_ID=app_your_client_id_here
HUMANITY_CLIENT_SECRET=sk_your_client_secret_here
HUMANITY_REDIRECT_URI=http://localhost:3100/callback
# Environment: 'sandbox' or 'production'
HUMANITY_ENVIRONMENT=sandbox

# ===========================================
# MongoDB Configuration
# ===========================================
# For Docker (local):
MONGODB_URI=mongodb://localhost:27017

MONGODB_DB_NAME=newsletter-app

# ===========================================
# News API (GNews.io)
# Get your free API key at: <https://gnews.io/>
# ===========================================
NEWS_API_KEY=your_gnews_api_key_here
NEWS_API_BASE_URL=https://gnews.io/api/v4

# ===========================================
# App JWT Configuration
# Generate secret with: openssl rand -base64 32
# ===========================================
APP_JWT_SECRET=your_random_secret_here
APP_JWT_ISSUER=newsletter-app
APP_JWT_EXPIRES_IN=86400

# ===========================================
# Humanity App URL (for social connections redirect)
# ===========================================
NEXT_PUBLIC_HUMANITY_APP_URL=https://app.sandbox.humanity.org/

# ===========================================
# Optional: Cron Secret (for production only)
# ===========================================
CRON_SECRET=your_cron_secret_here

Step 4: Generate JWT Secret

Generate a secure random secret for JWT signing by running this command on terminal:

openssl rand -base64 32

Copy the output and paste it as your APP_JWT_SECRET value.

Step 5: Start MongoDB (if using Docker)

# Start Docker daemon (if not running)
sudo systemctl start docker

# Run MongoDB container
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Verify it's running
docker ps

Step 6: Run the Development Server

bun dev

Step 7: Test the OAuth Flow

1. Open http://localhost:3100 in your browser

2. Click "Sign in with Humanity Protocol"

3. Complete the OAuth authorization flow

4. You'll be redirected back to the app with your profile loaded

Step 8: Fetch News Articles

The news feed may be empty initially. Populate it by running in your terminal:

curl http://localhost:3100/api/cron/fetch-news

You should see output like:

{
  "success": true,
  "fetched": 30,
  "inserted": 29,
  "errors": [],
  "duration": 5977,
  "timestamp": "2026-02-02T13:36:01.261Z"
}

Step 9: Refresh and View Your Personalized Feed

Refresh the feed page in your browser. You should now see news articles personalized based on your social connections!