Skip to content

Commit fcf14e5

Browse files
mythzmythz
committed
Update README.md
1 parent 67ac8c8 commit fcf14e5

File tree

1 file changed

+93
-54
lines changed

1 file changed

+93
-54
lines changed

‎README.md‎

Lines changed: 93 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ dotnet watch
6464
- **ASP.NET Core Identity** - Complete authentication & authorization system
6565
- **Entity Framework Core** - For Identity data management
6666
- **OrmLite** - ServiceStack's fast, lightweight Typed ORM for application data
67-
- **SQLite** - Default database (easily upgradable to PostgreSQL/SQL Server/MySQL)
67+
- **SQLite** - Default database - [Upgrade to PostgreSQL/SQL Server/MySQL](#upgrading-to-enterprise-database)
6868

6969
## Major Features
7070

@@ -87,7 +87,7 @@ dotnet watch
8787
- Command pattern for job execution
8888
- Email sending via background jobs
8989
- Recurring job scheduling support
90-
- Upgradable to `DatabaseJobsFeature` for enterprise RDBMS
90+
- Uses monthly rolling Sqlite databases by default - [Upgrade to PostgreSQL/SQL Server/MySQL](#upgrading-to-enterprise-database)
9191

9292
### 4. Developer Experience
9393
- **Admin UI** at `/admin-ui` for App management
@@ -267,57 +267,6 @@ npx add-in ef-postgres
267267
npx add-in db-identity
268268
```
269269

270-
## Deployment
271-
272-
### Docker + Kamal
273-
274-
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.
275-
276-
### GitHub Action Secrets
277-
278-
**Required - App Specific*:
279-
280-
The only secret needed to be configured per Repository.
281-
282-
| Variable | Example | Description |
283-
|----------|---------|-------------|
284-
| `KAMAL_DEPLOY_HOST` | `example.org` | Hostname used for SSL certificate and Kamal proxy |
285-
286-
**Required** (Organization Secrets):
287-
288-
Other Required variables can be globally configured in your GitHub Organization or User secrets which will
289-
enable deploying all your Repositories to the same server.
290-
291-
| Variable | Example | Description |
292-
|----------|----------|-------------|
293-
| `KAMAL_DEPLOY_IP` | `100.100.100.100` | IP address of the server to deploy to |
294-
| `SSH_PRIVATE_KEY` | `ssh-rsa ...` | SSH private key to access the server |
295-
| `LETSENCRYPT_EMAIL` | `[email protected]` | Email for Let's Encrypt SSL certificate |
296-
297-
**Optional**:
298-
299-
| Variable | Example | Description |
300-
|----------|---------|-------------|
301-
| `SERVICESTACK_LICENSE` | `...` | ServiceStack license key |
302-
303-
**Inferred** (from GitHub Action context):
304-
305-
These are inferred from the GitHub Action context and don't need to be configured.
306-
307-
| Variable | Source | Description |
308-
|----------|--------|-------------|
309-
| `GITHUB_REPOSITORY` | `${{ github.repository }}` | e.g. `acme/example.org` - used for service name and image |
310-
| `KAMAL_REGISTRY_USERNAME` | `${{ github.actor }}` | GitHub username for container registry |
311-
| `KAMAL_REGISTRY_PASSWORD` | `${{ secrets.GITHUB_TOKEN }}` | GitHub token for container registry auth |
312-
313-
#### Features
314-
315-
- **Docker containerization** with optimized .NET images
316-
- **SSL auto-certification** via Let's Encrypt
317-
- **GitHub Container Registry** integration
318-
- **Volume persistence** for App_Data including any SQLite database
319-
320-
321270
## AutoQuery CRUD Dev Workflow
322271

323272
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.
@@ -345,7 +294,7 @@ npx okai "Table to store Customer Stripe Subscriptions"
345294
This launches a TUI that invokes ServiceStack's okai API to fire multiple concurrent requests to frontier cloud
346295
and OSS models to generate the TypeScript Data Models required to implement this feature.
347296
You'll be able to browse and choose which of the AI Models you prefer which you can accept by pressing `a`
348-
to `(a) accept`. These are the data models [Claude Sonnet 4.5 generated](https://servicestack.net/text-to-blazor?id=1764337230546) generated for this prompt.
297+
to `(a) accept`. These are the data models [Claude Sonnet 4.5 generated](https://servicestack.net/text-to-blazor?id=1764337230546) for this prompt.
349298

350299
#### Regenerate AutoQuery APIs and DB Migrations
351300

@@ -385,6 +334,96 @@ Which will drop the table and then you can get rid of the AutoQuery APIs, DB Mig
385334
npx okai rm Transaction.d.ts
386335
```
387336

337+
## Deployment
338+
339+
### Docker + Kamal
340+
341+
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.
342+
343+
### GitHub Action Secrets
344+
345+
**Required - App Specific*:
346+
347+
The only secret needed to be configured per Repository.
348+
349+
| Variable | Example | Description |
350+
|----------|---------|-------------|
351+
| `KAMAL_DEPLOY_HOST` | `example.org` | Hostname used for SSL certificate and Kamal proxy |
352+
353+
**Required** (Organization Secrets):
354+
355+
Other Required variables can be globally configured in your GitHub Organization or User secrets which will
356+
enable deploying all your Repositories to the same server.
357+
358+
| Variable | Example | Description |
359+
|----------|----------|-------------|
360+
| `KAMAL_DEPLOY_IP` | `100.100.100.100` | IP address of the server to deploy to |
361+
| `SSH_PRIVATE_KEY` | `ssh-rsa ...` | SSH private key to access the server |
362+
| `LETSENCRYPT_EMAIL` | `[email protected]` | Email for Let's Encrypt SSL certificate |
363+
364+
**Optional**:
365+
366+
| Variable | Example | Description |
367+
|----------|---------|-------------|
368+
| `SERVICESTACK_LICENSE` | `...` | ServiceStack license key |
369+
370+
**Inferred** (from GitHub Action context):
371+
372+
These are inferred from the GitHub Action context and don't need to be configured.
373+
374+
| Variable | Source | Description |
375+
|----------|--------|-------------|
376+
| `GITHUB_REPOSITORY` | `${{ github.repository }}` | e.g. `acme/example.org` - used for service name and image |
377+
| `KAMAL_REGISTRY_USERNAME` | `${{ github.actor }}` | GitHub username for container registry |
378+
| `KAMAL_REGISTRY_PASSWORD` | `${{ secrets.GITHUB_TOKEN }}` | GitHub token for container registry auth |
379+
380+
#### Features
381+
382+
- **Docker containerization** with optimized .NET images
383+
- **SSL auto-certification** via Let's Encrypt
384+
- **GitHub Container Registry** integration
385+
- **Volume persistence** for App_Data including any SQLite database
386+
387+
## AI-Assisted Development with CLAUDE.md
388+
389+
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.
390+
391+
### What is CLAUDE.md?
392+
393+
`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.
394+
395+
### What's Included
396+
397+
Each template's `AGENTS.md` contains:
398+
399+
- **Project Architecture Overview** - Technology stack, design patterns, and key architectural decisions
400+
- **Project Structure** - Gives Claude a map of the codebase
401+
- **ServiceStack Conventions** - DTO patterns, Service implementation, AutoQuery, Authentication, and Validation
402+
- **API Integration** - TypeScript DTO generation, API client usage, component patterns, and form handling
403+
- **Database Patterns** - OrmLite setup, migrations, and data access patterns
404+
- **Common Development Tasks** - Step-by-step guides for adding APIs, implementing features, and extending functionality
405+
- **Testing & Deployment** - Test patterns and deployment workflows
406+
407+
### Extending with Project-Specific Details
408+
409+
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.
410+
411+
### Benefits
412+
413+
- **Faster Onboarding** - New developers (and AI assistants) understand project conventions immediately
414+
- **Consistent Code Generation** - AI tools generate code following your project's patterns
415+
- **Better Context** - AI assistants can reference specific ServiceStack patterns and conventions
416+
- **Reduced Errors** - Clear documentation of framework-specific conventions
417+
- **Living Documentation** - Keep it updated as your project evolves
418+
419+
### How to Use
420+
421+
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:
422+
423+
> Using my project's AGENTS.md, can you help me add a new AutoQuery API for managing Products?
424+
425+
The AI will understand your App's ServiceStack conventions, React setup, and project structure, providing more accurate and contextual assistance.
426+
388427
## Ideal Use Cases
389428

390429
- SaaS applications requiring authentication

0 commit comments

Comments
 (0)