🐙 Gitea Git Server on AlmaLinux: Your Own Lightweight GitHub Alternative

Welcome to self-hosted Git paradise! 🎉 Ready to take control of your code repositories? Gitea is the painless, lightweight Git service that brings GitHub-like features to your own server! It’s the platform that makes Git hosting simple and beautiful! Think of it as your personal GitHub that runs anywhere! 🚀✨

🤔 Why is Gitea Important?

Gitea revolutionizes self-hosted Git! 🚀 Here’s why it’s amazing:

• 🪶 Ultra Lightweight - Runs on minimal resources!
• 🎯 GitHub Compatible - Familiar interface and features!
• 📦 Package Registry - Host Docker, npm, PyPI packages!
• 🔄 CI/CD Built-in - Gitea Actions like GitHub Actions!
• 🔒 Full Control - Your code, your server, your rules!
• 🆓 Completely Free - MIT licensed forever!

It’s like having GitHub in your pocket! 💰

🎯 What You Need

Before building your Git server, ensure you have:

• ✅ AlmaLinux 9 server
• ✅ Root or sudo access
• ✅ At least 2GB RAM (1GB minimum)
• ✅ 2 CPU cores recommended
• ✅ 10GB free disk space
• ✅ Git installed
• ✅ Love for version control! 🐙

📝 Step 1: System Preparation - Getting Ready!

Let’s prepare AlmaLinux 9 for Gitea! 🏗️

# Update system packages
sudo dnf update -y

# Install Git and dependencies
sudo dnf install -y git wget curl

# Create git user for Gitea
sudo useradd -r -m -U -d /home/git -s /bin/bash git

# Install database (MariaDB)
sudo dnf install -y mariadb-server mariadb

# Start and enable MariaDB
sudo systemctl start mariadb
sudo systemctl enable mariadb

# Secure MariaDB installation
sudo mysql_secure_installation
# Set root password: YourRootPass123!
# Remove anonymous users: Y
# Disallow root login remotely: Y
# Remove test database: Y
# Reload privilege tables: Y

# Create Gitea database
sudo mysql -u root -p << 'EOF'
CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'gitea'@'localhost' IDENTIFIED BY 'GiteaPass123!';
GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost';
FLUSH PRIVILEGES;
EXIT;
EOF

Configure firewall for Gitea:

# Open Gitea port
sudo firewall-cmd --permanent --add-port=3000/tcp
# Open SSH port for Git
sudo firewall-cmd --permanent --add-port=22/tcp
sudo firewall-cmd --reload

# Verify ports
sudo firewall-cmd --list-ports
# Should show: 3000/tcp 22/tcp

Perfect! System is ready! 🎯

🔧 Step 2: Installing Gitea - The Simple Way!

Let’s install Gitea binary! 🚀

Download Gitea:

# Check latest version at https://dl.gitea.io/gitea/
GITEA_VERSION="1.21.3"  # Update to latest version

# Download Gitea binary
sudo wget -O /usr/local/bin/gitea \
  https://dl.gitea.io/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64

# Make it executable
sudo chmod +x /usr/local/bin/gitea

# Verify installation
gitea --version
# Should show: Gitea version 1.21.3

Create Directory Structure:

# Create required directories
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo mkdir -p /etc/gitea

# Set proper ownership
sudo chown -R git:git /var/lib/gitea/
sudo chown root:git /etc/gitea
sudo chmod 750 /etc/gitea

# This allows Gitea to write config during setup
# We'll lock it down after initial setup
sudo chmod 770 /etc/gitea

Create Systemd Service:

