You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Instead of polluting each GitHub Reposity with multiple App-specific GitHub Action Secrets, you can save all your secrets in a single `APPSETTINGS_PATCH` GitHub Action Secret to patch `appsettings.json` with environment-specific configuration using [JSON Patch](https://jsonpatch.com). E.g:
2. Install `db-identity` to use RDBMS `DatabaseJobsFeature` for background jobs and `DbRequestLogger` for Request Logs:
320
+
321
+
```bash
322
+
npx add-in db-identity
323
+
```
324
+
325
+
## AutoQuery CRUD Dev Workflow
326
+
327
+
For Rapid Development simple [TypeScript Data Models](https://docs.servicestack.net/autoquery/okai-models) can be used to generate C# AutoQuery APIs and DB Migrations.
328
+
329
+
### Cheat Sheet
330
+
331
+
### Create a new Table
332
+
333
+
Create a new Table use `init <Table>`, e.g:
334
+
335
+
```bash
336
+
npx okai init Table
337
+
```
338
+
339
+
This will generate an empty `MyApp.ServiceModel/<Table>.d.ts` file along with stub AutoQuery APIs and DB Migration implementations.
340
+
341
+
### Use AI to generate the TypeScript Data Model
342
+
343
+
Or to get you started quickly you can also use AI to generate the initial TypeScript Data Model with:
344
+
345
+
```bash
346
+
npx okai "Table to store Customer Stripe Subscriptions"
347
+
```
348
+
349
+
This launches a TUI that invokes ServiceStack's okai API to fire multiple concurrent requests to frontier cloud
350
+
and OSS models to generate the TypeScript Data Models required to implement this feature.
351
+
You'll be able to browse and choose which of the AI Models you prefer which you can accept by pressing `a`
352
+
to `(a) accept`. These are the data models [Claude Sonnet 4.5 generated](https://servicestack.net/text-to-blazor?id=1764337230546) for this prompt.
353
+
354
+
#### Regenerate AutoQuery APIs and DB Migrations
355
+
356
+
After modifying the `Table.d.ts` TypeScript Data Model to include the desired fields, re-run the `okai` tool to re-generate the AutoQuery APIs and DB Migrations:
357
+
358
+
```bash
359
+
npx okai Table.d.ts
360
+
```
361
+
362
+
> Command can be run anywhere within your Solution
363
+
364
+
After you're happy with your Data Model you can run DB Migrations to run the DB Migration and create your RDBMS Table:
365
+
366
+
```bash
367
+
npm run migrate
368
+
```
369
+
370
+
#### Making changes after first migration
371
+
372
+
If you want to make further changes to your Data Model, you can re-run the `okai` tool to update the AutoQuery APIs and DB Migrations, then run the `rerun:last` npm script to drop and re-run the last migration:
373
+
374
+
```bash
375
+
npm run rerun:last
376
+
```
377
+
378
+
#### Removing a Data Model and all generated code
379
+
380
+
If you changed your mind and want to get rid of the RDBMS Table you can revert the last migration:
381
+
382
+
```bash
383
+
npm run revert:last
384
+
```
385
+
386
+
Which will drop the table and then you can get rid of the AutoQuery APIs, DB Migrations and TypeScript Data model with:
387
+
388
+
```bash
389
+
npx okai rm Transaction.d.ts
390
+
```
391
+
392
+
## Deployment
393
+
394
+
### Docker + Kamal
395
+
396
+
This project includes GitHub Actions for CI/CD with automatic Docker image builds and production [deployment with Kamal](https://docs.servicestack.net/kamal-deploy). The `/config/deploy.yml` configuration is designed to be reusable across projects—it dynamically derives service names, image paths, and volume mounts from environment variables, so you only need to configure your server's IP and hostname using GitHub Action secrets.
397
+
398
+
### GitHub Action Secrets
399
+
400
+
**Required - App Specific*:
401
+
402
+
The only secret needed to be configured per Repository.
403
+
404
+
| Variable | Example | Description |
405
+
|----------|---------|-------------|
406
+
|`KAMAL_DEPLOY_HOST`|`example.org`| Hostname used for SSL certificate and Kamal proxy |
407
+
408
+
**Required** (Organization Secrets):
409
+
410
+
Other Required variables can be globally configured in your GitHub Organization or User secrets which will
411
+
enable deploying all your Repositories to the same server.
412
+
413
+
| Variable | Example | Description |
414
+
|----------|----------|-------------|
415
+
|`KAMAL_DEPLOY_IP`|`100.100.100.100`| IP address of the server to deploy to |
416
+
|`SSH_PRIVATE_KEY`|`ssh-rsa ...`| SSH private key to access the server |
417
+
|`LETSENCRYPT_EMAIL`|`[email protected]`| Email for Let's Encrypt SSL certificate |
These are inferred from the GitHub Action context and don't need to be configured.
428
+
429
+
| Variable | Source | Description |
430
+
|----------|--------|-------------|
431
+
|`GITHUB_REPOSITORY`|`${{ github.repository }}`| e.g. `acme/example.org` - used for service name and image |
432
+
|`KAMAL_REGISTRY_USERNAME`|`${{ github.actor }}`| GitHub username for container registry |
433
+
|`KAMAL_REGISTRY_PASSWORD`|`${{ secrets.GITHUB_TOKEN }}`| GitHub token for container registry auth |
434
+
435
+
#### Features
436
+
437
+
-**Docker containerization** with optimized .NET images
438
+
-**SSL auto-certification** via Let's Encrypt
439
+
-**GitHub Container Registry** integration
440
+
-**Volume persistence** for App_Data including any SQLite database
441
+
442
+
## AI-Assisted Development with CLAUDE.md
443
+
444
+
As part of our objectives of improving developer experience and embracing modern AI-assisted development workflows - all new .NET SPA templates include a comprehensive `AGENTS.md` file designed to optimize AI-assisted development workflows.
445
+
446
+
### What is CLAUDE.md?
447
+
448
+
`CLAUDE.md` and [AGENTS.md](https://agents.md) onboards Claude (and other AI assistants) to your codebase by using a structured documentation file that provides it with complete context about your project's architecture, conventions, and technology choices. This enables more accurate code generation, better suggestions, and faster problem-solving.
-**Project Structure** - Gives Claude a map of the codebase
456
+
-**ServiceStack Conventions** - DTO patterns, Service implementation, AutoQuery, Authentication, and Validation
457
+
-**API Integration** - TypeScript DTO generation, API client usage, component patterns, and form handling
458
+
-**Database Patterns** - OrmLite setup, migrations, and data access patterns
459
+
-**Common Development Tasks** - Step-by-step guides for adding APIs, implementing features, and extending functionality
460
+
-**Testing & Deployment** - Test patterns and deployment workflows
461
+
462
+
### Extending with Project-Specific Details
463
+
464
+
The existing `CLAUDE.md` serves as a solid foundation, but for best results, you should extend it with project-specific details like the purpose of the project, key parts and features of the project and any unique conventions you've adopted.
465
+
466
+
### Benefits
467
+
468
+
-**Faster Onboarding** - New developers (and AI assistants) understand project conventions immediately
469
+
-**Consistent Code Generation** - AI tools generate code following your project's patterns
470
+
-**Better Context** - AI assistants can reference specific ServiceStack patterns and conventions
471
+
-**Reduced Errors** - Clear documentation of framework-specific conventions
472
+
-**Living Documentation** - Keep it updated as your project evolves
473
+
474
+
### How to Use
475
+
476
+
Claude Code and most AI Assistants already support automatically referencing `CLAUDE.md` and `AGENTS.md` files, for others you can just include it in your prompt context when asking for help, e.g:
477
+
478
+
> Using my project's AGENTS.md, can you help me add a new AutoQuery API for managing Products?
479
+
480
+
The AI will understand your App's ServiceStack conventions, React setup, and project structure, providing more accurate and contextual assistance.
0 commit comments