POTE/GITEA_SECRETS_GUIDE.md

# 🔐 Gitea Secrets Guide for POTE

## ✅ YES! You Can Store Passwords in Gitea

Gitea has a **Secrets** feature (like GitHub Actions secrets) that lets you store passwords securely and use them in:
1. **CI/CD pipelines** (Gitea Actions workflows) ✅
2. **Deployment workflows** ✅

**BUT NOT:**
- ❌ Directly in your running application on Proxmox
- ❌ Accessed by scripts outside of workflows

---

## 🎯 What Gitea Secrets Are Good For

### ✅ Perfect Use Cases

1. **CI/CD Testing** - Run tests with real credentials
2. **Automated Deployment** - Deploy to Proxmox with SSH keys
3. **Notifications** - Send emails/Slack after builds
4. **Docker Registry** - Push images with credentials
5. **API Keys** - Access external services during builds

### ❌ NOT Good For

1. **Runtime secrets** - Your deployed app on Proxmox can't access them
2. **Local development** - Can't use secrets on your laptop
3. **Manual scripts** - Can't run `python script.py` with Gitea secrets

---

## 🔧 How to Set Up Gitea Secrets

### Step 1: Add Secrets to Gitea

1. Go to your POTE repository in Gitea
2. Click **Settings** → **Secrets** (or **Actions** → **Secrets**)
3. Click **Add Secret**

Add these secrets:

| Secret Name | Example Value | Used For |
|-------------|---------------|----------|
| `SMTP_PASSWORD` | `your_mail_password` | Email reports in CI |
| `DB_PASSWORD` | `changeme123` | Database in CI |
| `PROXMOX_HOST` | `10.0.10.95` | Deployment |
| `PROXMOX_USER` | `poteapp` | Deployment |
| `PROXMOX_SSH_KEY` | `-----BEGIN...` | Deployment |
| `SMTP_HOST` | `mail.levkin.ca` | Email config |
| `SMTP_USER` | `test@levkin.ca` | Email config |
| `FROM_EMAIL` | `test@levkin.ca` | Email config |

### Step 2: Use Secrets in Workflows

Secrets are accessed with `${{ secrets.SECRET_NAME }}` syntax.

---

## 📝 Example: CI Pipeline with Secrets

**File:** `.github/workflows/ci.yml`

```yaml
name: CI

on:
  push:
    branches: [main, master]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Run tests
        env:
          # Use Gitea secrets
          DATABASE_URL: postgresql://user:${{ secrets.DB_PASSWORD }}@localhost/db
          SMTP_HOST: ${{ secrets.SMTP_HOST }}
          SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
        run: |
          pytest tests/

      - name: Send notification
        if: failure()
        run: |
          # Send email using secrets
          python scripts/send_notification.py \
            --smtp-password "${{ secrets.SMTP_PASSWORD }}"
```

**✅ I've already updated your CI pipeline to use secrets!**

---

## 🚀 Example: Automated Deployment Workflow

Create `.github/workflows/deploy.yml`:

```yaml
name: Deploy to Proxmox

on:
  workflow_dispatch:  # Manual trigger

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Setup SSH
        env:
          SSH_KEY: ${{ secrets.PROXMOX_SSH_KEY }}
          SSH_HOST: ${{ secrets.PROXMOX_HOST }}
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan -H $SSH_HOST >> ~/.ssh/known_hosts

      - name: Deploy to Proxmox
        env:
          PROXMOX_HOST: ${{ secrets.PROXMOX_HOST }}
          PROXMOX_USER: ${{ secrets.PROXMOX_USER }}
          SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
        run: |
          # SSH to Proxmox and update
          ssh $PROXMOX_USER@$PROXMOX_HOST << 'ENDSSH'
            cd ~/pote
            git pull
            
            # Update .env with secrets
            echo "SMTP_PASSWORD=${SMTP_PASSWORD}" >> .env
            echo "DATABASE_URL=postgresql://user:${DB_PASSWORD}@localhost/db" >> .env
            
            # Restart services
            source venv/bin/activate
            alembic upgrade head
          ENDSSH

      - name: Health Check
        run: |
          ssh ${{ secrets.PROXMOX_USER }}@${{ secrets.PROXMOX_HOST }} \
            "cd ~/pote && python scripts/health_check.py"
```

