> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynkz.elipseday.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Firebase Firestore for Your Lynkz Instance

> Set up Firebase Firestore as the Lynkz database. Create a project, enable Firestore, configure security rules, and retrieve your credentials.

Lynkz uses Firebase Firestore — not Firebase Auth — as its sole database. Firestore stores your page data (links, themes, bio), server-side analytics, and access control records such as IP lockouts and magic tokens. You do not need to enable any other Firebase services.

<Steps>
  <Step title="Create a Firebase Project">
    Go to [console.firebase.google.com](https://console.firebase.google.com) and sign in with your Google account. Click **Add project**, give your project a name, and follow the prompts to finish creation. You can disable Google Analytics for the Firebase project — Lynkz tracks its own analytics independently.
  </Step>

  <Step title="Enable Firestore">
    Inside your new project, navigate to **Build → Firestore Database** in the left sidebar. Click **Create database**, select your preferred region (choose one close to your users), and when prompted for a security mode select **Start in production mode**. The default locked-down rules are fine for now — you'll replace them in the next step.
  </Step>

  <Step title="Set Firestore Rules">
    In the Firestore console, open the **Rules** tab and replace the existing content with the rules below, then click **Publish**.

    ```js theme={null}
    rules_version = '2';
    service cloud.firestore {
      match /databases/{database}/documents {
        match /pages/{username} {
          allow read: if true;
          allow write: if !('pinHash' in request.resource.data)
                       && !('email' in request.resource.data);
        }
        match /analytics/{username} {
          allow read: if false;
          allow write: if true;
        }
        match /analytics/{username}/daily/{day} {
          allow read: if false;
          allow write: if true;
        }
        match /lockouts/{id} { allow read, write: if false; }
        match /magic_tokens/{token} { allow read, write: if false; }
      }
    }
    ```

    These rules allow public reads of page data while blocking clients from writing sensitive fields such as `pinHash` and `email`. Analytics can be written from the browser but never read. Lockout and magic token records are fully server-side only.

    <Tip>
      You can also push your rules from the command line instead of copy-pasting in the console. Install the Firebase CLI (`npm install -g firebase-tools`), then run `firebase deploy --only firestore:rules` from your project root.
    </Tip>
  </Step>

  <Step title="Get Your Web App Config">
    Navigate to **Project Settings** (gear icon) **→ Your apps**. If you haven't added a web app yet, click **Add app** and choose the **Web** platform (`</>`). After registering the app, Firebase displays a config object like this:

    ```js theme={null}
    const firebaseConfig = {
      apiKey: "AIza...",
      authDomain: "your-project.firebaseapp.com",
      projectId: "your-project",
      storageBucket: "your-project.appspot.com",
      messagingSenderId: "123456789",
      appId: "1:123456789:web:abc123"
    };
    ```

    Copy each value into your `.env.local` file under the corresponding `NEXT_PUBLIC_FIREBASE_*` variable. See the [Environment Variables](/setup/environment-variables) reference for the full list.
  </Step>

  <Step title="Get Your Service Account Key">
    Still in **Project Settings**, open the **Service accounts** tab. Click **Generate new private key** and confirm the download. Firebase gives you a `.json` file containing your full service account credentials.

    Open the file, copy its entire contents, and set it as the value of `FIREBASE_SERVICE_ACCOUNT_KEY` in your Vercel environment variables. The value should be the raw JSON string — the entire object, including braces.

    <Warning>
      Your service account key grants full admin access to your Firestore database. Treat it like a password — never commit it to version control or paste it anywhere publicly visible. Store it exclusively as a Vercel environment variable (or equivalent secret store if you self-host). It should never reach the browser.
    </Warning>
  </Step>
</Steps>