Skip to content

Commit bee284f

Browse files
mythzmythz
committed
Update README.md
1 parent 8879663 commit bee284f

File tree

1 file changed

+39
-201
lines changed

1 file changed

+39
-201
lines changed

‎README.md‎

Lines changed: 39 additions & 201 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,8 @@ Integrated markdown blog with:
134134
- **Syntax Highlighting** - Prism.js code blocks
135135
- **Static Generation** - Pre-rendered at build time
136136
- **Frontmatter** - YAML metadata for posts
137+
- **YouTube Embeds** - Custom remark plugin for YouTube videos
138+
- **Typography Styling** - Beautiful prose with `@tailwindcss/typography`
137139

138140
### 🗄️ Database
139141

@@ -168,6 +170,40 @@ Automatic TypeScript type generation:
168170
- **Sync Command** - `npm run dtos` to update types
169171
- **ServiceStack Client** - Full-featured TypeScript client
170172

173+
### 📖 OpenAPI & Scalar
174+
175+
API documentation with modern tooling:
176+
177+
- **OpenAPI 3.0** - Auto-generated API specifications
178+
- **Scalar API Reference** - Interactive API documentation at `/scalar/v1`
179+
- **Development Mode** - API docs available in development
180+
181+
### 🧪 Testing
182+
183+
Comprehensive test coverage:
184+
185+
- **Vitest** - Fast unit testing for React components
186+
- **React Testing Library** - Component testing utilities
187+
- **jsdom** - Browser environment simulation
188+
- **Integration Tests** - .NET integration tests in `MyApp.Tests`
189+
190+
### 🐳 Docker Deployment
191+
192+
Production-ready containerization:
193+
194+
- **Kamal Deployment** - Zero-downtime deploys with Kamal
195+
- **GitHub Container Registry** - Automatic container builds
196+
- **SSL Auto-Certification** - Let's Encrypt integration
197+
- **Volume Persistence** - `App_Data` volume mounting for SQLite
198+
199+
### 🌙 Dark Mode
200+
201+
Built-in theme support:
202+
203+
- **System Preference** - Respects OS dark mode setting
204+
- **Tailwind CSS 4** - Native dark mode utilities
205+
- **Consistent Theming** - All components support dark mode
206+
171207
## Example Pages
172208

173209
| Page | Description |
@@ -180,6 +216,9 @@ Automatic TypeScript type generation:
180216
| `/profile` | User profile management |
181217
| `/posts` | MDX blog listing |
182218
| `/shadcn-ui` | shadcn/ui component showcase |
219+
| `/about` | About page (MDX) |
220+
| `/features` | Template features overview (MDX) |
221+
| `/privacy` | Privacy policy page (MDX) |
183222

184223
## Admin UIs
185224

@@ -193,207 +232,6 @@ Access built-in admin dashboards at:
193232
- `/admin-ui/apikeys` - API key management
194233
- `/admin-ui/chat` - AI chat analytics
195234

