# Quick Start Guide

Get R2-Manager-Worker up and running in just a few minutes.

## 5-Minute Setup

### Step 1: Clone and Install (1 minute)

```bash
git clone https://github.com/neverinfamous/R2-Manager-Worker.git
cd R2-Manager-Worker
npm install
```

### Step 2: Prepare Configuration Files (1 minute)

```bash
cp .env.example .env
cp wrangler.toml.example wrangler.toml
```

### Step 3: Authenticate with Cloudflare (1 minute)

```bash
npx wrangler login
```

This opens a browser window for authentication. Follow the prompts.

### Step 4: Create Cloudflare Resources (2 minutes)

Create an R2 bucket:

```bash
npx wrangler r2 bucket create my-files
```

### Step 5: Update Configuration Files (1 minute)

Edit `wrangler.toml`:

```toml
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-files"
```

## Authentication Setup (10 minutes)

### Create GitHub OAuth App

1. Go to GitHub Settings → Developer Settings → [OAuth Apps](https://github.com/settings/developers)
2. Click **New OAuth App**
3. Fill in:
   - **Application name:** "R2 Manager"
   - **Homepage URL:** `https://yourteam.cloudflareaccess.com`
   - **Authorization callback URL:** `https://yourteam.cloudflareaccess.com/cdn-cgi/access/callback`
4. Click **Register application**
5. Copy **Client ID** and **Client Secret**

### Configure Cloudflare Access

1. Go to [Zero Trust Dashboard](https://one.dash.cloudflare.com/)
2. Navigate to **Settings** → **Authentication** → **Login methods**
3. Click **Add new** → **GitHub**
4. Paste your GitHub Client ID and Client Secret
5. Click **Save**

### Create Access Application

1. Go to **Access** → **Applications** → **Add an application** → **Self-hosted**
2. Enter:
   - **Application name:** "R2 Manager"
   - **Session Duration:** 24 hours
3. Click **Add public hostname**
4. Select your domain or use `workers.dev`
5. Click **Next**
6. Create Allow policy:
   - **Policy name:** "Allow authenticated users"
   - **Action:** Allow
   - **Include:** GitHub (select your identity provider)
7. Click **Save**

### Get Configuration Values

1. Go to **Access** → **Applications** → Select "R2 Manager"
2. On **Overview** tab, copy **Application Audience (AUD) Tag**
3. Go to **Settings** → **Custom Pages** to find your **Team Domain**

## Deploy Secrets (5 minutes)

Set each secret when prompted:

**Account ID** (from Cloudflare Dashboard):

```bash
npx wrangler secret put ACCOUNT_ID
```

**Cloudflare Email:**

```bash
npx wrangler secret put CF_EMAIL
```

**API Token** (create at https://dash.cloudflare.com/profile/api-tokens):

```bash
npx wrangler secret put API_KEY
```

**Team Domain** (format: `https://yourteam.cloudflareaccess.com`):

```bash
npx wrangler secret put TEAM_DOMAIN
```

**Application Audience (AUD) Tag:**

```bash
npx wrangler secret put POLICY_AUD
```

## Deploy (2 minutes)

Build the frontend:

```bash
npm run build
```

Deploy to Cloudflare:

```bash
npx wrangler deploy
```

Your app is now live! 🎉

## Access Your Application

- **Workers.dev URL:** `https://r2-manager-worker.<your-subdomain>.workers.dev`
- **Custom domain** (if configured): `https://your-domain.com`

## Next Steps

1. ✅ **Log in** with your GitHub account
2. 📦 **Create a new bucket** to test
3. 📤 **Upload a test file**
4. 📖 **Read the [Installation & Setup](Installation-&-Setup) guide** for detailed explanations

## Local Development

Want to develop locally? Start both servers:

**Terminal 1:**

```bash
npm run dev
```

**Terminal 2:**

```bash
npx wrangler dev
```

Then visit `http://localhost:5173`

**Note:** Authentication is disabled on localhost for easier development.

## Troubleshooting Quick Fixes

| Issue                | Solution                                                |
| -------------------- | ------------------------------------------------------- |
| Authentication fails | Check `TEAM_DOMAIN` includes `https://`                 |
| Bucket not found     | Verify `bucket_name` in `wrangler.toml` matches exactly |
| Deploy fails         | Run `npx wrangler login` again                          |
| Secrets not working  | Check: `npx wrangler secret list`                       |

## Common Questions

**Q: Do I need a custom domain?**  
A: No! Use the free `workers.dev` subdomain. You can add a custom domain later.

**Q: What's the cost?**  
A: Free tier is generous! Typically $0/month for small-to-medium usage.

**Q: Can I use a different identity provider?**  
A: Yes! Cloudflare Access supports many providers (Google, Azure AD, Okta, etc.).

**Q: How do I update my deployment?**  
A: Just run `npm run build && npx wrangler deploy` again.

---

**Need more details?** Check the [Installation & Setup](Installation-&-Setup) guide or [Troubleshooting](Troubleshooting) page.

**Ready to explore?** See the [API Reference](API-Reference) for available operations.