jeet/grateful-journal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update CICD_SETUP.md

Browse Source
This commit is contained in:
Jeet Debnath
2026-04-08 11:19:01 +05:30
parent eefdf32aa8
commit df9f5dc12b
1 changed files with 85 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
CICD_SETUP.md
View File

@@ -1,77 +1,78 @@
# CI/CD Setup — Gitea Actions (Auto Deploy)
This doc covers how to set up automatic deployment to your production server whenever you push to `main`. The deploy runs `deploy.sh` (`git pull && docker-compose down && docker-compose up -d --build`).
This doc covers how to set up automatic deployment to your VPS whenever you push to `main`. The deploy runs `deploy.sh` (`git pull && docker-compose down && docker-compose up -d --build`).
The runner is installed **directly on the VPS** — no SSH keys needed.
---
## Prerequisites
### On Gitea
- Gitea Actions must be enabled (check Site Administration → Configuration)
- At least one Actions runner must be registered and online
### On the Production Server
- Docker and docker-compose installed
- The repo already cloned at a known path
- SSH access configured
---
## Step 1 — Install a Gitea Actions Runner
If you don't already have a runner:
1. Download the runner binary from your Gitea instance or from the Gitea releases page
2. Register it:
```
./act_runner register --instance https://your-gitea-url --token <runner-token>
```
Get the token from: Gitea → Site Administration → Runners → Create Runner
3. Start the runner:
```
./act_runner daemon
```
Consider running it as a systemd service so it survives reboots.
---
## Step 2 — Set Up SSH Key for Deployment
On your local machine or CI machine, generate a dedicated deploy key:
## Step 1 — Install act_runner on your VPS
```bash
ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy
wget https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-linux-amd64
chmod +x act_runner-linux-amd64
mv act_runner-linux-amd64 /usr/local/bin/act_runner
```
Copy the **public key** (`gitea_deploy.pub`) to your production server:
---
## Step 2 — Get a runner token from Gitea
Go to: **Gitea repo → Settings → Actions → Runners → Create Runner**
Copy the token shown.
---
## Step 3 — Register the runner on your VPS
```bash
ssh-copy-id -i ~/.ssh/gitea_deploy.pub user@your-server
act_runner register \
--instance https://YOUR_GITEA_URL \
--token YOUR_RUNNER_TOKEN \
--name vps-runner \
--labels ubuntu-latest
```
Or manually append it to `~/.ssh/authorized_keys` on the server.
---
## Step 4 — Run it as a systemd service
```bash
nano /etc/systemd/system/act_runner.service
```
Paste:
```ini
[Unit]
Description=Gitea Act Runner
After=network.target
[Service]
ExecStart=/usr/local/bin/act_runner daemon
WorkingDirectory=/root
Restart=always
[Install]
WantedBy=multi-user.target
```
Enable and start:
```bash
systemctl daemon-reload
systemctl enable --now act_runner
```
---
## Step 3 — Add Secrets in Gitea
## Step 5 — Create the workflow file
Go to: your repo → Settings → Secrets → Add Secret
| Secret Name | Value |
|------------------|--------------------------------------------|
| `DEPLOY_HOST` | IP address or hostname of your server |
| `DEPLOY_USER` | SSH username (e.g. `ubuntu`, `root`) |
| `DEPLOY_SSH_KEY` | Full contents of the **private** key file |
| `DEPLOY_PORT` | SSH port (default: `22`) |
---
## Step 4 — Create the Workflow File
Create `.gitea/workflows/deploy.yml` in the repo root:
File is already at `.gitea/workflows/deploy.yml`:
```yaml
name: Deploy
name: Deploy to VPS
on:
push:
@@ -82,52 +83,42 @@ jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy via SSH
uses: appleboy/ssh-action@v1.0.3
with:
host: ${{ secrets.DEPLOY_HOST }}
username: ${{ secrets.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_SSH_KEY }}
port: ${{ secrets.DEPLOY_PORT }}
script: |
cd /path/to/grateful-journal # <-- update this path
bash deploy.sh
```
Update the `cd` path to wherever the repo lives on your server.
---
## Alternative — Runner Running Directly on the Server
If your Gitea Actions runner is already installed on the production server itself, you can skip SSH entirely and simplify the workflow:
```yaml
name: Deploy
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Run deploy script
- name: Deploy
run: |
cd /path/to/grateful-journal # <-- update this path
cd /path/to/grateful-journal
bash deploy.sh
```
This is simpler and avoids managing SSH keys.
Update `/path/to/grateful-journal` to the actual path on your VPS where the repo is cloned.
---
## Verifying It Works
## Step 6 — Make sure the repo is cloned on your VPS
```bash
git clone https://YOUR_GITEA_URL/username/grateful-journal.git
```
Skip if already cloned.
---
## How it works
```
Push to main
→ Gitea triggers the workflow
→ act_runner (on VPS) picks up the job
→ Runs deploy.sh in place: git pull + docker-compose rebuild
→ App is live
```
---
## Verifying it works
1. Push a commit to `main`
2. Go to your repo → Actions tab in Gitea
3. You should see the workflow run and each step's log output
2. Go to **Gitea repo → Actions tab**
3. You should see the workflow run with step-by-step logs
If the runner isn't picking up jobs, check that the runner is online in Site Administration → Runners.
If the runner isn't picking up jobs, check it's online at **Site Administration → Runners**.