Installation Guide

This guide covers everything you need to install, configure, and deploy Connect World in both development and production environments.

System Requirements

Node.js

Version 20 or higher required

MongoDB

Version 5.0 or higher (local or cloud)

Package Manager

npm, yarn, pnpm, or bun

Git

For version control and deployment

Installation Steps

Install Node.js

Download and install Node.js 20+ from nodejs.orgVerify installation:

node --version  # Should be v20.0.0 or higher
npm --version

Clone Repository

Clone the Connect World repository:

git clone <your-repository-url>
cd connect-world

Install Dependencies

Choose your preferred package manager:

npm install

The project uses Next.js 16, React 19, and TypeScript 5. All dependencies are locked in package-lock.json.

Database Setup

Option 1: Local MongoDB

Install MongoDB

# Using Homebrew
brew tap mongodb/brew
brew install mongodb-community

Start MongoDB Service

brew services start mongodb-community

# Verify it's running
brew services list | grep mongodb

Verify Connection

Test MongoDB connection:

mongosh

# You should see:
# Current Mongosh Log ID: ...
# Connecting to: mongodb://127.0.0.1:27017
# Using MongoDB: 7.0.x

Create the database:

use connect-world
db.customers.insertOne({ test: true })
db.customers.deleteOne({ test: true })

Option 2: Docker MongoDB

# Run MongoDB in Docker
docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -v mongodb_data:/data/db \
  mongo:latest

MongoDB in Docker is perfect for development. For production, consider MongoDB Atlas for managed hosting.

Option 3: MongoDB Atlas (Cloud)

Create Atlas Account

Go to mongodb.com/cloud/atlas
Sign up for a free account
Create a new cluster (M0 free tier available)

Configure Database Access

Navigate to Database Access
Click Add New Database User
Create username and password
Grant Read and write to any database permission

Configure Network Access

Navigate to Network Access
Click Add IP Address
For development: Click Allow Access from Anywhere (0.0.0.0/0)
For production: Add your server’s IP address

Get Connection String

Click Connect on your cluster
Choose Connect your application
Copy the connection string:

mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/connect-world?retryWrites=true&w=majority

Environment Configuration

Create a .env.local file in the project root with all required variables:

Complete Configuration Template

.env.local

# ============================================
# DATABASE CONFIGURATION (REQUIRED)
# ============================================

# Local MongoDB
MONGDB_URI=mongodb://localhost:27017/connect-world

# Or MongoDB Atlas
# MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/connect-world?retryWrites=true&w=majority

# Or Docker MongoDB with auth
# MONGODB_URI=mongodb://admin:secret@localhost:27017/connect-world?authSource=admin

# ============================================
# STRIPE CONFIGURATION (REQUIRED)
# ============================================

# Get these from: https://dashboard.stripe.com/apikeys

# Secret key (server-side, starts with sk_test_ or sk_live_)
STRIPE_SECRET_KEY=sk_test_51xxxxx

# Publishable key (client-side, starts with pk_test_ or pk_live_)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51xxxxx

# ============================================
# PAYPAL CONFIGURATION (OPTIONAL)
# ============================================

# Get these from: https://developer.paypal.com/dashboard/

# Client ID (public, used in frontend)
NEXT_PUBLIC_PAYPAL_CLIENT_ID=AYourPayPalClientID123

# Client Secret (private, server-side only)
PAYPAL_CLIENT_SECRET=EYourPayPalClientSecret456

# API Base URL
# Sandbox for testing:
PAYPAL_BASE_URL=https://api-m.sandbox.paypal.com
# Production:
# PAYPAL_BASE_URL=https://api-m.paypal.com

# ============================================
# TMDB API CONFIGURATION (OPTIONAL)
# ============================================

# Get API key from: https://www.themoviedb.org/settings/api
# Required for content catalog display
NEXT_PUBLIC_TMDB_API_KEY=your_tmdb_api_key_here

# ============================================
# ENVIRONMENT
# ============================================

NODE_ENV=development

Environment Variables Reference

MONGODB_URI

Required - MongoDB connection string