196-
## Testing
197-
198-
### .NET Tests
199-
200-
```bash
201-
cd MyApp.Tests
202-
dotnet test
203-
```
204-
205-
### Frontend Tests
206-
207-
```bash
208-
cd MyApp.Client
209-
npm test # Watch mode
210-
npm run test:run # Single run
211-
npm run test:ui # Vitest UI
212-
```
213-
214-
## Configuration
215-
216-
### Key Configuration Files
217-
218-
- **MyApp/appsettings.json** - Application configuration
219-
- **MyApp.Client/next.config.mjs** - Next.js configuration
220-
- **MyApp.Client/styles/index.css** - Tailwind CSS configuration
221-
- **config/deploy.yml** - Kamal deployment settings
222-
223-
### App Settings
224-
225-
Configure in `appsettings.json` or environment:
226-
227-
```json
228-
{
229-
"ConnectionStrings": {
230-
"DefaultConnection": "DataSource=App_Data/app.db;Cache=Shared"
231-
},
232-
"SmtpConfig": {
233-
"Host": "smtp.example.com",
234-
"Port": 587,
235-
"FromEmail": "[email protected]",
236-
"FromName": "MyApp"
237-
},
238-
"AppConfig": {
239-
"BaseUrl": "https://myapp.example.com"
240-
}
241-
}
242-
```
243-
244-
### App Settings Secrets
245-
246-
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:
247-
248-
```json
249-
[
250-
{
251-
"op":"replace",
252-
"path":"/ConnectionStrings/DefaultConnection",
253-
"value":"Server=service-postgres;Port=5432;User Id=dbuser;Password=dbpass;Database=dbname;Pooling=true;"
254-
},
255-
{ "op":"add", "path":"/SmtpConfig", "value":{
256-
"UserName": "SmptUser",
257-
"Password": "SmptPass",
258-
"Host": "email-smtp.us-east-1.amazonaws.com",
259-
"Port": 587,
260-
"From": "[email protected]",
261-
"FromName": "MyApp",
262-
"Bcc": "[email protected]"
263-
}
264-
},
265-
{ "op":"add", "path":"/Admins", "value": ["[email protected]","[email protected]"] },
266-
{ "op":"add", "path":"/CorsFeature/allowOriginWhitelist/-", "value":"https://servicestack.net" }
267-
]
268-
```
269-
270-
### SMTP Email
271-
272-
Enable email sending by uncommenting in `Program.cs`:
273-
274-
```csharp
275-
services.AddSingleton<IEmailSender<ApplicationUser>, EmailSender>();
276-
```
277-
278-
## Upgrading to Enterprise Database
279-
280-
To switch from SQLite to PostgreSQL/SQL Server/MySQL:
281-
282-
1. Install preferred RDBMS (ef-postgres, ef-mysql, ef-sqlserver), e.g:
283-
284-
```bash
285-
npx add-in ef-postgres
286-
```
287-
288-
2. Install `db-identity` to use RDBMS `DatabaseJobsFeature` for background jobs and `DbRequestLogger` for Request Logs:
289-
290-
```bash
291-
npx add-in db-identity
292-
```
293-
294-
## Deployment
295-
296-
### Docker + Kamal
297-
298-
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.
299-
300-
### GitHub Action Secrets
301-
302-
**Required - App Specific*:
303-
304-
The only secret needed to be configured per Repository.
305-
306-
| Variable | Example | Description |
307-
|----------|---------|-------------|
308-
| `KAMAL_DEPLOY_HOST` | `example.org` | Hostname used for SSL certificate and Kamal proxy |
309-
310-
**Required** (Organization Secrets):
311-
312-
Other Required variables can be globally configured in your GitHub Organization or User secrets which will
313-
enable deploying all your Repositories to the same server.
314-
315-
| Variable | Example | Description |
316-
|----------|----------|-------------|
317-
| `KAMAL_DEPLOY_IP` | `100.100.100.100` | IP address of the server to deploy to |
318-
| `SSH_PRIVATE_KEY` | `ssh-rsa ...` | SSH private key to access the server |
319-
| `LETSENCRYPT_EMAIL` | `[email protected]` | Email for Let's Encrypt SSL certificate |
320-
321-
**Optional**:
322-
323-
| Variable | Example | Description |
324-
|----------|---------|-------------|
325-
| `SERVICESTACK_LICENSE` | `...` | ServiceStack license key |
326-
327-
**Inferred** (from GitHub Action context):
328-
329-
These are inferred from the GitHub Action context and don't need to be configured.
330-
331-
| Variable | Source | Description |
332-
|----------|--------|-------------|
333-
| `GITHUB_REPOSITORY` | `${{ github.repository }}` | e.g. `acme/example.org` - used for service name and image |
334-
| `KAMAL_REGISTRY_USERNAME` | `${{ github.actor }}` | GitHub username for container registry |
335-
| `KAMAL_REGISTRY_PASSWORD` | `${{ secrets.GITHUB_TOKEN }}` | GitHub token for container registry auth |
336-
337-
#### Features
338-
339-
- **Docker containerization** with optimized .NET images
340-
- **SSL auto-certification** via Let's Encrypt
341-
- **GitHub Container Registry** integration
342-
- **Volume persistence** for App_Data including any SQLite database
343-
344-
345-
## AutoQuery CRUD Dev Workflow
346-
347-
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.
348-
349-
### Cheat Sheet
350-
351-
Create a new Table use `init <Table>`, e.g:
352-
353-
```bash
354-
npx okai init Table
355-
```
356-
357-
This will generate an empty `MyApp.ServiceModel/<Table>.d.ts` file along with stub AutoQuery APIs and DB Migration implementations.
358-
359-
#### Regenerate AutoQuery APIs and DB Migrations
360-
361-
After modifying the TypeScript Data Model to include the desired fields, re-run the `okai` tool to re-generate the AutoQuery APIs and DB Migrations:
362-
363-
```bash
364-
npx okai Table.d.ts
365-
```
366-
367-
> Command can be run anywhere within your Solution
368-
369-
After you're happy with your Data Model you can run DB Migrations to run the DB Migration and create your RDBMS Table:
370-
371-
```bash
372-
npm run migrate
373-
```
374-
375-
#### Making changes after first migration
376-
377-
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:
378-
379-
```bash
380-
npm run rerun:last
381-
```
382-
383-
#### Removing a Data Model and all generated code
384-
385-
If you changed your mind and want to get rid of the RDBMS Table you can revert the last migration:
386-
387-
```bash
388-
npm run revert:last
389-
```
390-
391-
Which will drop the table and then you can get rid of the AutoQuery APIs, DB Migrations and TypeScript Data model with:
392-
393-
```bash
394-
npx okai rm Transaction.d.ts
395-
```
396-
397235
## Learn More
398236

399237
- [ServiceStack Documentation](https://docs.servicestack.net)

0 commit comments

Comments
 (0)