131 lines
4.0 KiB
Markdown
131 lines
4.0 KiB
Markdown
# CD Deploy SSH Key Setup
|
|
|
|
How to create and place the SSH key pair used by `.gitea/workflows/cd.yml` to copy `docker-compose.prod.yml` and run deploy commands on the production VM.
|
|
|
|
Related Gitea secrets: `DEPLOY_SSH_KEY`, `DEPLOY_HOST`, `DEPLOY_USER`.
|
|
|
|
---
|
|
|
|
## Who holds what
|
|
|
|
Generate the key pair **on your computer** (or any trusted machine). Split it afterward: private key → Gitea; public key → VM.
|
|
|
|
| Piece | Where it lives | Who uses it |
|
|
|-------|----------------|-------------|
|
|
| **Private key** (`vigilcare-deploy`) | Gitea secret `DEPLOY_SSH_KEY` | The **act_runner** (CD job) when it SSHs |
|
|
| **Public key** (`vigilcare-deploy.pub`) | Prod VM → `~/.ssh/authorized_keys` for `DEPLOY_USER` | The VM accepts logins that present the matching private key |
|
|
|
|
The private key does **not** need to live on the VM. The VM only needs the public half.
|
|
|
|
---
|
|
|
|
## Step by step
|
|
|
|
### 1. On your computer — create the key pair
|
|
|
|
**Windows (PowerShell):**
|
|
|
|
```powershell
|
|
ssh-keygen -t ed25519 -f vigilcare-deploy -N '""' -C "gitea-cd"
|
|
```
|
|
|
|
Windows 10/11 ships the OpenSSH client by default (`Settings → Optional features → OpenSSH Client` if it's missing). PowerShell needs the empty passphrase quoted as `'""'` — a bare `-N ""` sometimes gets swallowed by PowerShell's argument parsing and prompts for a passphrase anyway.
|
|
|
|
**Linux (Ubuntu):**
|
|
|
|
```bash
|
|
ssh-keygen -t ed25519 -f vigilcare-deploy -N "" -C "gitea-cd"
|
|
```
|
|
|
|
Both produce two files in the current folder:
|
|
|
|
- `vigilcare-deploy` — **private** (secret)
|
|
- `vigilcare-deploy.pub` — **public** (safe to copy)
|
|
|
|
### 2. On the VM — install the public key
|
|
|
|
Log into the prod VM as a user that can set up the deploy account (or as `DEPLOY_USER` if it already exists).
|
|
|
|
Copy the **public** key onto the VM, then:
|
|
|
|
```bash
|
|
# On the VM, as DEPLOY_USER (e.g. deploy)
|
|
mkdir -p ~/.ssh
|
|
chmod 700 ~/.ssh
|
|
# Paste the contents of vigilcare-deploy.pub into authorized_keys:
|
|
echo "ssh-ed25519 AAAA... gitea-cd" >> ~/.ssh/authorized_keys
|
|
chmod 600 ~/.ssh/authorized_keys
|
|
```
|
|
|
|
Or from your computer (if you already have another way to SSH in):
|
|
|
|
**Windows (PowerShell):** `ssh-copy-id` doesn't exist on Windows, so pipe the public key into the same `mkdir`/`echo`/`chmod` sequence over SSH instead:
|
|
|
|
```powershell
|
|
Get-Content vigilcare-deploy.pub | ssh deploy@YOUR_DEPLOY_HOST "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
|
|
```
|
|
|
|
**Linux (Ubuntu):**
|
|
|
|
```bash
|
|
ssh-copy-id -i vigilcare-deploy.pub deploy@YOUR_DEPLOY_HOST
|
|
```
|
|
|
|
Ensure `DEPLOY_USER` can manage `/opt/vigilcare` and run Docker (`docker compose`).
|
|
|
|
### 3. On Gitea — store the private key as a secret
|
|
|
|
Repo → **Settings** → **Actions** → **Secrets** → New secret:
|
|
|
|
- Name: `DEPLOY_SSH_KEY`
|
|
- Value: **entire contents** of `vigilcare-deploy` (including `-----BEGIN OPENSSH PRIVATE KEY-----` and the end line)
|
|
|
|
Also set:
|
|
|
|
- `DEPLOY_HOST` — hostname or IP of the VM
|
|
- `DEPLOY_USER` — that Linux user (e.g. `deploy`)
|
|
|
|
### 4. Sanity check from your computer
|
|
|
|
**Windows (PowerShell):**
|
|
|
|
```powershell
|
|
ssh -i vigilcare-deploy deploy@YOUR_DEPLOY_HOST
|
|
```
|
|
|
|
**Linux (Ubuntu):**
|
|
|
|
```bash
|
|
ssh -i vigilcare-deploy deploy@YOUR_DEPLOY_HOST
|
|
```
|
|
|
|
Same command either way — if that works without a password, CD's SSH steps will work the same way (the runner uses the same private key from the secret).
|
|
|
|
### 5. Optional cleanup on your computer
|
|
|
|
After the private key is in Gitea and you've verified SSH, you can delete the local private file if you don't want another copy. Keep the public key only if you need it again. Prefer regenerating over emailing or sharing the private key.
|
|
|
|
**Windows (PowerShell):**
|
|
|
|
```powershell
|
|
Remove-Item vigilcare-deploy
|
|
```
|
|
|
|
**Linux (Ubuntu):**
|
|
|
|
```bash
|
|
rm vigilcare-deploy
|
|
```
|
|
|
|
---
|
|
|
|
## How CD uses it
|
|
|
|
When the deploy job runs, the runner roughly does:
|
|
|
|
1. Write `secrets.DEPLOY_SSH_KEY` to `~/.ssh/id_ed25519`
|
|
2. `scp` / `ssh` as `DEPLOY_USER@DEPLOY_HOST`
|
|
3. The VM checks that private key against the public key in `authorized_keys` and allows the session
|
|
|
|
Summary: **generate on your PC → public key on the VM → private key in Gitea**.
|