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

# Quickstart

This guide helps you set up nums with Upstash Redis, run it locally, deploy to Vercel, and verify everything works end‑to‑end.

<Steps>
  <Step title="Fork and clone">
    ```bash theme={null}
    git clone https://github.com/advayc/nums.git
    cd nums
    ```

    <Info>
      You can also import the repo directly into Vercel and skip local cloning.
    </Info>
  </Step>

  <Step title="Create Redis (Upstash recommended)">
    * Visit [https://console.upstash.com/redis](https://console.upstash.com/redis)
    * Create a database and copy both:
      * the connection host (host:port or rediss\://…)
      * the password

    <Tip>
      If you provide both <code>UPSTASH\_REDIS\_URL</code> and <code>UPSTASH\_REDIS\_PASSWORD</code>, nums will build a proper <code>REDIS\_URL</code> automatically.
    </Tip>
  </Step>

  <Step title="Configure environment variables">
    Create a <code>.env</code> file in the repo root:

    ```env theme={null}
    # Required for /hit authorization (send via X-Auth-Token or ?token=)
    SECRET_TOKEN=YOUR_RANDOM_SECRET

    # Redis via Upstash (recommended)
    UPSTASH_REDIS_URL=your-upstash-host:port
    UPSTASH_REDIS_PASSWORD=your-password

    # Alternatively provide a full redis URL
    # REDIS_URL=rediss://default:password@host:port

    # Optional (local server only)
    PORT=8080
    REDIS_PREFIX=hits:
    FAIL_FAST_REDIS=0
    ```

    <Note>
      Only <b>/hit</b> requires a secret. Read endpoints (<code>/count</code>, <code>/count.txt</code>, <code>/badge</code>, <code>/badge.json</code>) are public.
    </Note>
  </Step>

  <Step title="Run locally">
    ```bash theme={null}
    go run ./cmd/server
    ```

    Verify endpoints:

    ```bash theme={null}
    # increment (requires your secret)
    curl -H "X-Auth-Token: $SECRET_TOKEN" "http://localhost:8080/hit?id=home"

    # read JSON and text
    curl "http://localhost:8080/count?id=home"
    curl "http://localhost:8080/count.txt?id=home"
    ```

    <Check>
      You should see a JSON response like <code>\{"id":"home","hits":1}</code> from /hit and a number from /count.txt.
    </Check>
  </Step>

  <Step title="Deploy to Vercel">
    1. Push your fork to GitHub.
    2. Import the repo in Vercel: [https://vercel.com/new](https://vercel.com/new)
    3. Add the same env vars in Project → Settings → Environment Variables.
    4. Deploy. Your URL will look like <code>https\://\<project>.vercel.app</code> (or your custom domain).

    <Warning>
      Never expose your secret token in client-side code. For client websites, route increment requests through a server function.
    </Warning>
  </Step>

  <Step title="Add a badge to your README">
    * Shields (recommended):

    ```markdown theme={null}
    ![hits](https://img.shields.io/endpoint?url=https%3A%2F%2F<project>.vercel.app%2Fbadge.json%3Fid%3Dhome%26label%3Dhits%26cacheSeconds%3D30)
    ```

    * Direct SVG (terminal style):

    ```markdown theme={null}
    ![hits](https://<project>.vercel.app/badge?id=home&style=terminal&label=hits)
    ```

    <Tip>
      <code>cacheSeconds</code> in <code>/badge.json</code> is clamped to 30–3600 seconds.
    </Tip>
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Troubleshooting">
    * 401 on /hit: check <code>SECRET\_TOKEN</code> in the header or <code>?token=</code>.
    * Count stuck at 0: call <code>/hit?id=…</code> at least once; verify Redis env vars.
    * Vercel envs: ensure variables are set for the right environment (Preview/Production).
  </Accordion>
</AccordionGroup>