homarr-dashboard/GITEA_SETUP.md

# 🦊 Gitea Repository Setup Guide

This guide will help you set up a Gitea repository for your Homarr dashboard configuration, enabling easy deployment and version-controlled updates.

## 📋 Prerequisites

- Gitea instance running (e.g., `gitea.lemonlink.eu`)
- Git installed on your server
- Docker and Docker Compose installed

---

## 🚀 Setup Steps

### 1. Create Repository in Gitea

1. Navigate to your Gitea instance: `https://gitea.lemonlink.eu`
2. Create a new organization (optional): `homelab`
3. Create new repository:
   - **Repository Name**: `homarr-dashboard`
   - **Description**: "Homarr dashboard configuration with system monitoring"
   - **Visibility**: Private (recommended)
   - **Initialize**: Yes, with README

### 2. Push Configuration to Gitea

```bash
# On your local machine (where you created the files)
cd homarr-deploy

# Initialize git repo (if not already done)
git init

# Add Gitea remote
git remote add origin https://gitea.lemonlink.eu/homelab/homarr-dashboard.git

# Or if using SSH:
# git remote add origin git@gitea.lemonlink.eu:homelab/homarr-dashboard.git

# Add all files
git add .

# Commit
git commit -m "Initial Homarr dashboard configuration

Features:
- Homarr 1.0 beta with dark theme
- Dash. system monitoring
- 60+ pre-configured apps
- RSS feeds for homelab, cyber, tech news
- Nginx Proxy Manager ready
- Watchtower auto-updates"

# Push to Gitea
git push -u origin main
```

### 3. Deploy on Your Server

SSH into your server and run:

```bash
# Create directory
mkdir -p /opt/homelab
cd /opt/homelab

# Clone repository
git clone https://gitea.lemonlink.eu/homelab/homarr-dashboard.git
# Or with SSH:
# git clone git@gitea.lemonlink.eu:homelab/homarr-dashboard.git

cd homarr-dashboard

# Configure environment
cp .env.example .env
nano .env  # Edit with your settings

# Ensure NPM network exists
docker network create npm-network 2>/dev/null || true

# Deploy
docker compose up -d
```

---

## 🔄 Update Workflow

### Method 1: Pull Updates on Server

```bash
cd /opt/homelab/homarr-dashboard
git pull
docker compose up -d
```

### Method 2: Using Update Script

The included `update.sh` script automates this:

```bash
# Make executable and run
chmod +x update.sh
./update.sh
```

### Method 3: Automatic Updates (Webhook)

Set up a Gitea webhook to auto-deploy on push:

**In Gitea:**
1. Repository → Settings → Webhooks
2. Add Webhook → Gitea
3. Target URL: `https://deploy.lemonlink.eu/webhook/homarr`
4. Secret: Generate a secure secret
5. Events: Push

**On Server (optional):** Set up a simple webhook listener or use a CI/CD tool like Drone CI.

---

## 🔐 NPM Configuration

### Add Proxy Hosts in NPM

#### 1. Dashboard (Homarr)

| Setting | Value |
|---------|-------|
| Domain Names | `dashboard.lemonlink.eu` |
| Scheme | `http` |
| Forward Hostname/IP | `homarr` |
| Forward Port | `7575` |
| Cache Assets | ✅ |
| Block Common Exploits | ✅ |

**SSL Tab:**
- SSL Certificate: Request a new SSL certificate
- Accept Terms: ✅
- Force SSL: ✅
- HTTP/2 Support: ✅
- HSTS Enabled: ✅

#### 2. System Monitor (Dash.)

| Setting | Value |
|---------|-------|
| Domain Names | `system.lemonlink.eu` |
| Scheme | `http` |
| Forward Hostname/IP | `dash` |
| Forward Port | `3001` |

**SSL Tab:** Same as above

### Ensure NPM Network Exists

```bash
# Check if network exists
docker network ls | grep npm-network

# Create if missing
docker network create npm-network
```

---

## 📁 Repository Structure

```
homarr-dashboard/
├── .git/                    # Git repository
├── .env                     # Environment config (not in git)
├── .env.example             # Template for .env
├── docker-compose.yml       # Main compose file
├── deploy.sh                # Initial deployment script
├── update.sh                # Update script
├── README.md                # Project readme
├── DEPLOYMENT.md            # Full deployment guide
├── GITEA_SETUP.md           # This file
└── config/                  # Configuration files
    ├── apps.json
    ├── rss-feeds.json
    ├── board-layouts.md
    └── homarr-themes.md
```

---

## 🔄 Version Control Best Practices

### Commit Messages

```bash
# Good commit messages
git commit -m "Add new RSS feeds for cybersecurity"
git commit -m "Update Docker image to beta.3"
git commit -m "Fix: Correct port mapping for Dash."
git commit -m "Theme: Update primary color to match new design"
```

### Branching Strategy

```bash
# Production branch: main
# Development branch: develop

# Feature workflow
git checkout -b feature/add-grafana-integration
# ... make changes ...
git commit -am "Add Grafana integration"
git push origin feature/add-grafana-integration
# Create merge request in Gitea
```

### Sensitive Data

**Never commit:**
- `.env` file (contains secrets)
- `homarr/appdata/` (runtime data)
- Any files with passwords or API keys

**Already configured in `.gitignore`:**
```gitignore
.env
homarr/appdata/
dash/
*.log
```

---

## 🛠️ Advanced: Drone CI Integration

### `.drone.yml` (optional)

```yaml
kind: pipeline
type: docker
name: deploy

steps:
  - name: deploy
    image: appleboy/drone-ssh
    settings:
      host:
        from_secret: server_host
      username:
        from_secret: server_user
      password:
        from_secret: server_password
      script:
        - cd /opt/homelab/homarr-dashboard
        - git pull
        - docker compose up -d

    when:
      branch:
        - main
      event:
        - push
```

---

## 📝 Maintenance Checklist

- [ ] Weekly: Review and update RSS feeds
- [ ] Monthly: Update Docker images (`docker compose pull`)
- [ ] Monthly: Backup `homarr/appdata/` directory
- [ ] Quarterly: Review and rotate secrets
- [ ] As needed: Add new apps or integrations

---

## 🆘 Troubleshooting

### Issue: Cannot clone repository

```bash
# Test Gitea access
curl -I https://gitea.lemonlink.eu

# Check SSH key (if using SSH)
cat ~/.ssh/id_rsa.pub
# Add to Gitea: User Settings → SSH Keys
```

### Issue: NPM network not found

```bash
# Create network manually
docker network create npm-network

# Restart containers
docker compose restart
```

### Issue: Changes not reflecting

```bash
# Force pull and recreate
git fetch origin
git reset --hard origin/main
docker compose up -d --force-recreate
```

---

## 🔗 Useful Commands

```bash
# Check repo status
git status

# View commit history
git log --oneline -10

# Pull latest changes
git pull origin main

# See what files changed
git diff --name-only

# Rollback to previous version
git log --oneline  # Find commit hash
git checkout <commit-hash>
docker compose up -d
```