honey-be/docs/GITEA_VPS_DEPLOY.md

# Gitea Actions: Deploy honey-be to VPS on push to main

This guide sets up automatic deployment of **honey-be** to your Honey VPS (188.116.23.7) when you push to the `main` branch. The workflow runs on your Gitea runner, syncs the repo via rsync over SSH, then runs the rolling-update script on the VPS.

## Prerequisites

- Gitea with Actions enabled and at least one runner registered (e.g. `ubuntu-latest`).
- Honey VPS (188.116.23.7) with backend at `/opt/app/backend/honey-be` and `scripts/rolling-update.staged.sh`.
- The **Gitea server (or the machine where the runner runs)** must be able to reach 188.116.23.7 over the network (e.g. outbound SSH). Gitea itself can stay Tailscale-only.

---

## 1. Create the deploy SSH key on your Mac

**Where:** Local Mac (Terminal).

**1.1** Generate a dedicated deploy key (Ed25519, no passphrase):

```bash
ssh-keygen -t ed25519 -C "gitea-deploy-honey-be" -f ~/.ssh/gitea_deploy_honey_be -N ""
```

**1.2** Where the keys are on your Mac:

| File on your Mac | Purpose |
|------------------|--------|
| `~/.ssh/gitea_deploy_honey_be` | **Private key** — you will paste this into Gitea (Step 3). Never put this on the Staged VPS. |
| `~/.ssh/gitea_deploy_honey_be.pub` | **Public key** — you will put this on the Staged VPS (Step 2). |

**1.3** Optional: display the keys so you can copy them later.

To show the **public** key (for Step 2):

```bash
cat ~/.ssh/gitea_deploy_honey_be.pub
```

To show the **private** key (for Step 3 — paste into Gitea):

```bash
cat ~/.ssh/gitea_deploy_honey_be
```

Copy each output as a whole (including `ssh-ed25519 ...` for the public key and `-----BEGIN ... KEY-----` / `-----END ... KEY-----` for the private key). You can run these commands again anytime.

---

## 2. Put the public key on the Staged VPS

The **Staged VPS** is your Honey server: **188.116.23.7**. The Gitea runner will SSH into this machine as `root` (or your deploy user), so the **public** key must be in that user’s `authorized_keys` on the Staged VPS.

**2.1 — On your Local Mac:** Copy the public key to the clipboard (so you can paste it on the VPS):

```bash
cat ~/.ssh/gitea_deploy_honey_be.pub | pbcopy
```

Or just note the single line that looks like:  
`ssh-ed25519 AAAAC3... gitea-deploy-honey-be`

**2.2 — Log in to the Staged VPS** from your Mac:

```bash
ssh root@188.116.23.7
```

(Use the same user you normally use to manage this server, e.g. `root` or a user with sudo. If you use a different user, replace `root` in the next steps with that user.)

**2.3 — On the Staged VPS (188.116.23.7):** Ensure `.ssh` exists and add the public key.

Run these commands **one by one** on the Staged VPS (after you’re logged in via SSH):

```bash
mkdir -p ~/.ssh
chmod 700 ~/.ssh
```

Then add the public key. **Either** paste the line you copied (replace `PASTE_YOUR_PUBLIC_KEY_LINE_HERE` with the actual line):

```bash
echo 'PASTE_YOUR_PUBLIC_KEY_LINE_HERE' >> ~/.ssh/authorized_keys
```

**Or**, if you have the key in your Mac clipboard, on the Staged VPS you can do (from Mac, one line):

```bash
ssh root@188.116.23.7 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo '$(cat ~/.ssh/gitea_deploy_honey_be.pub)' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
```

If you ran the `echo ... >> authorized_keys` manually on the VPS, set permissions:

```bash
chmod 600 ~/.ssh/authorized_keys
```

**2.4 — Verify from your Mac:** Check that the deploy key can log in without a password:

```bash
ssh -i ~/.ssh/gitea_deploy_honey_be root@188.116.23.7 "echo OK"
```

