Deploying with Kamal

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.

Overview​

Kamal enables simple commands to deploy containerized applications to Linux hosts, handling:

• 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

Hosting Recommendation​

If you don't have a Linux Server, we recommend Hetzner who we've found offers the best value US Cloud VMs 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​

• A domain name
• A Linux host (e.g., VPS from providers like Hetzner)
• GitHub account for CI/CD

Initial Setup​

1. Create a new ServiceStack application:

2. Create the SSH Private and Public Keys:

3. Copy Public Key to deployment server to enable SSH access:

4. Configure GitHub Secrets for Kamal to access your deployment server:

• SSH private key to access the server: ssh-rsa ...

• IP address of the server to deploy to: 100.100.100.100

• Email for Let's Encrypt SSL certificate: me@example.org

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:

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

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. E.g:

JSON Patch to apply to appsettings.json:

JSON Patch example:

[
    {
        "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.

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:

Which is triggered after a commit to main:

• build.yml - Builds and tests the application, triggered on push to main
• build-container.yml - Builds a Docker image from the application and pushes it to GitHub Container Registry
• release.yml - Runs any pending DB Migrations, if successful Deploys the Docker image to server

Your App's Kamal deployment is configured in config/deploy.yml with additional Kamal hooks and configuration in .kamal, see Kamal documentation for more information.

Configuration​

The /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.

The authentication between GitHub Container Registry (ghcr.io) and your server is handled by the GitHub Actions workflow, the deploy.yml and Kamal 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:

# Required for Kamal deploy.yml template processing

GITHUB_REPOSITORY=acme/example.org

# Server deployment details
KAMAL_DEPLOY_IP=100.100.100.100
KAMAL_DEPLOY_HOST=example.org

# Container registry credentials (for ghcr.io)
KAMAL_REGISTRY_USERNAME=my-user
GITHUB_TOKEN=ghp_xxx

# Login to GitHub Container Registry
#echo $KAMAL_REGISTRY_PASSWORD | docker login ghcr.io -u my-user --password-stdin

You can then load the environment variables into your shell with:

Which will allow you to use kamal locally to access your deployment server, e.g:

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:

• View deployment details

• Check application logs

• Deploy new version

• Restart application

Additional Containers​

Kamal supports extensive configuration options including "accessories" for additional features like databases, caches, and more. See the Kamal documentation for more information.

Troubleshooting​

Initial deployment fails​

If you are having issues with the initial deployment, an earlier bootstrap of the server via GitHub Actions may have failed. Delete the .<app-name> file in your deployment user's home directory and re-run the GitHub Actions workflow to re-bootstrap the server.

Missing the service label​

If you are getting:

Image ghcr.io/netcoreapps/northwindauto:latest is missing the 'service' label

Ensure your AppHost csproj has ContainerLabel with the value matching the service in your deploy.yml.