From connection.ts

const MONGODB_URI = process.env.MONGODB_URI as string;

if (!MONGODB_URI) {
  throw new Error("Please define MONGODB_URI in .env.local");
}

The connection uses Mongoose with these options:

mongoose.connect(MONGODB_URI, {
  bufferCommands: false,
});

STRIPE_SECRET_KEY

Required - Stripe secret API key (server-side)

From stripe/route.ts

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

Used to:

Create payment intents
Process card payments
Handle 3D Secure authentication

Get from: dashboard.stripe.com/apikeys

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

Required - Stripe publishable key (client-side)Exposed to browser, safe to commit. Used to initialize Stripe Elements:

import { loadStripe } from '@stripe/stripe-js';
const stripe = await loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

NEXT_PUBLIC_PAYPAL_CLIENT_ID

Optional - PayPal client ID (public)

From paypal/create-order/route.ts

const credentials = Buffer.from(
  `${process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID}:${process.env.PAYPAL_CLIENT_SECRET}`
).toString('base64');

Used for PayPal authentication and order creation.

PAYPAL_CLIENT_SECRET

Optional - PayPal client secret (private)Server-side only. Combined with client ID for OAuth token generation:

async function getPayPalAccessToken(): Promise<string> {
  const credentials = Buffer.from(
    `${process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID}:${process.env.PAYPAL_CLIENT_SECRET}`
  ).toString('base64');
  // ... request access token
}

PAYPAL_BASE_URL

Optional - PayPal API endpoint

const PAYPAL_BASE = process.env.PAYPAL_BASE_URL ?? "https://api-m.sandbox.paypal.com";

Sandbox: https://api-m.sandbox.paypal.com (testing)
Production: https://api-m.paypal.com (live payments)

NEXT_PUBLIC_TMDB_API_KEY

Optional - The Movie Database API key

From tmdbService.ts

const TMDB_API_KEY = process.env.NEXT_PUBLIC_TMDB_API_KEY;
const tmdbClient = axios.create({
  baseURL: BASE_URL,
  params: { api_key: TMDB_API_KEY, language: "es-ES" },
});

Used to fetch:

Trending movies and TV shows
Now playing movies
Top rated series

App works without it, but catalog will be empty.

Payment Provider Setup

Stripe Configuration

Create Stripe Account

Sign up at stripe.com
Complete account verification
Enable test mode (toggle in dashboard)

Get API Keys

Go to dashboard.stripe.com/apikeys
Copy Publishable key (starts with pk_test_)
Reveal and copy Secret key (starts with sk_test_)
Add both to .env.local

Test Payment

Use Stripe test cards:

Card Number	Result
4242 4242 4242 4242	Success
4000 0025 0000 3155	Requires 3D Secure
4000 0000 0000 9995	Card declined

Expiry: Any future date
CVC: Any 3 digits
ZIP: Any 5 digits

PayPal Configuration (Optional)

Create Developer Account

Go to developer.paypal.com
Log in or create account
Navigate to Dashboard

Create Sandbox App

Click Apps & Credentials
Ensure Sandbox tab is selected
Click Create App
Name your app and click Create App

Get Credentials

Copy Client ID → NEXT_PUBLIC_PAYPAL_CLIENT_ID
Click Show under Secret → PAYPAL_CLIENT_SECRET
Set PAYPAL_BASE_URL=https://api-m.sandbox.paypal.com

Create Test Accounts

Go to Sandbox → Accounts
Create a Business account (merchant)
Create a Personal account (buyer)
Use the personal account email/password for test purchases

For production PayPal, switch to Live credentials and update PAYPAL_BASE_URL to https://api-m.paypal.com

TMDB API Setup (Optional)

Create TMDB Account

Sign up at themoviedb.org
Verify your email
Log in to your account

Request API Key

Go to Settings → API
Click Request an API Key
Choose Developer (free for non-commercial)
Fill out the application form
Accept terms and submit

Copy API Key

Copy your API Key (v3 auth)
Add to .env.local as NEXT_PUBLIC_TMDB_API_KEY

