⚡ Zee-Index

Self-Hosted Google Drive Explorer, CMS & Streaming Platform

Transform your Google Drive into a professional file manager, media gallery, and streaming server.
Shared Drive management · Video Streaming · Password-Protected Folders · Share Links

📑 Table of Contents

🌟 Key Features

⚡ Performance & UI

🎬 Media & File Previews

🛡️ Security & Access Control

🗂️ Drive Management

🛠️ Admin Dashboard

🛠️ Tech Stack

🏗 Architecture Overview

flowchart TB
    subgraph CLIENT["🌐 Client Browser"]
        A["React 19 + Next.js 16\nApp Router · Zustand · TanStack Query"]
    end

    subgraph CADDY["🔒 Caddy Reverse Proxy"]
        B["Auto-HTTPS · Let's Encrypt\n:443 → :3000"]
    end

    subgraph APP["⚡ Zee-Index Application"]
        C["API Routes"]
        D["Middleware\nAuth · i18n · Rate Limit"]
        E["Server Components\nStreaming SSR"]
    end

    subgraph SERVICES["📦 Backend Services"]
        F[("🐘 PostgreSQL 16\nUsers · Shares\nActivity · Config")]
        G[("🔴 Redis 7\nCache · KV Store\nRate Limiting")]
        H["☁️ Google Drive API v3\nFiles · Streaming\nMetadata"]
    end

    CLIENT <-->|HTTPS| CADDY
    CADDY <--> APP
    C <--> F
    C <--> G
    C <--> H
    D --- C
    E --- C

    style CLIENT fill:#1a1a2e,stroke:#e94560,color:#fff
    style CADDY fill:#0f3460,stroke:#e94560,color:#fff
    style APP fill:#16213e,stroke:#0f3460,color:#fff
    style SERVICES fill:#1a1a2e,stroke:#533483,color:#fff

Live Demo: https://zee-index.duckdns.org

🚀 Getting Started

Prerequisites

🐳 Quick Start with Docker (Recommended)

The fastest way to get Zee-Index running with PostgreSQL, Redis, auto-HTTPS, all preconfigured:

# 1. Clone the repository
git clone https://github.com/ifauzeee/Zee-Index.git
cd Zee-Index

# 2. Copy environment template
cp .env.example .env

# 3. Edit .env with your credentials (see Environment Variables section)
# IMPORTANT: You must define your own ADMIN_EMAILS and ADMIN_PASSWORD here.
# There is no default password. You create it in this file.
nano .env

# 4. Build and start all services
docker compose up -d --build

# 5. Open http://localhost:3000 (or your domain)
#    Navigate to /setup to complete Google Drive configuration

Useful Docker commands:

# View logs
docker compose logs -f zee-index

# Restart after .env changes
docker compose up -d

# Rebuild after code changes
docker compose up -d --build

# Stop all services
docker compose down

# Stop and remove all data (⚠️ destructive)
docker compose down -v

💻 Local Development

For contributors or those who prefer local development with hot reload:

# 1. Clone and install
git clone https://github.com/ifauzeee/Zee-Index.git
cd Zee-Index
pnpm install

# 2. Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL for a local PostgreSQL instance

# 3. Setup database
pnpm prisma migrate deploy   # or: pnpm prisma db push

# 4. Start Redis (optional but recommended)
docker run -d --name zee-redis -p 6379:6379 redis:7-alpine

# 5. Start development server (with Turbopack)
pnpm dev

# 6. Open http://localhost:3000
#    Log in with the ADMIN_EMAILS and ADMIN_PASSWORD you set in .env

Development commands:

pnpm dev              # Start with Turbopack (fast)
pnpm dev:webpack      # Start with Webpack (fallback)
pnpm build            # Production build
pnpm typecheck        # TypeScript type checking
pnpm lint             # ESLint
pnpm format:check     # Prettier check
pnpm check:all        # Run all checks
pnpm test             # Unit tests (Vitest)
pnpm test:e2e         # E2E tests (Playwright)

☁️ Google Cloud Setup

⚙️ Environment Variables

Required Variables

Database & Cache

Optional Variables

Email Configuration (Optional)

# ==============================================================================
# ZEE-INDEX CONFIGURATION
# ==============================================================================

# 1. CORE
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET=""          # openssl rand -base64 32
SHARE_SECRET_KEY=""         # openssl rand -base64 32

ADMIN_EMAILS="[email protected]"
ADMIN_PASSWORD="your-secure-password"

