# 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**.