Verify Integration

The app uses these TMDB endpoints:

From tmdbService.ts

// Fetch trending content
export async function getTrendingAll(timeWindow: "day" | "week" = "week") {
  const { data } = await tmdbClient.get<TmdbResponse>(
    `/trending/all/${timeWindow}`
  );
  return data.results.slice(0, 10);
}

// Fetch now playing movies
export async function getNowPlayingMovies() {
  const { data } = await tmdbClient.get<TmdbResponse>(
    "/movie/now_playing"
  );
  return data.results.slice(0, 10);
}

// Fetch top rated series
export async function getTopRatedSeries() {
  const { data } = await tmdbClient.get<TmdbResponse>(
    "/tv/top_rated"
  );
  return data.results.slice(0, 5);
}

Running the Application

Development Mode

npm run dev

The app will start at http://localhost:3000

Next.js 16 uses Turbopack by default for faster development builds.

Production Build

Build Application

npm run build

This creates an optimized production build in .next/

Start Production Server

npm run start

Linting

npm run lint

The project uses ESLint with Next.js configuration:

From eslint.config.mjs

import { dirname } from "path";
import { fileURLToPath } from "url";
import { FlatCompat } from "@eslint/eslintrc";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const compat = new FlatCompat({
  baseDirectory: __dirname,
});

const eslintConfig = [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
];

export default eslintConfig;

Database Schema

Connect World uses two main collections:

Customers Collection

From CustomerModel.ts

export interface CustomerDbDoc extends Document {
  email: string;
  phone: string;
  name: string;
  created_at: Date;
  updated_at: Date;
}

const CustomerSchema = new Schema<CustomerDbDoc>(
  {
    email: { type: String, required: true, unique: true, lowercase: true },
    phone: { type: String, required: true },
    name:  { type: String, required: true },
  },
  {
    timestamps: { createdAt: "created_at", updatedAt: "updated_at" },
  }
);

Orders Collection

From OrderModel.ts

export interface OrderDbDoc extends Document {
  customer_id: string;
  plan_id: string;
  devices: number;
  months: number;
  amount: number;
  payment_method: "stripe" | "paypal";
  payment_receipt_id: string;
  status: "pending" | "completed" | "failed";
  activation_date: Date;
  expiration_date: Date;
  created_at: Date;
  updated_at: Date;
}

const OrderSchema = new Schema<OrderDbDoc>(
  {
    customer_id:        { type: String, required: true, index: true },
    plan_id:            { type: String, required: true },
    devices:            { type: Number, required: true },
    months:             { type: Number, required: true },
    amount:             { type: Number, required: true },
    payment_method:     { type: String, enum: ["stripe", "paypal"], required: true },
    payment_receipt_id: { type: String, required: true, unique: true },
    status:             { type: String, enum: ["pending", "completed", "failed"], default: "pending" },
    activation_date:    { type: Date, required: true },
    expiration_date:    { type: Date, required: true },
  },
  {
    timestamps: { createdAt: "created_at", updatedAt: "updated_at" },
  }
);

The schema uses snake_case for MongoDB fields following common NoSQL conventions, while the application layer uses camelCase.

Security Configuration

Connect World includes comprehensive security headers:

From next.config.ts

const securityHeaders = [
  { key: "X-Frame-Options", value: "DENY" },
  { key: "X-Content-Type-Options", value: "nosniff" },
  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
  {
    key: "Permissions-Policy",
    value: "camera=(), microphone=(), geolocation=(), payment=(self)",
  },
  { key: "X-XSS-Protection", value: "1; mode=block" },
  {
    key: "Strict-Transport-Security",
    value: "max-age=63072000; includeSubDomains; preload",
  },
  {
    key: "Content-Security-Policy",
    value: [
      "default-src 'self'",
      "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://js.stripe.com https://www.paypal.com https://www.sandbox.paypal.com",
      "style-src 'self' 'unsafe-inline'",
      "img-src 'self' data: blob: https://image.tmdb.org https://www.paypalobjects.com",
      "font-src 'self' data:",
      "connect-src 'self' https://api.stripe.com https://api-m.sandbox.paypal.com https://api-m.paypal.com https://api.themoviedb.org",
      "frame-src https://js.stripe.com https://hooks.stripe.com https://www.paypal.com https://www.sandbox.paypal.com",
    ].join("; "),
  },
];