# 2. GOOGLE DRIVE
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
GOOGLE_REFRESH_TOKEN=""
NEXT_PUBLIC_ROOT_FOLDER_ID=""
NEXT_PUBLIC_ROOT_FOLDER_NAME="Home"

# 3. DATABASE (Docker auto-configures DATABASE_URL)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=zee_index

# 4. LIMITS & MONITORING
STORAGE_LIMIT_GB=15
STORAGE_WARNING_THRESHOLD=0.90
CRON_SECRET="random-string"

# 5. BUILD
SKIP_ENV_VALIDATION=false

# 6. HTTPS (Optional)
# DUCKDNS_DOMAIN="your-subdomain"
# DUCKDNS_TOKEN="your-token"
# CADDY_SITE="your-subdomain.duckdns.org"

# 7. EMAIL (Optional)
# SMTP_HOST="smtp.gmail.com"
# SMTP_PORT="465"
# SMTP_USER="[email protected]"
# SMTP_PASS="your-app-password"
# EMAIL_FROM="Zee Index <[email protected]>"

# 8. EXTERNAL SERVICES (Optional)
# TMDB_API_KEY=""

📦 Deployment Guide

VPS / DigitalOcean

Zee-Index is optimized for deployment on low-resource VPS instances (1 CPU / 1 GB RAM):

# 1. SSH into your server
ssh root@your-server-ip

# 2. Install Docker
curl -fsSL https://get.docker.com | sh

# 3. Create a non-root user (recommended)
adduser zee && usermod -aG docker zee
su - zee

# 4. Clone and configure
git clone https://github.com/ifauzeee/Zee-Index.git
cd Zee-Index
cp .env.example .env
nano .env  # Configure all required variables

# 5. Deploy
docker compose up -d --build

# 6. Verify
docker compose ps        # All containers should be "healthy"
docker compose logs -f   # Watch startup logs

Resource usage (approximate):

Automatic HTTPS with DuckDNS + Caddy

The included docker-compose.yml has built-in support for free HTTPS:

1. Get a DuckDNS domain at duckdns.org
2. Add to .env:

   DUCKDNS_DOMAIN="your-subdomain"
   DUCKDNS_TOKEN="your-duckdns-token"
   CADDY_SITE="your-subdomain.duckdns.org"
   NEXTAUTH_URL="https://your-subdomain.duckdns.org"

3. Use the included Caddyfile:

   {$CADDY_SITE:localhost} {
     reverse_proxy zee-index:3000
   }

4. Deploy — Caddy automatically provisions SSL via Let's Encrypt

Other Platforms

🔐 Security

Authentication & Authorization

Role Hierarchy:

Security Headers & CSP

Zee-Index includes comprehensive security headers:

• Content-Security-Policy — Prevents XSS by restricting script/style/media sources
• Strict-Transport-Security — Forces HTTPS (63072000s / ~2 years)
• X-Frame-Options: DENY — Prevents clickjacking
• X-Content-Type-Options: nosniff — Prevents MIME sniffing
• Referrer-Policy — strict-origin-when-cross-origin
• Permissions-Policy — Disables camera, microphone, geolocation

📖 API Reference

Public Endpoints

Authenticated Endpoints

Admin Endpoints

🎬 TMDB Integration (Optional)

Enhance your media library with rich metadata from The Movie Database (TMDB):

1. Obtain an API key from themoviedb.org.
2. Add TMDB_API_KEY to your .env file.
3. Restart the application.
4. Open any video file — Zee-Index will automatically search for matches and display posters, ratings, and cast information.

⌨️ Keyboard Shortcuts

🌍 Internationalization (i18n)

Zee-Index supports multiple languages via next-intl:

Switching language (UI):

• Use the Language button in the header to open a dropdown and select your preferred language.
• Routes are locale-prefixed (e.g. /en/..., /id/..., /zh-TW/...).

Adding a new language:

1. Copy messages/en.json → messages/xx.json
2. Translate all strings
3. Add "xx" to the supported locales list in lib/i18n-config.ts (LOCALES)
4. Ensure the language file exists in messages/xx.json
5. Add "xx" to the locales array in middleware.ts:

   const intlMiddleware = createMiddleware({
     locales: ["en", "id", "xx"],
     defaultLocale: "en",
   });

📂 Project Structure

