6.6 KiB

Raw Blame History

🦊 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

Navigate to your Gitea instance: https://gitea.lemonlink.eu
Create a new organization (optional): homelab
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

# 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:

# 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

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

Method 2: Using Update Script

The included update.sh script automates this:

# 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:

Repository → Settings → Webhooks
Add Webhook → Gitea
Target URL: https://deploy.lemonlink.eu/webhook/homarr
Secret: Generate a secure secret
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

# 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

# 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

# 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:

.env
homarr/appdata/
dash/
*.log

🛠️ Advanced: Drone CI Integration

`.drone.yml` (optional)

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

# 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

# Create network manually
docker network create npm-network

# Restart containers
docker compose restart

Issue: Changes not reflecting

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

🔗 Useful Commands

# 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

6.6 KiB Raw Blame History