diff --git a/CICD_SETUP.md b/CICD_SETUP.md
new file mode 100644
index 0000000..8b18e84
--- /dev/null
+++ b/CICD_SETUP.md
@@ -0,0 +1,133 @@
+# 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`).
+
+---
+
+## 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:
+
+```bash
+ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy
+```
+
+Copy the **public key** (`gitea_deploy.pub`) to your production server:
+
+```bash
+ssh-copy-id -i ~/.ssh/gitea_deploy.pub user@your-server
+```
+
+Or manually append it to `~/.ssh/authorized_keys` on the server.
+
+---
+
+## Step 3 — Add Secrets in Gitea
+
+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:
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+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
+        run: |
+          cd /path/to/grateful-journal   # <-- update this path
+          bash deploy.sh
+```
+
+This is simpler and avoids managing SSH keys.
+
+---
+
+## 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
+
+If the runner isn't picking up jobs, check that the runner is online in Site Administration → Runners.