|
1 | | -# ServiceStack mix GitHub Actions |
2 | | -`release.yml` generated from `x mix release-ghr-vanilla`, this template in designed to help with CI deployment to a dedicated server with SSH access. |
3 | | - |
4 | | -## Overview |
5 | | -`release.yml` is designed to work with a ServiceStack app deploying directly to a single server via SSH. A docker image is built and stored on GitHub's `ghcr.io` docker registry when a GitHub Release is created. |
6 | | - |
7 | | -GitHub Actions specified in `release.yml` then copy files remotely via scp and use `docker-compose` to run the app remotely via SSH. |
8 | | - |
9 | | -## Deployment server setup |
10 | | -To get this working, a server needs to be setup with the following: |
11 | | - |
12 | | -- SSH access |
13 | | -- docker |
14 | | -- docker-compose |
15 | | -- ports 443 and 80 for web access of your hosted application |
16 | | - |
17 | | -This can be your own server or any cloud hosted server like Digital Ocean, AWS, Azure etc. |
18 | | - |
19 | | -When setting up your server, you'll want to use a dedicated SSH key for access to be used by GitHub Actions. GitHub Actions will need the *private* SSH key within a GitHub Secret to authenticate. This can be done via ssh-keygen and copying the public key to the authorized clients on the server. |
20 | | - |
21 | | -To let your server handle multiple ServiceStack applications and automate the generation and management of TLS certificates, an additional docker-compose file is provided via the `x mix` template, `nginx-proxy-compose.yml`. This docker-compose file is ready to run and can be copied to the deployment server. |
22 | | - |
23 | | -For example, once copied to remote `~/nginx-proxy-compose.yml`, the following command can be run on the remote server. |
24 | | - |
25 | | -``` |
26 | | -docker-compose -f ~/nginx-proxy-compose.yml up -d |
27 | | -``` |
28 | | - |
29 | | -This will run an nginx reverse proxy along with a companion container that will watch for additional containers in the same docker network and attempt to initialize them with valid TLS certificates. |
30 | | - |
31 | | -## GitHub Repository setup |
32 | | -The `release.yml` uses the following secrets. |
33 | | - |
34 | | -- DEPLOY_HOST - hostname used to SSH to, this can either be an IP address or subdomain with A record pointing to the server. |
35 | | -- DEPLOY_USERNAME - the username being logged into via SSH. Eg, `ubuntu`, `ec2-user`, `root` etc. |
36 | | -- DEPLOY_KEY - SSH private key used to remotely access deploy server/app host. |
37 | | -- LETSENCRYPT_EMAIL - Email address, required for Let's Encrypt automated TLS certificates. |
38 | | - |
39 | | -These secrets can use the [GitHub CLI](https://cli.github.com/manual/gh_secret_set) for ease of creation. Eg, using the GitHub CLI the following can be set. |
40 | | - |
41 | | -```bash |
42 | | -gh secret set DEPLOY_HOST -b"<DEPLOY_HOST, domain or subdomain for your application and server host.>" |
43 | | -gh secret set DEPLOY_USERNAME -b"<DEPLOY_USERNAME, the username being logged into via SSH. Eg, `ubuntu`, `ec2-user`, `root` etc.>" |
44 | | -gh secret set DEPLOY_KEY -b"<DEPLOY_KEY, SSH private key used to remotely access deploy server/app host.>" |
45 | | -gh secret set LETSENCRYPT_EMAIL -b "<LETSENCRYPT_EMAIL, Email address for your TLS certificate generation, eg [email protected]>" |
46 | | -``` |
47 | | - |
48 | | -These secrets are used to populate variables within GitHub Actions and other configuration files. |
49 | | - |
50 | | -## What's the process of `release.yml`? |
51 | | - |
52 | | - |
| 1 | +## Overview |
| 2 | + |
| 3 | +This template uses the deployment configurations for a ServiceStack .NET 8 application. The application is containerized using Docker and is set up to be automatically built and deployed via GitHub Actions. The recommended deployment target is a stand-alone Linux server running Ubuntu, with an NGINX reverse proxy also containerized using Docker, which a Docker Compose file is included in the template under the `.deploy` directory. |
| 4 | + |
| 5 | +### Highlights |
| 6 | +- 🌐 **NGINX Reverse Proxy**: Utilizes an NGINX reverse proxy to handle web traffic and SSL termination. |
| 7 | +- 🚀 **GitHub Actions**: Leverages GitHub Actions for CI/CD, pushing Docker images to GitHub Container Registry and deploying them on a remote server. |
| 8 | +- 🐳 **Dockerized ServiceStack App**: The application is containerized, with the image built using `.NET 8`. |
| 9 | +- 🔄 **Automated Migrations**: Includes a separate service for running database migrations. |
| 10 | + |
| 11 | +### Technology Stack |
| 12 | +- **Web Framework**: ServiceStack |
| 13 | +- **Language**: C# (.NET 8) |
| 14 | +- **Containerization**: Docker |
| 15 | +- **Reverse Proxy**: NGINX |
| 16 | +- **CI/CD**: GitHub Actions |
| 17 | +- **OS**: Ubuntu 22.04 (Deployment Server) |
| 18 | + |
| 19 | + |
| 20 | + |
| 21 | +## Deployment Server Setup |
| 22 | + |
| 23 | +To successfully host your ServiceStack applications, there are several components you need to set up on your deployment server. This guide assumes you're working on a standalone Linux server (Ubuntu is recommended) with SSH access enabled. |
| 24 | + |
| 25 | +### Prerequisites |
| 26 | + |
| 27 | +1. **SSH Access**: Required for GitHub Actions to communicate with your server. |
| 28 | +2. **Docker**: To containerize your application. |
| 29 | +3. **Docker-Compose**: For orchestrating multiple containers. |
| 30 | +4. **Ports**: 80 and 443 should be open for web access. |
| 31 | +5. **nginx-reverse-proxy**: For routing traffic to multiple ServiceStack applications and managing TLS certificates. |
| 32 | + |
| 33 | +You can use any cloud-hosted or on-premises server like Digital Ocean, AWS, Azure, etc., for this setup. |
| 34 | + |
| 35 | +### Step-by-Step Guide |
| 36 | + |
| 37 | +#### 1. Install Docker and Docker-Compose |
| 38 | + |
| 39 | +It is best to follow the [latest installation instructions on the Docker website](https://docs.docker.com/engine/install/ubuntu/) to ensure to have the correct setup with the latest patches. |
| 40 | + |
| 41 | +#### 2. Configure SSH for GitHub Actions |
| 42 | + |
| 43 | +Generate a dedicated SSH key pair to be used by GitHub Actions: |
| 44 | + |
| 45 | +```bash |
| 46 | +ssh-keygen -t rsa -b 4096 -f ~/.ssh/github_actions |
| 47 | +``` |
| 48 | + |
| 49 | +Add the public key to the `authorized_keys` file on your server: |
| 50 | + |
| 51 | +```bash |
| 52 | +cat ~/.ssh/github_actions.pub >> ~/.ssh/authorized_keys |
| 53 | +``` |
| 54 | + |
| 55 | +Then, add the *private* key to your GitHub Secrets as `DEPLOY_KEY` to enable GitHub Actions to SSH into the server securely. |
| 56 | + |
| 57 | +#### 3. Set Up nginx-reverse-proxy |
| 58 | + |
| 59 | +You should have a `docker-compose` file similar to the `nginx-proxy-compose.yml` in your repository. Upload this file to your server: |
| 60 | + |
| 61 | +```bash |
| 62 | +scp nginx-proxy-compose.yml user@your_server:~/ |
| 63 | +``` |
| 64 | + |
| 65 | +To bring up the nginx reverse proxy and its companion container for handling TLS certificates, run: |
| 66 | + |
| 67 | +```bash |
| 68 | +docker compose -f ~/nginx-proxy-compose.yml up -d |
| 69 | +``` |
| 70 | + |
| 71 | +This will start an nginx reverse proxy along with a companion container. They will automatically watch for additional Docker containers on the same network and initialize them with valid TLS certificates. |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | +## GitHub Repository Setup |
| 76 | + |
| 77 | +Configuring your GitHub repository is an essential step for automating deployments via GitHub Actions. This guide assumes you have a `release.yml` workflow file in your repository's `.github/workflows/` directory, and your deployment server has been set up according to the [Deployment Server Setup](#Deployment-Server-Setup) guidelines. |
| 78 | + |
| 79 | +### Secrets Configuration |
| 80 | + |
| 81 | +Your GitHub Actions workflow requires the following secrets to be set in your GitHub repository: |
| 82 | + |
| 83 | +1. **`DEPLOY_HOST`**: The hostname for SSH access. This can be either an IP address or a domain with an A-record pointing to your server. |
| 84 | +2. **`DEPLOY_USERNAME`**: The username for SSH login. Common examples include `ubuntu`, `ec2-user`, or `root`. |
| 85 | +3. **`DEPLOY_KEY`**: The SSH private key to securely access the deployment server. This should be the same key you've set up on your server for GitHub Actions. |
| 86 | +4. **`LETSENCRYPT_EMAIL`**: Your email address, required for Let's Encrypt automated TLS certificates. |
| 87 | + |
| 88 | +#### Using GitHub CLI for Secret Management |
| 89 | + |
| 90 | +You can conveniently set these secrets using the [GitHub CLI](https://cli.github.com/manual/gh_secret_set) like this: |
| 91 | + |
| 92 | +```bash |
| 93 | +gh secret set DEPLOY_HOST --body="your-host-or-ip" |
| 94 | +gh secret set DEPLOY_USERNAME --body="your-username" |
| 95 | +gh secret set DEPLOY_KEY --bodyFile="path/to/your/ssh-private-key" |
| 96 | +gh secret set LETSENCRYPT_EMAIL --body= "[email protected]" |
| 97 | +``` |
| 98 | + |
| 99 | +These secrets will populate environment variables within your GitHub Actions workflow and other configuration files, enabling secure and automated deployment of your ServiceStack applications. |
0 commit comments