# Create service file
sudo tee /etc/systemd/system/gitea.service << 'EOF'
[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
After=mariadb.service

[Service]
Type=notify
RestartSec=2s
Restart=always
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd
sudo systemctl daemon-reload

# Enable Gitea service
sudo systemctl enable gitea

🌟 Step 3: Initial Configuration - Your Git Platform!

Let’s configure Gitea! 🎮

Start Gitea:

# Start Gitea service
sudo systemctl start gitea

# Check status
sudo systemctl status gitea
# Should show: active (running)

# View logs if needed
sudo journalctl -u gitea -f

Web Setup Wizard:

1. Access Gitea:

   # Get your server IP
   ip addr show | grep inet
   # Open browser: http://your-server-ip:3000

2. Database Settings:

   • Database Type: MySQL
   • Host: 127.0.0.1:3306
   • User: gitea
   • Password: GiteaPass123!
   • Database: gitea

3. General Settings:

   • Site Title: My Gitea Server
   • Repository Root Path: /home/git/gitea-repositories
   • Git LFS Root Path: /var/lib/gitea/data/lfs
   • Run As Username: git
   • Domain: your-server-ip
   • SSH Port: 22
   • HTTP Port: 3000
   • Application URL: http://your-server-ip:3000/
   • Log Path: /var/lib/gitea/log

4. Optional Settings:

   • Enable Email: Configure SMTP if needed
   • Disable Registration: Check if private
   • Enable OpenID: For SSO support
   • Admin Account:
     • Username: gitadmin
     • Password: AdminPass123!
     • Email: [email protected]

5. Click “Install Gitea” 🎉

Secure Configuration:

# After setup, lock down config file
sudo chmod 750 /etc/gitea
sudo chmod 640 /etc/gitea/app.ini
sudo chown root:git /etc/gitea/app.ini

# Restart Gitea
sudo systemctl restart gitea

✅ Step 4: Creating Your First Repository - Let’s Code!

Time to create and use repositories! 🎯

Create Repository via Web:

1. Login with admin account
2. Click ”+” → “New Repository”
3. Configure:
   • Owner: gitadmin
   • Repository Name: hello-world
   • Description: My first Gitea repository
   • Visibility: Private/Public
   • Initialize: ✓ README
   • .gitignore: Select template
   • License: Choose license
4. Create Repository

Clone and Use Repository:

# Configure Git globally
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Clone via HTTP
git clone http://your-server-ip:3000/gitadmin/hello-world.git

# Or clone via SSH (after adding SSH key)
git clone git@your-server-ip:gitadmin/hello-world.git

# Work with repository
cd hello-world
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Add SSH Key:

# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"

# Copy public key
cat ~/.ssh/id_ed25519.pub

# In Gitea:
# 1. Click avatar → Settings
# 2. SSH/GPG Keys → Add Key
# 3. Paste public key
# 4. Add Key

🌟 Step 5: Advanced Features - Power User Mode!

Let’s explore Gitea’s powerful features! 🎯

Enable Gitea Actions (CI/CD):

# Edit Gitea config
sudo vi /etc/gitea/app.ini

# Add Actions section
cat << 'EOF' | sudo tee -a /etc/gitea/app.ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com
EOF

# Restart Gitea
sudo systemctl restart gitea

Create .gitea/workflows/ci.yml in your repository:

name: CI Pipeline
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm install
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build

Setup Package Registry:

# Enable packages in config
sudo vi /etc/gitea/app.ini

# Add packages section
[packages]
ENABLED = true
CHUNKED_UPLOAD_PATH = /var/lib/gitea/data/tmp/package-upload

# Restart Gitea
sudo systemctl restart gitea

Use Docker registry:

# Login to Gitea Docker registry
docker login your-server-ip:3000

# Tag and push image
docker tag myapp:latest your-server-ip:3000/gitadmin/myapp:latest
docker push your-server-ip:3000/gitadmin/myapp:latest

Create Organization:

1. Click ”+” → “New Organization”
2. Configure:
   • Organization Name: mycompany
   • Visibility: Public/Private
3. Create Organization
4. Add team members and manage permissions

🎮 Quick Examples

Example 1: Mirror GitHub Repository

# In Gitea, create new migration
# 1. Click "+" → "New Migration"
# 2. Select "GitHub"
# 3. Enter repository URL
# 4. Choose options:
#    - Mirror: Yes (keep synced)
#    - Private: Your choice
#    - Migrate Issues/PRs: Optional
# 5. Migrate Repository

# Repository stays synced with upstream!

Example 2: Webhook Integration

# Add webhook for deployments
# 1. Go to Repository → Settings → Webhooks
# 2. Add Webhook → Gitea
# 3. Configure:
#    - URL: http://deploy-server/webhook
#    - Secret: webhook-secret-key
#    - Events: Push, Release
# 4. Add Webhook

# Server-side webhook handler
cat << 'EOF' > /usr/local/bin/deploy-webhook.sh
#!/bin/bash
if [ "$1" = "webhook-secret-key" ]; then
    cd /var/www/app
    git pull
    npm install
    npm run build
    sudo systemctl restart app
fi
EOF

Example 3: API Usage

# Get API token
# User Settings → Applications → Generate Token

# Use API
API_TOKEN="your-api-token"
SERVER="http://your-server-ip:3000"

# List repositories
curl -H "Authorization: token $API_TOKEN" \
  $SERVER/api/v1/user/repos

# Create repository via API
curl -X POST -H "Authorization: token $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"api-repo","private":true}' \
  $SERVER/api/v1/user/repos

# Create issue
curl -X POST -H "Authorization: token $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bug Report","body":"Description here"}' \
  $SERVER/api/v1/repos/gitadmin/hello-world/issues

