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

# Local development

> Set up, run, and test Unkey locally

## Prerequisites

* <a href="https://nodejs.org" target="_blank">
    Node.js
  </a>
* <a href="https://go.dev" target="_blank">
    Go
  </a>
* <a href="https://pnpm.io/installation" target="_blank">
    pnpm
  </a>
* <a href="https://www.docker.com/products/docker-desktop" target="_blank">
    Docker
  </a>
* <a href="https://tilt.dev/" target="_blank">
    Tilt
  </a>
* <a href="https://github.com/tilt-dev/ctlptl" target="_blank">
    ctlptl
  </a>
* <a href="https://minikube.sigs.k8s.io" target="_blank">
    Minikube
  </a>
* <a href="https://github.com/FiloSottile/mkcert" target="_blank">
    mkcert
  </a>

Some of this can be automatically installed via `make install-brew-tools`

## Initial setup

Clone the repository and install dependencies:

```bash theme={"theme":"kanagawa-wave"}
git clone https://github.com/unkeyed/unkey
cd unkey
make install
```

## Configure depot

We use depot as build runner and right now that is not optional.

```bash theme={"theme":"kanagawa-wave"}
cp ./dev/.env.depot.example ./dev/.env.depot
# Edit ./dev/.env.depot with your Depot credentials
```

### Run dev mode

Start the full development setup:

```bash theme={"theme":"kanagawa-wave"}
make dev
```

You get:

* Tilt UI at `http://localhost:10350`
* Various services port-forwarded
* Dashboard at `http://localhost:3000`

## Local HTTPS with Frontline (optional)

Set up local TLS for `*.unkey.local`:

1. Configure local DNS:

```bash theme={"theme":"kanagawa-wave"}
./dev/setup-wildcard-dns.sh
```

2. Start the minikube tunnel in another terminal:

```bash theme={"theme":"kanagawa-wave"}
make tunnel
```

3. Open the local domain:

```bash theme={"theme":"kanagawa-wave"}
open https://app.unkey.local
```

Tilt generates trusted TLS certificates using mkcert and Frontline terminates TLS on port 443.

## Stop the development environment

```bash theme={"theme":"kanagawa-wave"}
make down
```

## Environment configuration

### Local authentication

Set local auth mode in your `.env` file:

```plaintext theme={"theme":"kanagawa-wave"}
AUTH_PROVIDER="local"
```

### Optional services

WorkOS authentication:

```plaintext theme={"theme":"kanagawa-wave"}
AUTH_PROVIDER="workos"
WORKOS_CLIENT_ID=<your client ID>
WORKOS_API_KEY=<your API key>
WORKOS_COOKIE_PASSWORD=<your base64 password>
```

Stripe billing:

```plaintext theme={"theme":"kanagawa-wave"}
STRIPE_SECRET_KEY=<your Stripe secret key>
```

## Seed local data

```bash theme={"theme":"kanagawa-wave"}
make unkey dev seed local
```

## Test locally

Run Go tests with Bazel:

```bash theme={"theme":"kanagawa-wave"}
make test
```

Run a single Go test:

```bash theme={"theme":"kanagawa-wave"}
bazel test //pkg/cache:cache_test --test_filter=TestCacheName
```

Run TypeScript tests with pnpm:

```bash theme={"theme":"kanagawa-wave"}
pnpm --dir=web test
```

## Code quality

```bash theme={"theme":"kanagawa-wave"}
make fmt
make build
```

## Troubleshooting

### Failure: resource\_exhausted: too many requests

If you receive an error message similar to below, make sure you authenticate your terminal with buf, you can sign up for a free account at: [https://buf.build/home](https://buf.build/home)

```shellscript theme={"theme":"kanagawa-wave"}
Failure: resource_exhausted: too many requestssh

Please see https://buf.build/docs/bsr/rate-limits/ for details about BSR rate limiting.
svc/sentinel/proto/generate.go:4: running "go": exit status 1
Failure: resource_exhausted: too many requests

Please see https://buf.build/docs/bsr/rate-limits/ for details about BSR rate limiting.
svc/vault/proto/generate.go:3: running "go": exit status 1
make: *** [generate] Error 1
```