|
| 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="your-email@example.com" |
| 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