🚨 Fix Common Problems

Problem 1: Cannot Access Web Interface

Symptom: Connection refused on port 3000 😰

Fix:

# Check if Gitea is running
sudo systemctl status gitea

# Check port binding
sudo netstat -tlnp | grep 3000

# View logs for errors
sudo journalctl -u gitea -n 100

# Check firewall
sudo firewall-cmd --list-all

# Restart Gitea
sudo systemctl restart gitea

Problem 2: Git Push Fails

Symptom: Authentication or permission errors 🔐

Fix:

# Check SSH service
sudo systemctl status sshd

# Verify git user shell
sudo cat /etc/passwd | grep git
# Should have /bin/bash shell

# Test SSH connection
ssh -T git@your-server-ip

# Check repository permissions
sudo ls -la /home/git/gitea-repositories/

# Fix permissions if needed
sudo chown -R git:git /home/git/gitea-repositories/

Problem 3: Database Connection Issues

Symptom: 500 errors, database errors 🔴

Fix:

# Check MariaDB status
sudo systemctl status mariadb

# Test database connection
mysql -u gitea -p gitea

# Check Gitea config
sudo cat /etc/gitea/app.ini | grep -A5 database

# Restart both services
sudo systemctl restart mariadb
sudo systemctl restart gitea

# Check logs
sudo tail -f /var/lib/gitea/log/gitea.log

📋 Simple Commands Summary

💡 Tips for Success

🚀 Performance Optimization

Make Gitea super fast:

# Enable caching
sudo vi /etc/gitea/app.ini

# Add cache settings
[cache]
ENABLED = true
ADAPTER = memory
INTERVAL = 60
HOST =

[cache.last_commit]
ENABLED = true
ITEM_TTL = 8760h

# Use PostgreSQL for better performance
# Install PostgreSQL instead of MariaDB
sudo dnf install -y postgresql postgresql-server

# Database indexing
mysql -u root -p gitea
CREATE INDEX idx_issue_repo ON issue(repo_id);
CREATE INDEX idx_action_repo ON action(repo_id);

🔒 Security Best Practices

Keep Gitea secure:

1. Enable HTTPS - Use SSL certificates! 🔐
2. Disable registration - Control who joins! 👥
3. 2FA authentication - Extra security layer! 🔑
4. Regular backups - Protect your data! 💾
5. Update regularly - Stay secure! 📦

# Setup HTTPS with Let's Encrypt
sudo dnf install -y certbot nginx

# Configure Nginx reverse proxy
cat << 'EOF' | sudo tee /etc/nginx/conf.d/gitea.conf
server {
    listen 443 ssl http2;
    server_name git.example.com;
    
    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

sudo systemctl restart nginx

📊 Monitoring and Backup

Keep Gitea healthy:

# Automated backup script
cat << 'EOF' > /usr/local/bin/backup-gitea.sh
#!/bin/bash
BACKUP_DIR="/backup/gitea"
DATE=$(date +%Y%m%d)

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup Gitea
sudo -u git gitea dump -c /etc/gitea/app.ini \
  -w /tmp --file $BACKUP_DIR/gitea-dump-$DATE.zip

# Keep only last 7 backups
find $BACKUP_DIR -name "*.zip" -mtime +7 -delete

echo "Backup completed: gitea-dump-$DATE.zip"
EOF

chmod +x /usr/local/bin/backup-gitea.sh
# Add to cron: 0 2 * * * /usr/local/bin/backup-gitea.sh

🏆 What You Learned

You’re now a Gitea expert! 🎓 You’ve successfully:

• ✅ Installed Gitea on AlmaLinux 9
• ✅ Configured database and web interface
• ✅ Created repositories and users
• ✅ Enabled CI/CD with Actions
• ✅ Set up package registry
• ✅ Implemented webhooks and API
• ✅ Mastered self-hosted Git

Your Git server is production-ready! 🐙

🎯 Why This Matters

Gitea gives you Git independence! With your Git server, you can:

• 🚀 Control everything - Your code, your rules!
• 🪶 Save resources - Minimal requirements!
• 🔒 Stay private - No third-party access!
• 📦 Host packages - Complete DevOps platform!
• 💰 Save money - Enterprise features free!

You’re not just hosting Git - you’re building your own development platform! Every repository is yours, every feature is free! 🎭

Keep coding, keep hosting, and remember - with Gitea, Git hosting is simple and powerful! ⭐

May your commits be clean and your branches merge smoothly! 🚀🐙🙌