---

## 🔄 How Secrets Flow to Your Server

### Option 1: Deploy Workflow Updates `.env` (Recommended)

```yaml
# In deployment workflow
- name: Update secrets on server
  run: |
    ssh user@server << 'EOF'
      cd ~/pote
      # Update .env with secrets passed from Gitea
      sed -i "s/SMTP_PASSWORD=.*/SMTP_PASSWORD=${{ secrets.SMTP_PASSWORD }}/" .env
    EOF
```

### Option 2: Use Environment Variables

```yaml
# In deployment workflow
- name: Deploy with environment variables
  run: |
    ssh user@server << 'EOF'
      cd ~/pote
      # Export secrets as environment variables
      export SMTP_PASSWORD="${{ secrets.SMTP_PASSWORD }}"
      export DB_PASSWORD="${{ secrets.DB_PASSWORD }}"
      # Run scripts
      python scripts/send_daily_report.py
    EOF
```

### Option 3: Secrets File on Server

```yaml
# In deployment workflow
- name: Create secrets file
  run: |
    ssh user@server << 'EOF'
      # Create secure secrets file
      cat > /etc/pote/secrets << 'SECRETS'
      export SMTP_PASSWORD="${{ secrets.SMTP_PASSWORD }}"
      export DB_PASSWORD="${{ secrets.DB_PASSWORD }}"
      SECRETS
      chmod 600 /etc/pote/secrets
    EOF
```

---

## 🎯 Recommended Setup for Your POTE Project

### For CI/CD (Testing):

**Use Gitea Secrets** ✅

```yaml
# .github/workflows/ci.yml (already updated!)
env:
  SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
  DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
```

### For Deployed Server (Proxmox):

**Keep using `.env` file** ✅

Why?
- Simpler for manual SSH access
- No need for complex deployment workflows
- Easy to update: just `nano .env`

**BUT:** Use Gitea secrets in a deployment workflow to UPDATE the `.env` file automatically!

---

## 🚀 Complete Workflow: Gitea → Proxmox

### 1. Store Secrets in Gitea

```
Repository Settings → Secrets:
- SMTP_PASSWORD: your_password
- PROXMOX_HOST: 10.0.10.95
- PROXMOX_SSH_KEY: (your SSH private key)
```

### 2. Create Deployment Workflow

