kdaniel2410
bf5a1ad5b5
Point the login form at the explicit named action used by the server route. Remove the stale production preview command from the README deployment notes.
147 lines
3.5 KiB
Markdown
147 lines
3.5 KiB
Markdown
# Clearity
|
|
|
|
Clearity is a workspace, client, and contract management platform for managed office operations. It tracks clients, contacts, addresses, rooms, services, bookings, contracts, invoices, and workspace admins from a SvelteKit dashboard.
|
|
|
|
The app is built with SvelteKit, Svelte 5, shadcn-svelte, Superforms, Better Auth, Drizzle ORM, SQLite/libSQL, and Cloudflare Workers.
|
|
|
|
## Development
|
|
|
|
Install dependencies:
|
|
|
|
```sh
|
|
pnpm install
|
|
```
|
|
|
|
Create a local `.env` file:
|
|
|
|
```sh
|
|
DATABASE_URL=file:local.db
|
|
ORIGIN=http://localhost:5173
|
|
BETTER_AUTH_SECRET=replace-with-a-long-random-secret
|
|
```
|
|
|
|
Generate a Better Auth secret with:
|
|
|
|
```sh
|
|
openssl rand -base64 32
|
|
```
|
|
|
|
Apply database migrations:
|
|
|
|
```sh
|
|
DATABASE_URL=file:local.db pnpm db:migrate
|
|
```
|
|
|
|
Start the development server:
|
|
|
|
```sh
|
|
pnpm dev
|
|
```
|
|
|
|
Open `http://localhost:5173/login`. If no Better Auth users exist yet, Clearity shows a first-admin setup form instead of the normal sign-in form. Submitting it creates the initial user with the default Better Auth `admin` role and signs you in.
|
|
|
|
Useful development commands:
|
|
|
|
```sh
|
|
pnpm check # Wrangler types, SvelteKit sync, and svelte-check
|
|
pnpm lint # Prettier check and ESLint
|
|
pnpm format # Format the codebase
|
|
pnpm db:generate # Generate Drizzle migrations after schema changes
|
|
pnpm db:migrate # Apply Drizzle migrations to DATABASE_URL
|
|
pnpm db:studio # Open Drizzle Studio
|
|
pnpm gen # Regenerate Cloudflare Worker types
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
Required:
|
|
|
|
- `DATABASE_URL`: SQLite/libSQL connection URL. Use `file:local.db` for local development.
|
|
- `ORIGIN`: Public app origin, for example `http://localhost:5173` locally or `https://clearity.example.com` in production.
|
|
- `BETTER_AUTH_SECRET`: Secret used by Better Auth.
|
|
|
|
## Database
|
|
|
|
The application schema lives in `src/lib/server/db`. Drizzle migration files live in `drizzle`.
|
|
|
|
Local development currently uses the libSQL client through `DATABASE_URL`, so the fastest local database is a SQLite file:
|
|
|
|
```sh
|
|
DATABASE_URL=file:local.db pnpm db:migrate
|
|
```
|
|
|
|
For schema changes:
|
|
|
|
```sh
|
|
pnpm db:generate
|
|
DATABASE_URL=file:local.db pnpm db:migrate
|
|
```
|
|
|
|
## Production Deployment
|
|
|
|
The Worker is configured in `wrangler.jsonc` and built with the SvelteKit Cloudflare adapter.
|
|
|
|
Authenticate Wrangler:
|
|
|
|
```sh
|
|
pnpm wrangler login
|
|
pnpm wrangler whoami
|
|
```
|
|
|
|
Create a production D1 database:
|
|
|
|
```sh
|
|
pnpm wrangler d1 create clearity-production
|
|
```
|
|
|
|
Wrangler prints a `database_id`. Add it to `wrangler.jsonc`:
|
|
|
|
```jsonc
|
|
{
|
|
"d1_databases": [
|
|
{
|
|
"binding": "DB",
|
|
"database_name": "clearity-production",
|
|
"database_id": "<database_id>"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Regenerate Worker types after changing Wrangler bindings:
|
|
|
|
```sh
|
|
pnpm gen
|
|
```
|
|
|
|
Apply SQL migrations to the remote D1 database:
|
|
|
|
```sh
|
|
for file in drizzle/*.sql; do
|
|
pnpm wrangler d1 execute clearity-production --remote --file "$file"
|
|
done
|
|
```
|
|
|
|
Set production secrets:
|
|
|
|
```sh
|
|
pnpm wrangler secret put ORIGIN
|
|
pnpm wrangler secret put BETTER_AUTH_SECRET
|
|
```
|
|
|
|
This codebase currently reads the database through `DATABASE_URL`. If production is deployed against Cloudflare D1, wire the runtime database client to the `DB` D1 binding before deploying. If production is deployed against a hosted libSQL database instead, set `DATABASE_URL` as a Worker secret:
|
|
|
|
```sh
|
|
pnpm wrangler secret put DATABASE_URL
|
|
```
|
|
|
|
Build and deploy:
|
|
|
|
```sh
|
|
pnpm build
|
|
pnpm wrangler deploy
|
|
```
|
|
|
|
|
|
Create the first production admin by opening `/login` after migrations have run. The setup form is only shown while the Better Auth `user` table is empty.
|