Setup Guide

Get up and running
in 15 minutes

From zero to a fully working multi-account Google Drive dashboard. No cloud accounts, no paid services — just your machine and your Google credentials.

Python 3.10+Node.js 18+Google Account(s)Git
01

Clone the Repository

Fork the repository on GitHub to get your own copy, then clone it locally.

Terminal
git clone https://github.com/saimon4u/GDriveGenie.git
cd GDriveGenie
02

Create Google Cloud Credentials

You only need one Google Cloud project and one credentials file — no matter how many Drive accounts you want to add. All accounts authenticate through the same OAuth client.

  1. 1Go to console.cloud.google.com and create a new project.
  2. 2Navigate to APIs & Services → Library, search for Google Drive API, and enable it.
  3. 3Go to APIs & Services → OAuth consent screen. Choose External, fill in any app name, and add all Google accounts you want to connect as test users (one email per line).
  4. 4Go to Credentials → Create Credentials → OAuth client ID. Choose Web application as the application type. Under Authorized redirect URIs, add http://localhost:8000/api/auth/callback.
  5. 5Download the JSON file. You'll place it in the next step.
Tip — Adding all your Google accounts as test users on the OAuth consent screen gives them long-lived refresh tokens — no 7-day expiry. You won't need to reconnect periodically.
03

Place Credentials in /config

Place the downloaded credentials file in the config/ folder at the project root, named exactly credentials.json.

config/ folder
config/
└── credentials.json   ← your single OAuth client file
Important — The config/ folder is intentionally excluded from Git — its contents are listed in .gitignore so your credentials are never accidentally committed. The folder itself is tracked as an empty placeholder (via .gitkeep), so it already exists after cloning. Just drop your downloaded JSON file inside it.
Note — This one file is reused for every Drive account you connect. Each account gets its own encrypted refresh token stored in the database.
04

Generate Secrets

Install Python dependencies, then run the setup script. It will prompt you for a dashboard PIN and write all secrets directly into the local database — no .env file needed.

Install dependencies
pip install -r backend/requirements.txt
Generate secrets
python backend/scripts/generate_secrets.py

What the script does

  • PIN hashHashes your PIN with bcrypt and stores it as dashboard_pin_hash
  • JWT secretGenerates a cryptographically random 32-byte secret for signing session tokens
  • Encryption keyGenerates a Fernet key (AES-128-CBC) for encrypting OAuth refresh tokens at rest
Note — All three secrets are stored in the app_config table inside backend/gdriveGenie.db (or the gdriveGenie_data Docker volume when running with Docker Compose). Re-run the script at any time to change your PIN — it will ask before overwriting.
05

Start the Backend

The backend is a FastAPI app served by Uvicorn. On startup it creates the database tables, runs migrations, and syncs file metadata from all connected Drive accounts.

From the project root
uvicorn backend.main:app --reload --port 8000
Tip — Verify it works by opening http://localhost:8000/docs — you should see the Swagger UI with all API routes.
06

Start the Frontend

The frontend is a Next.js (App Router) app. Install dependencies and start the dev server. It must run alongside the backend simultaneously.

Terminal 2
cd frontend
npm install
npm run dev

Open http://localhost:3000. The Next.js config rewrites all /api/* requests to http://localhost:8000/api/* automatically.

07

Connect Your First Drive Account

Each account must be authorized via Google OAuth once before GDriveGenie can access it.

  1. 1Navigate to http://localhost:3000/login and enter your PIN.
  2. 2Click Settings in the left sidebar.
  3. 3Click the Connect another account button in the top-right of the Settings page.
  4. 4Google will show the account chooser — select the Google account you want to add, then approve the Drive permission on the consent screen.
  5. 5You'll be redirected back to Settings. The new account card appears with its storage quota.
Note — OAuth refresh tokens are encrypted with Fernet (AES-128-CBC) before being stored in the database — they are never saved in plain text.
08

Add More Accounts

Adding another Drive account takes seconds — no file changes, no restart needed.

  1. 1Go to Settings and click Connect another account.
  2. 2Sign in with a different Google account on the OAuth screen.
  3. 3You're back in Settings — the new account card is live with its own quota bar.
  4. 4Done — your pool just grew by 15 GB.
Tip — Make sure each Google account you want to add is listed as a test user on the OAuth consent screen (Step 02). Otherwise Google will block the sign-in.

N × 15 GB

No hard limit on accounts. 10 accounts = 150 GB free.