You should see `OK`. If you get "Permission denied (publickey)", the public key was not added correctly to `~/.ssh/authorized_keys` on the Staged VPS.

---

## 3. Put the private key into Gitea (repository secret)

**Where:** Private key stays on your Mac; you only **paste its contents** into Gitea in the browser.

**3.1 — On your Local Mac:** Show the private key so you can copy it:

```bash
cat ~/.ssh/gitea_deploy_honey_be
```

Copy the **entire** output, including:

- `-----BEGIN OPENSSH PRIVATE KEY-----`
- all lines in the middle
- `-----END OPENSSH PRIVATE KEY-----`

**3.2 — In Gitea (browser):** Add it as a repository secret.

1. Open your repo: `http://100.122.146.65:3000/admin/honey-be` (or your Gitea URL over Tailscale).
2. Go to **Settings** → **Secrets and Variables** → **Actions**.
3. Under **Repository Secrets**, click **Add Secret**.
4. **Name:** `DEPLOY_SSH_PRIVATE_KEY`
5. **Value:** Paste the full private key you copied from the previous command.
6. Save.

Optional secrets (workflow has defaults):

| Name | Value | When to set |
|------|--------|-------------|
| `DEPLOY_VPS_HOST` | `188.116.23.7` | Only if your Staged VPS has a different IP. |
| `DEPLOY_VPS_USER` | `root` | Only if the deploy user is not `root`. |

---

## 4. Add the workflow file to the repo and push it

The workflow is a YAML file that tells Gitea **what to do** when you push to `main`. It does not get “installed” anywhere except inside the repository.

**4.1 — What the file is and where it lives**

- **Path in repo:** `.gitea/workflows/deploy-vps.yaml`
- **What it does:** On every push to `main`, Gitea runs a job that: checks out the code → installs SSH/rsync → syncs the repo to the Staged VPS at `/opt/app/backend/honey-be` → runs `sudo ./scripts/rolling-update.staged.sh` on the VPS.
- Gitea only runs workflows that exist **on the branch you push**. So this file must be committed and pushed to `main`.

**4.2 — What you need to do**

**Where:** Local Mac (in your honey-be project directory).

1. Confirm the workflow file exists:

   ```bash
   cd /path/to/your/honey-be
   ls -la .gitea/workflows/deploy-vps.yaml
   ```

2. If it’s there, add it to git, commit, and push to `main`:

   ```bash
   git add .gitea/workflows/deploy-vps.yaml
   git commit -m "Add VPS deploy workflow"
   git push origin main
   ```

3. If the file is not there, create the directory and the file (the file contents are in this repo), then run the same `git add` / `git commit` / `git push` as above.

After the push, Gitea will see the workflow. It will run **only when** a runner is available (Step 5). So you can push the workflow first and set up the runner next, or the other way around.

---

## 5. Set up Gitea Actions and the runner

Gitea needs **Actions enabled** and at least one **runner** registered. The runner is the machine (or container) that actually runs the workflow steps. Your Gitea runs on a VPS with Docker; the runner is usually the **act_runner** container next to Gitea.

**5.1 — Enable Actions (if not already)**

**Where:** Gitea in the browser (admin or repo).

- **Site-wide:** Log in as admin → **Site Administration** → **Actions** → enable **Enable Actions**.
- Or at **repo level:** open **honey-be** → **Settings** → **Actions** → enable if there is an option.

**5.2 — Ensure the runner container is running**

**Where:** Gitea VPS (the server where Gitea’s Docker runs, e.g. 100.122.146.65 over Tailscale).

SSH into the Gitea server and check that both `gitea` and `gitea_runner` (or your runner container name) are up:

```bash
docker ps
```

You should see something like `gitea` and `gitea_runner`. If the runner container is stopped:

```bash
cd ~/gitea   # or wherever your docker-compose.yml is
docker compose up -d
```

**5.3 — Get the runner registration token from Gitea**

**Where:** Gitea in the browser.

