Update deploy docs

mythz · mythz · commit ab0f0b46f60d · 2025-12-04T19:16:34.000+08:00
diff --git a/MyApp/_pages/kamal-deploy.md b/MyApp/_pages/kamal-deploy.md
@@ -2,24 +2,36 @@
 title: Deploying with Kamal
 ---
 
-ServiceStack templates now support deployment using Kamal, a CLI tool from the BaseCamp team that simplifies containerized application deployments. Kamal wraps SSH and Docker to streamline self-hosting while maintaining GitHub Actions as the CI runner.
+All project templates includes the necessary GitHub Actions for CI/CD with automatic Docker image builds and
+production deployment with Kamal to any Linux server with SSH. Kamal is a CLI tool from the BaseCamp team that simplifies containerized application deployments, wrapping SSH and Docker to streamline self-hosting while maintaining GitHub Actions as the CI runner.
 
 <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="-mDJfRG8mLQ" style="background-image: url('https://img.youtube.com/vi/-mDJfRG8mLQ/maxresdefault.jpg')"></lite-youtube>
 
 ## Overview
 
 Kamal enables simple commands to deploy containerized applications to Linux hosts, handling:
-- Bootstrap configuration
-- Reverse proxy setup
-- SSL certificate provisioning
-- Zero-downtime deployments
-- Health checks on deploy
-- Rolling back changes
+- **Docker containerization** with optimized .NET images
+- **Bootstrap configuration**
+- **Reverse proxy setup**
+- **SSL auto-certification** via Let's Encrypt
+- **Zero-downtime deployments**
+- **Health checks on deploy**
+- **Rolling back changes**
+- **Volume persistence** for App_Data including any SQLite database
+- **GitHub Container Registry** integration
 
 ::: info
