JUNOHUB

JUNOHUB is a Next.js application that powers an admin and supplier portal with:

• Authentication and multi-factor auth
• Gmail integration for support tickets (Juno Engine)
• Shopify integration for orders, products, and inventory
• Knowledge base and FAQ management
• Admin dashboards for stores, suppliers, and email events

The frontend and backend are implemented in a single Next.js App Router project.

---

Tech Stack

• Framework: Next.js (App Router, TypeScript)
• UI: React + modern Tailwind-style components
• Auth: NextAuth
• Database: PostgreSQL (Prisma ORM)
• Background / Integrations:
  • Gmail APIs (via OAuth)
  • Shopify APIs
  • AWS Bedrock for embeddings and chat (Titan Text Embeddings V2 + Claude 3 Haiku)
• Deployment: Docker + GitHub Actions → AWS EC2

---

Local Development

1. Install dependencies

npm install

2. Create .env

Copy .env.example (or the variables listed below) into a local .env file and fill in your own values:

• DATABASE_URL
• NEXTAUTH_SECRET
• NEXTAUTH_URL
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• SMTP_HOST
• SMTP_PORT
• SMTP_SECURE
• SMTP_USER
• SMTP_PASSWORD
• AWS_ACCESS_KEY_ID (for AWS Bedrock)
• AWS_SECRET_ACCESS_KEY (for AWS Bedrock)
• AWS_REGION (default: us-east-1)
• ADMIN_EMAIL
• ADMIN_PASSWORD

Never commit real secrets; .env* files are ignored by git.

3. Run the dev server

npm run dev

Visit http://localhost:3000 in your browser.

---

Docker

The project can be run via Docker using the provided Dockerfile and docker-compose.yml.

Typical pattern:

docker compose up -d --build

Make sure your .env is present next to the app code so the container can read it.

---

CI/CD on AWS EC2

This repo includes a GitHub Actions workflow at .github/workflows/deploy-ec2.yml that:

1. Runs on pushes to the main branch.
2. Installs dependencies and builds the Next.js app.
3. SSHes into an EC2 instance.
4. Writes an .env file on the EC2 instance from a single GitHub secret EC2_ENV.
5. Uses docker compose / docker-compose to build and run the app.
6. Performs a health check and automatically rolls back to the previous commit if the deployment or health check fails.

Required GitHub Secrets

Set the following secrets in GitHub → Settings → Secrets and variables → Actions:

• EC2_HOST – public IP or DNS of the EC2 instance.
• EC2_USER – SSH user (e.g. ubuntu).
• EC2_SSH_KEY – private SSH key for that user.
• EC2_SSH_PORT – (optional) port, defaults to 22 if not set.
• EC2_ENV – multi-line secret containing the full contents of the .env file used in production.
  This is written to .env on the server during deployment.

Deployment Flow

• Push to main.
• GitHub Actions:
  • Builds the app.
  • Connects to EC2.
  • Writes .env from EC2_ENV.
  • Runs docker compose up -d --build.
  • Hits the health check URL (by default http://localhost:3000/api/health).
• If the health check fails, the workflow:
  • Resets the repo on EC2 to the previous commit.
  • Re-runs docker compose up -d --build.

This gives you a sharp deployment with an automatic rollback path.

---

AWS Bedrock Setup

The knowledge base feature uses AWS Bedrock for AI-powered embeddings and chat completion.

Prerequisites

1. AWS Account: Create an account at https://aws.amazon.com/
2. Enable Bedrock Access:
   • Go to https://console.aws.amazon.com/bedrock/
   • Navigate to "Model access" in the left sidebar
   • Request access to:
     • Amazon Titan Text Embeddings V2 (for embeddings)
     • Anthropic Claude 3 Haiku (for chat completion)
   • Wait for approval (usually instant for Titan, may take a few hours for Claude)

IAM Setup

Create an IAM user or role with Bedrock permissions:

1. Go to IAM Console → Users (or Roles)
2. Create a new user/role or select existing
3. Attach the following policy (or create a custom policy):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel"],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0",
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
      ]
    }
  ]
}

4. Create Access Keys (for IAM user):
   • Go to Security credentials tab
   • Click "Create access key"
   • Choose "Application running outside AWS" or "EC2" depending on your deployment
   • Copy the Access Key ID and Secret Access Key
   • Add these to your .env file

Environment Variables

Add to your .env file:

AWS_ACCESS_KEY_ID="your-access-key-id"
AWS_SECRET_ACCESS_KEY="your-secret-access-key"
AWS_REGION="us-east-1"  # or your preferred region

Database Migration

After setting up AWS Bedrock, you need to migrate existing embeddings:

1. Run the database migration to change embedding dimensions from 1536 to 1024:

   npx prisma migrate deploy
   

2. Re-embed existing knowledge base data:

   npm run re-embed-knowledge-base
   

   This script will:

   • Read all existing KnowledgeChunk records
   • Generate new 1024-dimension embeddings using Bedrock Titan V2
   • Update the database with new embeddings
   • Process in batches to avoid rate limiting

Models Used

• Embeddings: Amazon Titan Text Embeddings V2 (amazon.titan-embed-text-v2:0)

  • Output dimension: 1024 (configurable: 256, 512, or 1024)
  • Used for: FAQ embeddings, document chunk embeddings, query embeddings

• Chat: Anthropic Claude 3 Haiku (anthropic.claude-3-haiku-20240307-v1:0)

  • Used for: RAG (Retrieval-Augmented Generation) query responses
  • Fast and cost-effective for knowledge base Q&A

Optional: Override Models

You can override the default models via environment variables:

BEDROCK_EMBEDDING_MODEL="amazon.titan-embed-text-v2:0"
BEDROCK_CHAT_MODEL="anthropic.claude-3-haiku-20240307-v1:0"

Prisma:

If you want to visualize the database:

export DATABASE_URL='<YOUR_DB_URL>'
npx prisma studio

Troubleshooting

• "Access Denied" errors: Ensure Bedrock model access is enabled in AWS Console
• "Invalid credentials": Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are correct
• "Model not found": Check that you've requested access to the models in Bedrock Console
• Re-embedding fails: Ensure AWS credentials are set and Bedrock access is enabled

---

License

Private / All rights reserved unless explicitly stated otherwise.