# Installing the App

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

## **Step 1: Clone the Repository**

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

## **Step 2: Install Dependencies**

```bash
bun install
```

## **Step 3: Configure Environment Variables**

Create a `.env` file in the project root:

```bash
cp .env.example .env
```

Fill up the following configuration:

```
# ===========================================
# Humanity 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:

```bash
openssl rand -base64 32
```

Copy the output and paste it as your `APP_JWT_SECRET` value.

## **Step 5: Start MongoDB (if using Docker)**

```bash
# 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**

```bash
bun dev
```

## **Step 7: Test the OAuth Flow**

1. Open <http://localhost:3100> in your browser
2. Click **"Sign in with Humanity"**
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:

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

You should see output like:

```json
{
  "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!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humanity.org/developer-guides-and-tutorials/sdk-api-guides/personalized-newsletter-app-reference-implementation/installing-the-app.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.