Feature Reference

What's inside the dashboard

Overview
  • ›Stats cards — files, folders, storage, free space
  • ›Per-account storage bars
  • ›File type distribution
  • ›Recent files with thumbnails
Files
  • ›Upload (drag & drop or click)
  • ›Grid and list view toggle
  • ›Sort, filter, search
  • ›Folder navigation with breadcrumb
  • ›Inline rename, download, trash
  • ›Drag-to-folder side panel
Shared with Me
  • ›Files others shared with your accounts
  • ›Navigate into shared folders
  • ›Grid and list view
  • ›Sort by date / name / size
  • ›Download directly
Trash
  • ›All trashed files across accounts
  • ›Restore to Drive
  • ›Permanently delete
  • ›Grid and list view, search, sort
Analytics
  • ›Weekly upload activity chart
  • ›Storage by account (used vs free)
  • ›Files by type (donut chart)
  • ›Storage by type (horizontal bars)
Settings
  • ›Total pool summary
  • ›Per-account quota bars
  • ›Connect another account (OAuth)
  • ›Disconnect or remove accounts
  • ›Profile: display name, bio, avatar

FAQ

Frequently Asked Questions

Is my data safe?

Yes. GDriveGenie runs entirely on your local machine. Files are stored in your own Google Drive accounts. OAuth tokens are encrypted with AES-128 (Fernet) before being written to the local database.

How many accounts can I add?

There is no limit. Click "Connect another account" in Settings for each additional Google account. Each one adds its full storage quota to the pool. 10 free accounts = 150 GB.

What happens if an account is full?

GDriveGenie always routes to the account with the most free space. If all accounts are full, the upload fails with a 503 error. Add another account to fix it.

Can I access files I added directly in Google Drive?

Yes. Click Sync in the Files page. GDriveGenie syncs only metadata — not file content — so it's fast.

Can I move files between accounts?

Within one account, drag any file and drop it into a folder from the slide-in panel. Cross-account moves are not supported — the Drive API does not allow transferring file ownership.

Does it work on Windows / Mac / Linux?

Yes. Python and Node.js are both cross-platform.

Can I run it with Docker?

Yes. Each service has its own Dockerfile (backend/Dockerfile, frontend/Dockerfile). Drop your credentials.json into the config/ folder, then: (1) docker compose build, (2) docker compose run --rm backend python scripts/generate_secrets.py — enter a PIN when prompted, (3) docker compose up -d. The database lives in the gdriveGenie_data named volume and survives rebuilds.

Can I expose it on the internet?

GDriveGenie is designed for local/self-hosted use. If you put it behind a reverse proxy (nginx, Caddy) with HTTPS, you must update FRONTEND_URL to your public frontend URL, BACKEND_URL to your public backend URL, and add the new callback URL (BACKEND_URL + /api/auth/callback) to your Google Cloud Console authorized redirect URIs.

Troubleshooting

Common Issues

!Backend fails to start — config key missing

Run python backend/scripts/generate_secrets.py (local) or docker compose run --rm backend python scripts/generate_secrets.py (Docker). The script creates the app_config table and inserts the three required keys.

!OAuth callback returns 400 invalid_request (Docker)

The BACKEND_URL environment variable must match the URL registered in Google Cloud Console. By default it is http://localhost:8000. If your backend is on a different host or port, update BACKEND_URL in docker-compose.yml and add the new callback URL (BACKEND_URL + /api/auth/callback) to your authorized redirect URIs.

!OAuth callback returns an error (local)

Check that the authorized redirect URI in Google Cloud Console is exactly http://localhost:8000/api/auth/callback. Also confirm the Google account you're signing in with is added as a test user on the OAuth consent screen.

!Files don't appear after uploading directly in Drive

GDriveGenie doesn't watch Drive in real time. Click the Sync button in the Files page to pull in new files.

!Upload fails with 503

All connected accounts are full. Go to Settings, click "Connect another account", and authorize a new Google account.

!Account shows Disconnected after restart

The refresh token may have been revoked by Google. Go to Settings and reconnect via OAuth.

!CORS error in the browser

Ensure both servers are running — backend on :8000, frontend on :3000. The Next.js dev proxy handles /api/* rewrites automatically. For Docker, check that both containers started with docker compose ps.

Ready?

Open the dashboard and start managing your storage pool.

Open DashboardBack to Home

GDriveGenie is free and open source. View on GitHub.