See `.github/workflows/deploy.yml` (I'll create this next)

### 3. Trigger Deployment

```bash
# From Gitea UI:
Actions → Deploy to Proxmox → Run workflow

# Or commit and push:
git commit -m "Update code"
git push origin main
# Workflow runs automatically
```

### 4. Workflow Updates Proxmox

- SSH to Proxmox
- Pull latest code
- Update `.env` with secrets from Gitea
- Run migrations
- Health check

---

## ⚠️ Important Limitations

### Gitea Secrets CAN'T:

❌ Be accessed outside of workflows
❌ Be used in local `python script.py` runs
❌ Be read by cron jobs on Proxmox (directly)
❌ Replace `.env` for runtime application config

### Gitea Secrets CAN:

✅ Secure your CI/CD pipeline
✅ Deploy safely without exposing passwords in git
✅ Update `.env` on server during deployment
✅ Run automated tests with real credentials

---

## 🔒 Security Best Practices

### ✅ DO:

1. **Store ALL sensitive data as Gitea secrets**
   - SMTP passwords
   - Database passwords
   - API keys
   - SSH keys

2. **Use secrets in workflows**
   ```yaml
   env:
     PASSWORD: ${{ secrets.PASSWORD }}
   ```

3. **Never echo secrets**
   ```yaml
   # ❌ BAD - exposes in logs
   - run: echo "${{ secrets.PASSWORD }}"
   
   # ✅ GOOD - masked automatically
   - run: use_password "${{ secrets.PASSWORD }}"
   ```

4. **Rotate secrets regularly**
   - Update in Gitea UI
   - Re-run deployment workflow

### ❌ DON'T:

1. **Commit secrets to git** (even private repos)
2. **Share secrets via Slack/email**
3. **Use same password everywhere**
4. **Expose secrets in workflow logs**

---

## 📊 Comparison: Where to Store Secrets

| Storage | CI/CD | Deployed App | Easy Updates | Security |
|---------|-------|--------------|--------------|----------|
| **Gitea Secrets** | ✅ Perfect | ❌ No | ✅ Via workflow | ⭐⭐⭐⭐⭐ |
| **`.env` file** | ❌ No | ✅ Perfect | ✅ `nano .env` | ⭐⭐⭐ |
| **Environment Vars** | ✅ Yes | ✅ Yes | ❌ Harder | ⭐⭐⭐⭐ |
| **Both (Recommended)** | ✅ Yes | ✅ Yes | ✅ Automated | ⭐⭐⭐⭐⭐ |

---

## 🎯 My Recommendation for You

### Use BOTH:

1. **Gitea Secrets** - For CI/CD and deployment workflows
2. **`.env` file** - For runtime on Proxmox

### Workflow:

```
1. Store password in Gitea Secrets
2. Commit code changes
3. Push to Gitea
4. Workflow runs:
   - Tests with Gitea secrets ✅
   - Deploys to Proxmox ✅
   - Updates .env with secrets ✅
5. Proxmox app reads from .env ✅
```

**This gives you:**
- ✅ Secure CI/CD
- ✅ Easy manual SSH access
- ✅ Automated deployments
- ✅ No passwords in git

---

## 🚀 Next Steps

### 1. Add Secrets to Gitea (5 minutes)

```
1. Go to https://git.levkin.ca/ilia/POTE/settings/secrets
2. Add:
   - SMTP_PASSWORD: your_mail_password
   - DB_PASSWORD: changeme123
   - SMTP_HOST: mail.levkin.ca
   - SMTP_USER: test@levkin.ca
   - FROM_EMAIL: test@levkin.ca
```

### 2. Test CI Pipeline (Already Updated!)

```bash
git push origin main
# Watch Actions tab in Gitea
# CI should use secrets automatically
```

### 3. Create Deployment Workflow (Optional)

I can create `.github/workflows/deploy.yml` if you want automated deployments!

---

## 💡 Quick Commands

### Add SSH Key to Gitea (for deployment):

```bash
# On your local machine
cat ~/.ssh/id_rsa  # Copy this

# In Gitea:
Repository → Settings → Secrets → Add Secret
Name: PROXMOX_SSH_KEY
Value: (paste private key)
```

### Test Gitea Secrets:

```bash
# Push a test commit
git commit --allow-empty -m "Test secrets"
git push

# Check Gitea Actions tab
# Look for green checkmarks ✅
```

---

## 📚 See Also

- **[docs/13_secrets_management.md](docs/13_secrets_management.md)** - All secrets options
- **[.github/workflows/ci.yml](.github/workflows/ci.yml)** - Updated with secrets support
- **[DEPLOYMENT_AND_AUTOMATION.md](DEPLOYMENT_AND_AUTOMATION.md)** - Full deployment guide

---

## ✅ Summary

**YES, use Gitea secrets!** They're perfect for:
- ✅ CI/CD pipelines
- ✅ Automated deployments
- ✅ Keeping passwords out of git

**But ALSO keep `.env` on Proxmox** for:
- ✅ Runtime application config
- ✅ Manual SSH access
- ✅ Cron jobs

**Best of both worlds:** Gitea secrets deploy and update the `.env` file automatically! 🚀