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

# Quickstart

> From purchase to running application in nine steps.

<Warning>
  Change the default admin credentials before any production deployment. The seeded admin password is `Admin123!` and is the same for every scaffolded project.
</Warning>

<Steps>
  <Step title="Download the template package">
    After purchase you receive a download link via email. Download the `.nupkg` file to your machine. The file is named `AspFox.Templates.1.x.x.nupkg` (version number varies).

    Keep the file somewhere accessible — you will reference its path in the next step.
  </Step>

  <Step title="Install the template">
    From the directory where you saved the `.nupkg`, run:

    ```bash theme={null}
    dotnet new install ./AspFox.Templates.1.x.x.nupkg
    ```

    Replace `1.x.x` with the actual version in the filename. This registers the `aspfox` template in your local `dotnet new` catalog. Run it once per machine. To update to a newer version, download the new `.nupkg` and run this command again.
  </Step>

  <Step title="Scaffold your project">
    Replace `YourProjectName` with your actual project name (PascalCase, no spaces). This renames every namespace, file, and assembly reference automatically.

    ```bash theme={null}
    dotnet new aspfox -n YourProjectName
    ```

    Run this from whatever directory you want the project created in.

    Available scaffold options:

    | Option                   | Default             | Description                                |
    | ------------------------ | ------------------- | ------------------------------------------ |
    | `--AdminEmail`           | `admin@example.com` | Email address for the seeded admin account |
    | `--IncludeReactFrontend` | `true`              | Include the React + TypeScript frontend    |
    | `--IncludeTests`         | `true`              | Include the xUnit test project             |

    Example with options:

    ```bash theme={null}
    dotnet new aspfox -n Acme --AdminEmail admin@acme.com
    ```
  </Step>

  <Step title="Navigate to your project">
    ```bash theme={null}
    cd YourProjectName
    ```
  </Step>

  <Step title="Configure environment variables">
    ```bash theme={null}
    cp .env.example .env
    ```

    Open `.env` in your editor. At minimum, the following must be set before the application will start:

    * `DATABASE_URL` — filled in by Docker Compose if you use the default setup
    * `REDIS_URL` — same
    * `JWT_PRIVATE_KEY` and `JWT_PUBLIC_KEY` — see the next step

    For a first local run, Stripe and email variables can be placeholder values. Auth and tenant features work fully without them. Billing endpoints will return errors until Stripe is configured.

    See the full [Environment Variables](/configuration/environment-variables) reference for every variable.
  </Step>

  <Step title="Generate JWT RSA keys">
    AspFox uses RS256 (asymmetric) JWT signing. You need to generate a 4096-bit RSA key pair and base64-encode both the private and public keys.

    <CodeGroup>
      ```powershell PowerShell (Windows) theme={null}
      ssh-keygen -t rsa -b 4096 -m PEM -f jwt.key -N '""'
      [Convert]::ToBase64String([IO.File]::ReadAllBytes("jwt.key"))
      [Convert]::ToBase64String([IO.File]::ReadAllBytes("jwt.key.pub"))
      ```

      ```bash bash (macOS / Linux) theme={null}
      openssl genrsa -out private.pem 4096
      openssl rsa -in private.pem -pubout -out public.pem
      base64 -w 0 private.pem   # Linux  (-w 0 removes line breaks)
      base64 private.pem         # macOS
      ```
    </CodeGroup>

    Copy the base64 output of the private key into `.env` as `JWT_PRIVATE_KEY`, and the public key as `JWT_PUBLIC_KEY`. Both values are single long strings with no line breaks.

    <Note>
      Generate new keys for every environment. Do not reuse your local development keys in production.
    </Note>
  </Step>

  <Step title="Start services">
    ```bash theme={null}
    make up
    ```

    This runs Docker Compose with the development configuration. The first run downloads Docker images — expect 2–3 minutes. Subsequent starts take a few seconds.

    The following services start: PostgreSQL 15, Redis 7, the .NET API (with hot reload via `dotnet watch`), and the React frontend (with Vite HMR).
  </Step>

  <Step title="Apply migrations and seed the database">
    In a separate terminal (services must be running):

    ```bash theme={null}
    make migrate
    make seed
    ```

    `make migrate` applies all pending EF Core migrations to the PostgreSQL container. `make seed` creates the admin user and initial lookup data.
  </Step>

  <Step title="Open the application">
    | What               | URL                                                              |
    | ------------------ | ---------------------------------------------------------------- |
    | Frontend           | [http://localhost:5173](http://localhost:5173)                   |
    | API + Swagger      | [http://localhost:5000/swagger](http://localhost:5000/swagger)   |
    | Hangfire dashboard | [http://localhost:5000/hangfire](http://localhost:5000/hangfire) |

    Default admin credentials (seeded by `make seed`):

    * **Email:** the value of `--AdminEmail` (default: `admin@example.com`)
    * **Password:** `Admin123!`

    Log in at `http://localhost:5173` with the admin credentials. You will be prompted to create your first workspace (tenant) if one does not already exist.
  </Step>
</Steps>

<Note>
  The frontend runs at port 5173 (Vite dev server) and the backend at port 5000. Both must be running for the full application to work. The frontend proxies API requests to port 5000 automatically — you do not need to configure CORS for local development.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Configure Stripe" icon="credit-card" href="/configuration/stripe-setup">
    Set up Stripe test mode to develop billing features locally.
  </Card>

  <Card title="Configure Email" icon="envelope" href="/configuration/email-setup">
    Connect Resend to test transactional email locally.
  </Card>

  <Card title="Project Structure" icon="folder" href="/getting-started/project-structure">
    Understand the codebase layout before adding your first feature.
  </Card>

  <Card title="Adding a Feature" icon="plus" href="/guides/adding-a-feature">
    Complete walkthrough: domain entity to React page.
  </Card>
</CardGroup>