1. Open the **honey-be** repository.
2. Go to **Settings** → **Actions** → **Runners**.
3. Click **Create new runner** (or **Add runner** / **Register runner**).
4. Gitea will show a **registration token** and often a command or instructions. Copy the token (you’ll use it in the next step if the runner is not already registered).

**5.4 — Register the runner (if it isn’t already)**

**Where:** Gitea VPS (SSH).

Your `docker-compose` may already set `GITEA_RUNNER_REGISTRATION_TOKEN` and the runner registers on startup. Check in Gitea: **Settings** → **Actions** → **Runners**. If you see a runner with status **Idle** and label **ubuntu-latest**, you can skip to 5.5.

If no runner appears, register it manually on the Gitea VPS:

```bash
docker exec -it gitea_runner sh
```

Inside the container:

```bash
act_runner register --instance http://server:3000 --token PASTE_TOKEN_FROM_STEP_5.3
```

Use the token from step 5.3. For `--instance` use the URL your runner uses to reach Gitea (in your compose it’s `http://127.0.0.1:3000` from the host; from inside the runner container it might be `http://server:3000` if the service name is `server`). Then exit and restart the runner container so it runs the daemon:

```bash
exit
docker restart gitea_runner
```

**5.5 — Check that the runner has the right label**

**Where:** Gitea in the browser.

1. Go to **honey-be** → **Settings** → **Actions** → **Runners**.
2. You should see at least one runner with:
   - **Status:** Idle (or Running when a job is active)
   - **Labels:** must include **ubuntu-latest**, because the workflow file has `runs-on: ubuntu-latest`.

If your runner has a different label (e.g. `linux`), you have two options:

- **Option A:** In Gitea when registering the runner, add the label **ubuntu-latest** (if the UI lets you choose labels).
- **Option B:** Edit `.gitea/workflows/deploy-vps.yaml` and change the line `runs-on: ubuntu-latest` to your runner’s label (e.g. `runs-on: linux`), then commit and push.

**5.6 — Summary**

- Actions enabled in Gitea.
- Runner container running on the Gitea VPS.
- Runner registered and visible under **Settings** → **Actions** → **Runners** with label **ubuntu-latest** (or workflow updated to match your label).

---

## 6. Test the deployment

Do this **after** the workflow file is on `main` (Step 4) and the runner is set up (Step 5).

**6.1 — Trigger a run**

Push a commit to `main` (e.g. a small change or the workflow/docs you added):

```bash
cd /path/to/your/honey-be
git add .gitea/workflows/deploy-vps.yaml docs/GITEA_VPS_DEPLOY.md
git commit -m "Add VPS deploy workflow and guide"
git push origin main
```

**6.2 — Check the run in Gitea**

**Where:** Gitea in the browser.

1. Open **honey-be** → **Actions** (tab in the repo).
2. You should see a run for the “Deploy to VPS” workflow. Open it.
3. Confirm all steps are green. If something fails, open the failed step to see the log.

**6.3 — Check the Staged VPS**

**Where:** Staged VPS (188.116.23.7) or your Mac (SSH to VPS).

1. SSH in: `ssh root@188.116.23.7`
2. Check that code was updated: `ls -la /opt/app/backend/honey-be`
3. Check that the app restarted: `docker ps` (or your usual way to verify the backend is running).

---

## Troubleshooting

- **Permission denied (publickey)**  
  Check: public key in `authorized_keys` on VPS, private key in `DEPLOY_SSH_PRIVATE_KEY`, no extra spaces/newlines when pasting.

- **Runner doesn’t pick up the job**  
  In Gitea: **Settings** → **Actions** → **Runners**. Confirm runner is “idle” and has label `ubuntu-latest`.

- **rsync or SSH fails from runner**  
  From the **runner host** (Gitea VPS), test: `ssh -i /path/to/private_key root@188.116.23.7 "echo OK"`. If it fails, the runner cannot reach the VPS or the key is wrong.

- **sudo or script fails on VPS**  
  SSH in as the deploy user and run manually:  
  `cd /opt/app/backend/honey-be && sudo ./scripts/rolling-update.staged.sh`  
  Fix permissions or sudo rules as needed.