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):

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):

cat ~/.ssh/gitea_deploy_honey_be.pub

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

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):

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:

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):

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):

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):

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:

chmod 600 ~/.ssh/authorized_keys

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

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:

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:

   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:

   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:

docker ps

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

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:

docker exec -it gitea_runner sh

Inside the container:

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:

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):

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.