-Kamal is built by the BaseCamp team, developers of Hey email service and BaseCamp project management tool. For comprehensive documentation on all Kamal features, visit [https://kamal-deploy.org/](https://kamal-deploy.org/)
+Kamal is built by the BaseCamp team, developers of Hey.com and BaseCamp.com. For comprehensive documentation on all Kamal features, visit [https://kamal-deploy.org](https://kamal-deploy.org)
 :::
 
+### Hosting Recommendation
+
+If you don't have a Linux Server, we recommend Hetzner
+[who we've found](https://docs.servicestack.net/ormlite/litestream#savings-at-scale)
+offers the best value [US Cloud VMs](https://cloud.hetzner.com) offering **$15/mo** for a dedicated VM with
+**2vCPU / 8GB** RAM which is being used to host **30 Docker Apps**, including all project template live demos -
+using the GitHub Actions included in each template.
+
 ## Getting Started
 
 ### Prerequisites
@@ -30,30 +42,104 @@ Kamal is built by the BaseCamp team, developers of Hey email service and BaseCam
 ### Initial Setup
 
 1. Create a new ServiceStack application:
-```bash
+:::sh
 npx create-net blazor-vue MyApp
-```
+:::
 
-2. Generate deployment SSH key:
-```bash
+2. Create the SSH Private and Public Keys:
+:::sh
 ssh-keygen -t ed25519 -C "deploy@myapp" -f ./deploy-key
-```
+:::
 
-3. Copy public key to enable server access:
-```bash
+3. Copy Public Key to deployment server to enable SSH access:
+:::sh
 cat ~/deploy-key.pub | ssh <user>@<your-ip> "cat >> ~/.ssh/authorized_keys"
-```
+:::
 
-### GitHub Actions
+4. Configure GitHub Secrets for Kamal to access your deployment server:
 
-The template includes a GitHub Actions workflow that is broken up into 3 steps that trigger on push to the `main` branch, and then on successful build and test, it will deploy the application to your server.
+- SSH private key to access the server: ssh-rsa ...
+:::sh
+gh secret set SSH_PRIVATE_KEY < ~/deploy-key
+:::
 
-Once you create your GitHub repository, add the `SSH_PRIVATE_KEY` secret to your repository settings with the contents of your private key file.
+- IP address of the server to deploy to: 100.100.100.100
+:::sh
+gh secret set KAMAL_DEPLOY_IP [your.ip]
+:::
 
-```bash
-gh secret set SSH_PRIVATE_KEY < ~/deploy-key
+- Email for Let's Encrypt SSL certificate: me@example.org
+:::sh
+gh secret set LETSENCRYPT_EMAIL [your@email]
+:::
+
+These Required variables can be globally configured in your GitHub Organization or User secrets which will
+enable deploying all your Repositories to the same server.
+
+Optionally configure any other global secrets to be shared by all Apps here:
+
+:::sh
+gh secret set SERVICESTACK_LICENSE [license-key]
+:::
+
+5. Configure GitHub Secrets for your App
+
+The only secret that needs to be configured per App is:
+
+Hostname used for SSL certificate and Kamal proxy: www.example.org
+
+:::sh
+gh secret set KAMAL_DEPLOY_HOST [www.example.org]
+:::
+
+You could register any App-specific secrets here, although our preference is instead of polluting each
+GitHub Repository 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:
+
+JSON Patch to apply to appsettings.json:
+:::sh
+gh secret set APPSETTINGS_PATCH [json-patch]
+:::
+
+JSON Patch example:
+
+```json
+[
+    {
+        "op":"replace",
+        "path":"/ConnectionStrings/DefaultConnection",
+        "value":"Server=service-postgres;Port=5432;User Id=dbuser;Password=dbpass;Database=dbname"
+    },
+    { "op":"add", "path":"/SmtpConfig", "value":{
+        "UserName": "SmptUser",
+        "Password": "SmptPass",
+        "Host": "email-smtp.us-east-1.amazonaws.com",
+        "Port": 587,
+        "From": "noreply@example.org",
+        "FromName": "MyApp",
+        "Bcc": "copy@example.org"
+      }
+    },
+    { "op":"add", "path":"/Admins", "value": ["admin1@email.com","admin2@email.com"] },
+    { "op":"add", "path":"/CorsFeature/allowOriginWhitelist/-", "value":"https://example.org" }
+]
 ```
 
+### Inferred Variables
+
+These variables are inferred from the GitHub Action context and don't need to be configured.
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `GITHUB_REPOSITORY` | `${{github.repository}}`  | `acme/example.org` - used for service name and image |
+| `KAMAL_REGISTRY_USERNAME` | `${{github.actor}}` | GitHub username for container registry |
+| `KAMAL_REGISTRY_PASSWORD` | `${{secrets.GITHUB_TOKEN}}` | GitHub token for container registry auth |
+
+### GitHub Actions
+
+The template includes a GitHub Actions workflow that is broken up into 3 steps that trigger on push to the `main` branch, and then on successful build and test, it will deploy the application to your server.
+
 ### Structure
 
 The deployment scripts are embedded in the templates [/.github/workflows](https://github.com/NetCoreTemplates/blazor-vue/tree/main/.github/workflows):
@@ -64,6 +150,8 @@ The deployment scripts are embedded in the templates [/.github/workflows](https:
   build-container.yml
   release.yml
 /.kamal
+  /hooks
+  secrets
 /config
   deploy.yml
 ```
@@ -80,59 +168,91 @@ Your App's Kamal deployment is configured in [config/deploy.yml](https://github.
 
 ### Configuration
 
-Update `config/deploy.yml` with your deployment settings:
+The [/config/deploy.yml](https://github.com/NetCoreTemplates/next-static/blob/main/config/deploy.yml) configuration
+is designed to be reusable across projects as 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.
+
+Once you make these changes, commit and push to your repository to trigger the GitHub Actions workflow.
+
+Kamal will deploy the required services including Docker and Kamal Proxy if your server doesn't already have them installed.
+
+:::info
+When using ASP.NET Core applications with Kamal-Proxy, ensure your application is running with the environment variable `ASPNETCORE_FORWARDEDHEADERS_ENABLED` set to `true`.
+The template has this by default, but if you are getting errors with 302 redirects, ensure this is set.
+:::
+
+The authentication between GitHub Container Registry (ghcr.io) and your server is handled by the GitHub Actions workflow, the `deploy.yml` and [Kamal Secrets](https://kamal-deploy.org/docs/configuration/environment-variables/#secrets).
+
+### Using Kamal Locally
+
+To also be able to use kamal locally to inspect logs or deploy from your own server you can add the GitHub Action
+Secrets into a local `.env` file, e.g:
+
+```bash
+# Required for Kamal deploy.yml template processing
+
+GITHUB_REPOSITORY=acme/example.org
 
-```yaml
-service: myapp
-image: your-github-username/myapp
+# Server deployment details
+KAMAL_DEPLOY_IP=100.100.100.100
+KAMAL_DEPLOY_HOST=example.org
 
-servers:
-  web:
-    - <your-server-ip-address>
+# Container registry credentials (for ghcr.io)
+KAMAL_REGISTRY_USERNAME=my-user
+GITHUB_TOKEN=ghp_xxx
 
-proxy:
-  ssl: true
-  host: myapp.example.com
+# Login to GitHub Container Registry
+#echo $KAMAL_REGISTRY_PASSWORD | docker login ghcr.io -u my-user --password-stdin
 ```
 
-::: info
-The `image` value should match your GitHub repository path on ghcr.io. For example: `ghcr.io/username/repository`
+You can then load the environment variables into your shell with:
+
+:::sh
+source ./load-env.sh
 :::
 
-Once you make these changes, commit and push to your repository to trigger the GitHub Actions workflow.
 
-Kamal will deploy the required services including Docker and Kamal Proxy if you server doesn't already have them installed.
+Which will allow you to use kamal locally to access your deployment server, e.g:
 
-:::info
-When using ASP.NET Core applications with Kamal-Proxy, ensure your application is running with the environment variable `ASPNETCORE_FORWARDEDHEADERS_ENABLED` set to `true`. 
-The template has this by default, but if you are getting errors with 302 redirects, ensure this is set.
+:::sh
+kamal app logs -f
 :::
 
-The authentication between GitHub Container Registry (ghcr.io) and your server is handled by the GitHub Actions workflow, the `deploy.yml` and [Kamal Secrets](https://kamal-deploy.org/docs/configuration/environment-variables/#secrets).
-
 :::info
 You can still use the Kamal CLI locally, but if you want to directly push deployments with `kamal deploy`, you will need to locally populate `KAMAL_REGISTRY_USER` and `KAMAL_REGISTRY_PASSWORD` with your GitHub username and a GitHub Personal Access Token with `read:packages` scope.
 :::
 
+### Hard code App specific variables
+
+Alternatively if you don't want to maintain a `.env` with GitHub Action Secrets you can hard-code all
+App-specific variables in your `deploy.yml` file so it doesn't need to perform any template processing
+for its Environment Variable substitutions.
+
 ## Common Kamal Commands
 
 Kamal provides several useful commands for managing your deployment:
 
-```bash
-# View deployment details
+- View deployment details
+:::sh
 kamal details
+:::
 
-# Check application logs
-kamal app logs
+- Check application logs
+:::sh
+kamal app logs -f
+:::
 
-# Deploy new version
+- Deploy new version
+:::sh
 kamal deploy
+:::
 
-# Restart application
+- Restart application
+:::sh
 kamal app boot
-```
+:::
 
-::: info
+:::info
 Kamal commands are context-aware and will use the configuration from your current application directory. This makes managing multiple applications across different servers a lot easier as more applications are added.
 :::
 
@@ -151,6 +271,6 @@ Delete the `.<app-name>` file in your deployment user's home directory and re-ru
 
 If you are getting:
 
-  Image ghcr.io/netcoreapps/northwindauto:latest is missing the 'service' label
+    Image ghcr.io/netcoreapps/northwindauto:latest is missing the 'service' label
 
-Ensure that your AppHost csproj file has `ContainerLabel` with the value matching the `service` in your `deploy.yml` file.
+Ensure your AppHost **csproj** has `ContainerLabel` with the value matching the `service` in your `deploy.yml`.
diff --git a/MyApp/_pages/templates/index.md b/MyApp/_pages/templates/index.md
@@ -5,7 +5,7 @@ slug: templates-overview
 
 ServiceStack accelerates .NET development with battle-tested templates for building modern applications - from high-performance Web APIs and backend services to full-stack web apps, microservices, and cloud-native solutions. Whether you're building a Jamstack site, a Blazor application, or a serverless API, ServiceStack provides the foundation to ship faster.
 
-:::copy
+:::sh
 npx create-net ls
 :::
 
@@ -23,10 +23,10 @@ Where it will display all repositories in [.NET 10](https://github.com/NetCoreTe
 $ npx create-net `<template>` `<name>`
 ```
 
-For example to create a new **Vue Single Page App**, run:
+For example to create a new **Next.js statically generated React App**, run:
 
 :::sh
-npx create-net vue-spa ProjectName
+npx create-net next-static ProjectName
 :::
 
 Or download a customized project template from our Getting Started Page:
diff --git a/MyApp/_pages/templates/react-spa.md b/MyApp/_pages/templates/react-spa.md
@@ -25,13 +25,12 @@ built-in ASP.NET Core React SPA template with many new value-added and high-prod
 </div>
 </div>
 
-:::{.text-center}
-## Live Demo
-:::
-
-:::{.shadow .pb-1}
-[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/react-spa.png)](https://react-spa.react-templates.net)
-:::
+<vibe-template
+  template="react-spa"
+  title="React SPA"
+  description="A feature-rich React Single Page Application powered by Vite. Includes Blog functionality, Todos, shadcn/ui components, API Keys management, AI Chat capabilities, and Swagger UI - all integrated with a robust .NET backend."
+  href="https://react-templates.net/docs/templates/react-spa"
+  screenshot="https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/wwwroot/img/pages/react/react-spa.webp?raw=true"></vibe-template>
 
 ## ASP.NET Core React SPA Template 
 
