diff --git a/CICD_SETUP.md b/CICD_SETUP.md index 8b18e84..c8d9918 100644 --- a/CICD_SETUP.md +++ b/CICD_SETUP.md @@ -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 - ``` - 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**.