Adjust CSP headers for your domain before production deployment.

Verification Checklist

Before deploying, verify all components:

Database Connection

# Test MongoDB connection
mongosh $MONGODB_URI

# Check collections
use connect-world
show collections

Environment Variables

# Verify all required vars are set
node -e "console.log({
  MONGODB_URI: !!process.env.MONGODB_URI,
  STRIPE_SECRET: !!process.env.STRIPE_SECRET_KEY,
  STRIPE_PUBLIC: !!process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
})"

Build Success

npm run build
# Should complete without errors

API Endpoints

# Start server
npm run dev

# Test health
curl http://localhost:3000

# Test TMDB
curl http://localhost:3000/api/tmdb

Payment Test

Navigate to http://localhost:3000
Select a plan
Use Stripe test card: 4242 4242 4242 4242
Complete checkout
Verify order in MongoDB:

mongosh
use connect-world
db.orders.find().pretty()

Troubleshooting

Module not found errors

Clear and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Port 3000 already in use

Change the port:

PORT=3001 npm run dev

Or kill the process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

MongoDB connection timeout

Check MongoDB is running:

# macOS
brew services list | grep mongodb

# Linux
sudo systemctl status mongod

# Docker
docker ps | grep mongo

Test connection:

mongosh mongodb://localhost:27017

Stripe webhook errors (production)

For production, set up Stripe webhooks:

Go to dashboard.stripe.com/webhooks
Add endpoint: https://yourdomain.com/api/webhooks/stripe
Select events: payment_intent.succeeded, payment_intent.payment_failed
Add webhook secret to .env.local

Next Steps

Quick Start

Test your installation with your first subscription

API Reference

Explore available endpoints and data models

Development

Learn the architecture and development workflow

Deployment

Deploy to Vercel, AWS, or your own infrastructure

Get Started

Core Features

Architecture

Integrations

Security

Installation

Installation Guide

System Requirements

Node.js

MongoDB

Package Manager

Git

Installation Steps

Database Setup

Option 1: Local MongoDB

Option 2: Docker MongoDB

Option 3: MongoDB Atlas (Cloud)

Environment Configuration

Complete Configuration Template

Environment Variables Reference

Payment Provider Setup

Stripe Configuration

PayPal Configuration (Optional)

TMDB API Setup (Optional)

Running the Application

Development Mode

Production Build

Linting

Database Schema

Customers Collection

Orders Collection

Security Configuration

Verification Checklist

Troubleshooting

Next Steps

Quick Start

API Reference

Development

Deployment

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Integrations

Security

​Installation Guide

​System Requirements

Node.js

MongoDB

Package Manager

Git

​Installation Steps

​Database Setup

​Option 1: Local MongoDB

​Option 2: Docker MongoDB

​Option 3: MongoDB Atlas (Cloud)

​Environment Configuration

​Complete Configuration Template

​Environment Variables Reference

​Payment Provider Setup

​Stripe Configuration

​PayPal Configuration (Optional)

​TMDB API Setup (Optional)

​Running the Application

​Development Mode

​Production Build

​Linting

​Database Schema

​Customers Collection

​Orders Collection

​Security Configuration

​Verification Checklist

​Troubleshooting

​Next Steps

Quick Start

API Reference

Development

Deployment

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Installation Steps

Database Setup

Option 1: Local MongoDB

Option 2: Docker MongoDB

Option 3: MongoDB Atlas (Cloud)

Environment Configuration

Complete Configuration Template

Environment Variables Reference

Payment Provider Setup

Stripe Configuration

PayPal Configuration (Optional)

TMDB API Setup (Optional)

Running the Application

Development Mode

Production Build

Linting

Database Schema

Customers Collection

Orders Collection

Security Configuration

Verification Checklist

Troubleshooting

Next Steps