Ssh setup for gitea cd

2026-08-06 17:16:07 +08:00
parent de7f792947
commit cd29c57b55
1 changed files with 92 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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
+
+```bash
+ssh-keygen -t ed25519 -f vigilcare-deploy -N "" -C "gitea-cd"
+```
+
+That creates 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):
+
+```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
+
+```bash
+ssh -i vigilcare-deploy deploy@YOUR_DEPLOY_HOST
+```
+
+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.
+
+---
+
+## 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**.