zee-index/
├── app/                          # Next.js App Router
│   ├── [locale]/                 # Internationalized routes
│   │   ├── (main)/               # Main layout (sidebar + content)
│   │   ├── admin/                # Admin dashboard
│   │   ├── login/                # Login page
│   │   └── setup/                # Setup wizard
│   └── api/                      # API Routes
│       ├── admin/                # Admin-only APIs
│       ├── auth/                 # NextAuth handlers
│       ├── download/             # File download & streaming
│       ├── files/                # File listing
│       ├── share/                # Share link APIs
│       └── cron/                 # Scheduled tasks
│
├── components/                   # React Components
│   ├── admin/                    # Admin dashboard UI
│   ├── file-browser/             # File listing, actions, modals
│   │   ├── share/                # Share modal components
│   │   └── details/              # Detail panel components
│   ├── file-details/             # File preview & player
│   │   └── video-player/         # Video overlays & controls
│   ├── layout/                   # Header, Sidebar, Footer
│   │   └── sidebar/              # Sidebar sub-components
│   ├── common/                   # Shared UI components
│   └── ui/                       # Radix-based primitives
│
├── lib/                          # Core Libraries
│   ├── drive/                    # Google Drive API client
│   ├── kv/                       # Redis/KV abstraction layer
│   │   ├── index.ts              # Factory + re-exports
│   │   ├── types.ts              # KVClient interface
│   │   ├── redis-kv.ts           # Redis implementation
│   │   └── memory-kv.ts          # In-memory fallback
│   ├── store/                    # Zustand state management
│   ├── services/                 # Business logic (download, etc.)
│   └── *.ts                      # Utils, auth, logger, ratelimit
│
├── hooks/                        # Custom React Hooks
├── types/                        # TypeScript definitions
├── messages/                     # i18n translations (en, id)
├── prisma/                       # Database schema & migrations
│   ├── schema.prisma
│   └── migrations/               # Prisma migration history
├── scripts/                      # Utility scripts
│   └── hash-password.sh          # bcrypt password hash generator
│
├── docker-compose.yml            # Production stack
├── Dockerfile                    # Multi-stage optimized build
├── Caddyfile                     # Reverse proxy config
├── middleware.ts                  # Auth, i18n, rate limiting
└── next.config.mjs               # Next.js + security headers

🧪 Testing

Unit Tests (Vitest)

pnpm test                  # Run all tests
pnpm test -- --watch       # Watch mode
pnpm test -- --coverage    # Coverage report

End-to-End Tests (Playwright)

npx playwright install     # Install browsers (first time)
pnpm test:e2e              # Run E2E tests
npx playwright test --ui   # Run with interactive UI
npx playwright show-report # View HTML report

⚠️ Troubleshooting & FAQ

For common questions such as "How do I get the admin password?" or "How do I set up the Google Root Folder?", please see our Frequently Asked Questions (FAQ).

# Check logs for errors
docker compose logs zee-index --tail 50

# Common causes:
# 1. Database not ready — increase start_period in healthcheck
# 2. Missing .env variables — check all required vars are set
# 3. Port conflict — ensure 3000, 5432, 6379 are free

# Build without cache
docker compose build --no-cache

# Check disk space
df -h

# Ensure SKIP_ENV_VALIDATION=true is set for builds without full .env

# Check migration status
docker compose exec zee-index npx prisma migrate status

# Force apply migration
docker compose exec zee-index npx prisma migrate deploy

# Reset database (⚠️ destructive)
docker compose exec zee-index npx prisma migrate reset

🤝 Contributing

Contributions are welcome! Here's how to get started:

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/Zee-Index.git
cd Zee-Index

# 2. Create a feature branch
git checkout -b feat/amazing-feature

# 3. Install and develop
pnpm install && pnpm dev

# 4. Run all checks before committing
pnpm check:all

# 5. Commit with conventional format
git commit -m "feat: add amazing feature"

# 6. Push and open a Pull Request
git push origin feat/amazing-feature

Commit Convention (Conventional Commits):

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) with an attribution requirement.

• ✅ Free to use, modify, and distribute
• ✅ Commercial use allowed
• ⚠️ Attribution required: display © 2025 Muhammad Ibnu Fauzi in your deployment
• ⚠️ Modified versions that are hosted must share source code
• ⚠️ Changes must be documented

See the LICENSE file for full details.

Contributors

🙏 Acknowledgments

Built with these amazing open-source projects:

• Next.js — The React framework
• VidStack — Video player components
• Radix UI — Accessible UI primitives
• TanStack — React Query & Virtual
• Framer Motion — Animation library
• Zustand — State management
• Prisma — Database ORM
• Lucide — Beautiful icons