---
title: "Local setup"
description: "Get both applications running on your machine, in the order their pieces depend on each other."
canonical_url: "https://nuxtstart.com/docs/getting-started/local-setup"
---

> Index of every page on this site: [llms.txt](https://nuxtstart.com/llms.txt)

By the end of this page you have two applications running on your machine: the public website at
`http://site.<slug>.localhost`, and the signed-in product at `http://web.<slug>.localhost`. The
product talks to a Postgres database in Docker, and the email it sends lands in a local inbox
instead of a real one. Nothing here deploys anything.

This is stage 1, and `local` is the only Runtime Context it sets up.
[Deploying development](https://nuxtstart.com/docs/getting-started/deploying-development) and
[Adding pull request previews](https://nuxtstart.com/docs/getting-started/adding-pull-request-previews) come next, each on
its own and in either order. [Adding staging](https://nuxtstart.com/docs/getting-started/adding-staging) adds an optional
pre-production context, and [Going to production](https://nuxtstart.com/docs/getting-started/going-to-production) comes
last, once the application and its name are final.

Work through the steps in order. Each one depends on the one before it, and the errors you get from
skipping ahead name a missing value rather than the step you skipped.

Set aside an hour the first time. Most of it is creating accounts, not writing code.

## Prerequisites

<table>
<thead>
  <tr>
    <th>
      You need
    </th>
    
    <th>
      Where the version comes from
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Node.js
    </td>
    
    <td>
      The <code>
        devEngines.runtime
      </code>
      
       field in the root <code>
        package.json
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      pnpm
    </td>
    
    <td>
      The <code>
        devEngines.packageManager
      </code>
      
       field in the root <code>
        package.json
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Git
    </td>
    
    <td>
      Any recent version
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://cli.github.com" rel="nofollow">
        <code>
          gh
        </code>
      </a>
      
      , signed in with <code>
        gh auth login
      </code>
    </td>
    
    <td>
      Any recent version
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://github.com/koalaman/shellcheck#installing" rel="nofollow">
        ShellCheck
      </a>
    </td>
    
    <td>
      The <code>
        SHELLCHECK_VERSION
      </code>
      
       in the <code>
        Lint shell scripts and workflows
      </code>
      
       step of <code>
        .github/workflows/deploy.yml
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://github.com/rhysd/actionlint/blob/main/docs/install.md" rel="nofollow">
        actionlint
      </a>
    </td>
    
    <td>
      The <code>
        ACTIONLINT_VERSION
      </code>
      
       in the <code>
        Lint shell scripts and workflows
      </code>
      
       step of <code>
        .github/workflows/deploy.yml
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://orbstack.dev" rel="nofollow">
        OrbStack
      </a>
      
       on macOS, or Docker Engine on Linux
    </td>
    
    <td>
      Any recent version. Runs Postgres and the local mail inbox
    </td>
  </tr>
  
  <tr>
    <td>
      An <a href="https://infisical.com" rel="nofollow">
        Infisical
      </a>
      
       account
    </td>
    
    <td>
      Free plan. Holds your credentials
    </td>
  </tr>
</tbody>
</table>

On Linux, the local proxy needs port 80 without root. Allow it with
`sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80`, and write the same setting to a file in
`/etc/sysctl.d/` to keep it after a reboot. Linux also has to resolve `*.localhost` to loopback,
which `getent hosts web.x.localhost` checks. If it prints nothing, enable systemd-resolved, or
install libnss-myhostname and add `myhostname` to the hosts line of `/etc/nsswitch.conf`.

Social sign-in and payments also need a Google Cloud project, a GitHub OAuth app, and a
[Polar](https://polar.sh) sandbox account. You can skip any of the three today and add it later —
the step below on which features you're wiring up says what to put in the meantime. Locally, only
GitHub sign-in works: Google refuses local redirect URIs, so you test it once `development` deploys.

<steps level="3">

### Get the code

Your project starts from NuxtStart's `published` branch, the Published Tree: NuxtStart's source
with its own values and migration history removed. Don't fork NuxtStart or copy its default branch —
both hand you NuxtStart's `development`, which carries them.

Create an empty repository and pull `published` into its `development` branch:

```shell
# Empty on purpose: a README or license commit makes the first push fail
gh repo create <your-account>/<your-repo> --private

mkdir <your-repo> && cd <your-repo>
git init --initial-branch=development
git remote add origin https://github.com/<your-account>/<your-repo>.git
git remote add nuxtstart https://github.com/NuxtStart/NuxtStart.git
git pull nuxtstart published
git push --set-upstream origin development
```

The `nuxtstart` remote is how you pull NuxtStart's later changes — see
[Getting updates](https://nuxtstart.com/docs/getting-started/getting-updates).

**Everything on this page, and every deploy stage before production, happens on development.**
It's your repository's default branch because it's the first one you push, and it's the branch that
gives you a live URL.

A push is safe. Until your repository holds a Cloudflare API token, the deploy gate skips every
deploy and the run stays green.
[Connect the repository to Cloudflare](https://nuxtstart.com/docs/getting-started/deploying-development#connect-the-repository-to-cloudflare)
adds the token, and from then on a Runtime Context with an empty value fails its run, naming the
key. See [When a deploy is skipped](https://nuxtstart.com/docs/deployment/pipeline#when-a-deploy-is-skipped).

### Name your project

Your copy ships with these values empty in `.env.project.schema`, at the root of the repository.
Both applications read this file, and each value is required, so neither application installs or
runs on your machine until every one is set.

```env [.env.project.schema]
PROJECT_SLUG=acme
PROJECT_DISPLAY_NAME=Acme
PROJECT_DESCRIPTION="A CRM for small agencies, with pipelines, invoicing and client portals."
PROJECT_ZONE=acme.com
```

`PROJECT_SLUG` is the lowercase name inside every Worker, bucket, and database you'll create, and
its type rejects a slug that can't become one —
[Project identity](https://nuxtstart.com/docs/reference/project-identity#the-values-you-set) has the shape.
`PROJECT_DISPLAY_NAME` appears in page titles, transactional email, and social images.
`PROJECT_DESCRIPTION` is one sentence saying what your product is, in at most 160 characters. It
becomes the website's meta description and the summary at the top of its `llms.txt`.
`PROJECT_ZONE` is the DNS zone you own; your sending domains hang off it.

There's one more item, `PROJECT_DOMAIN`, and you can leave it alone for now. It defaults to your
zone, and only production reads it. [Project identity](https://nuxtstart.com/docs/reference/project-identity) is the full
picture — what derives from these, and what stays yours to write.

### Decide which features you're wiring up today

Email and password sign-in, the database, and transactional email need no provider account. Social
sign-in and payments do, and each one is a layer you can leave unconfigured for now:

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      Layer
    </th>
    
    <th>
      Keys it asks for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Google sign-in
    </td>
    
    <td>
      <code>
        @app/layer-auth
      </code>
    </td>
    
    <td>
      <code>
        GOOGLE_CLIENT_ID
      </code>
      
      , <code>
        GOOGLE_CLIENT_SECRET
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      GitHub sign-in
    </td>
    
    <td>
      <code>
        @app/layer-auth
      </code>
    </td>
    
    <td>
      <code>
        GITHUB_CLIENT_ID
      </code>
      
      , <code>
        GITHUB_CLIENT_SECRET
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Payments
    </td>
    
    <td>
      <code>
        @app/layer-payments
      </code>
    </td>
    
    <td>
      <code>
        POLAR_ACCESS_TOKEN
      </code>
      
      , <code>
        POLAR_WEBHOOK_SECRET
      </code>
    </td>
  </tr>
</tbody>
</table>

Every key is required, so put a stand-in such as `unused` in the ones you're skipping. The two later
steps say which file or folder each key goes in. `apps/web` starts either way, and only the feature
that reads the key fails when you first use it — the Google button, or a checkout.

A stand-in deploys like any other value, so the feature stays broken in every context you deploy it
to. Add the real values whenever you're ready with
[Set up sign-in and payments](https://nuxtstart.com/docs/configuration/provider-accounts).

### Set up your secret store

Both applications read their credentials from Infisical, and neither installs nor starts until it
can. Follow [Set up your secret store](https://nuxtstart.com/docs/configuration/secret-store), then come back here.

You're ready to continue when you have:

- Your own project ID in `apps/web/.env.infisical` and `apps/site/.env.infisical`
- A machine identity's client ID and secret in `apps/web/.env.local` and `apps/site/.env.local`
- The `development` environment's `/local` folder filled in for the `apps/web` project

### Fill in the values that are yours

The values that belonged to NuxtStart ship empty in your copy, and each one is required. These are
the ones you can choose now, so put them in the committed development files:

```env [apps/web/.env.development]
GOOGLE_CLIENT_ID=<your Google client ID>
GITHUB_CLIENT_ID=<your GitHub client ID>
```

```env [apps/site/.env.development]
NUXT_PUBLIC_CONTACT_EMAIL=hello@example.com
```

That's a short list because the Worker name, the bucket, the database, and the sending domain aren't
in these files at all. They're built from the values you set above, so renaming your project
renames all of them. [Project identity](https://nuxtstart.com/docs/reference/project-identity) lists which names derive
and which stay yours.

Your sending domain is one of the derived ones, `<slug>-<app>-local.<zone>` while you work locally.
Mailpit catches that mail instead of delivering it, so nothing has to be onboarded yet.
[Email will not send until you onboard a domain](https://nuxtstart.com/docs/getting-started/deploying-development#email-will-not-send-until-you-onboard-a-domain)
covers onboarding the deployed ones for real delivery.

Skipping Google or GitHub sign-in? Put your stand-in in that provider's client ID.

Leave the empty origins in these files alone. They're deployed origins, yours to write at the step
that pushes `development`, and the next step gives your machine its own.

### Create your local origin overrides

`.env.development.local` overrides keys that `.env.development` already sets.
[Environment values](https://nuxtstart.com/docs/reference/environment-values#which-file-wins) explains the split. Create
one per application, with your slug in place of `<slug>`:

```env [apps/web/.env.development.local]
NUXT_PUBLIC_APP_BASE_URL=http://web.<slug>.localhost
NUXT_PUBLIC_APP_WEBSITE_BASE_URL=http://site.<slug>.localhost
```

```env [apps/site/.env.development.local]
NUXT_PUBLIC_APP_BASE_URL=http://site.<slug>.localhost
```

These serve the commands that don't start a server, such as `pnpm install`, `db:generate` and
`typecheck`, which otherwise stop on the empty origins. The dev commands hand each application its
own origins, its database, and its inbox in process env, which outranks every env file, so a
worktree still gets its own URLs.

### Install dependencies

```shell
pnpm install
```

This also prepares both applications, which generates the types your editor needs. Preparing
resolves every value the steps above set, so it stops on any that's still missing and names it.
[Troubleshooting](#troubleshooting) says where each one goes.

### Generate your first migration

Your copy ships the database schema and no migration history.
[Migration publication](https://nuxtstart.com/docs/reference/migration-publication) explains why.

```shell
cd apps/web
pnpm db:generate
```

Commit what it writes. You own that history from here. The dev server applies pending migrations when
it starts, so there's no separate apply step locally.

### Run both applications

Make sure OrbStack, or Docker Engine on Linux, is running. Then use two terminals, one command
each. There's no root `dev` command, because it would have to choose one of the two applications
for you.

```shell
pnpm dev:site
pnpm dev:web
```

Before either server starts, the command starts this checkout's Postgres and
[Mailpit](https://mailpit.axllent.org) inbox in Docker and waits until they're ready. The first
run downloads both images. Each command prints the database's connection string, the inbox's
address, and both applications' URLs, whichever one it starts. On macOS, `pnpm dev:web` prints this:

```text
Postgres  postgres://postgres:postgres@postgres.<slug>.orb.local:5432/web
Mailpit   https://mailpit.<slug>.orb.local
Web       http://web.<slug>.localhost
Site      http://site.<slug>.localhost
```

The applications are served through [portless](https://github.com/vercel-labs/portless), a local
proxy on port 80, so open the printed URL of the application you started rather than a port.

Mailpit catches every email the product sends, so nothing leaves your machine. The containers keep
running after you stop the server. [Local services](https://nuxtstart.com/docs/getting-started/technical-details#local-services)
covers worktrees and how to stop or remove them.

### Check that it worked

1. Sign up at `http://web.<slug>.localhost/auth/sign-up` with your own address, such as `<user>@<org>.com`.
Nothing seeds a local account.
2. Open the Mailpit address the command printed and read the verification email.
3. Open `http://site.<slug>.localhost/docs` and confirm the website serves this page.

</steps>

## Optional: receive Polar webhooks locally

Skip this unless you're testing payment events after checkout, such as renewals, cancellations, or
refunds. Everything else runs without it. Polar delivers the `local` webhook through
[Tailscale Funnel](https://tailscale.com/kb/1223/funnel), which needs a one-time setup:

1. Install [Tailscale](https://tailscale.com/download). The free plan includes Funnel. Make sure `tailscale` runs in a terminal. On macOS, install the app's CLI from its Settings (Standalone), or put a wrapper for `/Applications/Tailscale.app/Contents/MacOS/Tailscale` on PATH (App Store). A shell alias isn't enough, because the dev command doesn't read it.
2. Sign in to Tailscale.
3. Join your machine to your tailnet:```bash [Terminal]
tailscale up
```
4. In the [admin console](https://login.tailscale.com/admin/dns), open **DNS** and select
**Enable HTTPS** under **HTTPS Certificates**.
5. In **Access controls**, give every tailnet member the `funnel` node attribute. Add this excerpt to
the policy file, or see [Funnel's requirements](https://tailscale.com/kb/1223/funnel#requirements-and-limitations)
to target fewer devices:```json [policy.hujson (excerpt)]
"nodeAttrs": [{ "target": ["autogroup:member"], "attr": ["funnel"] }]
```

Then register the endpoint once, as
[Receive webhooks locally](https://nuxtstart.com/docs/configuration/provider-accounts#receive-webhooks-locally) describes.
If a step is missing, `PORTLESS_FUNNEL=1 pnpm dev:web` stops and names it.

## Troubleshooting

Read the name in the error first. It names the value that's missing, which is rarely the thing you
were working on when it broke.

<table>
<thead>
  <tr>
    <th>
      What you see
    </th>
    
    <th>
      What to fix
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Infisical authentication is required
      </code>
    </td>
    
    <td>
      The client ID and secret in that application's <code>
        .env.local
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        projectId is required
      </code>
    </td>
    
    <td>
      Your Infisical project ID in that application's <code>
        .env.infisical
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Value is required but is currently empty
      </code>
    </td>
    
    <td>
      The key it names: identity in <code>
        .env.project.schema
      </code>
      
      , an origin in <code>
        .env.development.local
      </code>
      
      , a client ID or contact address in <code>
        .env.development
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      A regex or length error on <code>
        PROJECT_SLUG
      </code>
    </td>
    
    <td>
      A slug outside the shape in <a href="/docs/reference/project-identity#the-values-you-set">
        Project identity
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      An invalid URL or email
    </td>
    
    <td>
      A typo, or a stand-in in a typed key. Only the feature keys take a stand-in
    </td>
  </tr>
  
  <tr>
    <td>
      An error naming a single secret
    </td>
    
    <td>
      That key is missing from the <code>
        /local
      </code>
      
       folder in Infisical
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Docker isn't reachable
      </code>
      
       or any other <code>
        ✖
      </code>
      
       line before the server starts
    </td>
    
    <td>
      <a href="/docs/getting-started/technical-details#when-the-services-cant-start">
        When the services can't start
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROJECT_SLUG is empty in .env.project.schema
      </code>
    </td>
    
    <td>
      The project name from <a href="#name-your-project">
        Name your project
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Sign-up works but no email arrives
    </td>
    
    <td>
      You're reading another checkout's inbox. Open the Mailpit address this checkout's command printed
    </td>
  </tr>
  
  <tr>
    <td>
      Links to <code>
        /docs
      </code>
      
       and <code>
        /blog
      </code>
      
       don't load
    </td>
    
    <td>
      Start the website too, with <code>
        pnpm dev:site
      </code>
      
       in the same checkout
    </td>
  </tr>
</tbody>
</table>

## Next steps

Both applications run, so the rest of this section is about making the project yours:

- [Technical details](https://nuxtstart.com/docs/getting-started/technical-details) — what each package owns, and the
commands you'll use most
- [Customization](https://nuxtstart.com/docs/getting-started/customization) — colors, logo, name, fonts, and page head
- [Creating a page](https://nuxtstart.com/docs/getting-started/creating-a-page) — add a page, and decide which package
owns it
- [Deploying development](https://nuxtstart.com/docs/getting-started/deploying-development) — put `development` on
Cloudflare
- [Adding pull request previews](https://nuxtstart.com/docs/getting-started/adding-pull-request-previews) — a preview of
every pull request, before or after `development`
- [Adding staging](https://nuxtstart.com/docs/getting-started/adding-staging) — optional: a pre-production context
- [Going to production](https://nuxtstart.com/docs/getting-started/going-to-production) — the last stage: your domain and
real users, once the application and its name are final
- [Getting updates](https://nuxtstart.com/docs/getting-started/getting-updates) — pull NuxtStart's later changes into
your project
- [Automatic dependency updates](https://nuxtstart.com/docs/configuration/dependency-updates) — a pull request for each
dependency release, once you install the Renovate app

Two more if you skipped something above:

- [Set up sign-in and payments](https://nuxtstart.com/docs/configuration/provider-accounts) — add Google, GitHub, or
Polar if you left a stand-in behind
- [Environment values](https://nuxtstart.com/docs/reference/environment-values) — why the files are arranged this way

## Sitemap

See the full [sitemap](https://nuxtstart.com/sitemap.md) for all pages.
