Gitea is a lightweight, self-hosted Git service designed for managing repositories with ease. It’s an excellent choice for developers and system administrators who value customization, control over their data, and a streamlined setup process. This guide covers everything you need to deploy, configure, and manage Gitea, focusing on practical, hands-on steps.
Installing Gitea
📦 Docker/Docker Compose Setup
Using Docker Compose is the easiest way to deploy Gitea with isolated dependencies and persistent storage.
Create the docker-compose.yml file:
version: "3"
services:
gitea:
image: gitea/gitea:latest
container_name: gitea
ports:
- "3000:3000"
- "2222:22" # For SSH access
volumes:
- ./gitea/data:/data
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
Deploy the Gitea container:
docker-compose up -d
Verify that Gitea is running by accessing http://<your-server-ip>:3000 in your browser.
🚀 Manual Installation
For those who prefer manual installation, here’s how to set up Gitea on a Linux server.
Install dependencies and create a dedicated user:
sudo apt update && sudo apt install -y git wget sqlite3
sudo useradd -r -m -d /var/lib/gitea -s /bin/bash git
Download and install the Gitea binary:
wget -O /usr/local/bin/gitea https://dl.gitea.io/gitea/1.19.2/gitea-1.19.2-linux-amd64
chmod +x /usr/local/bin/gitea
Create necessary directories and set permissions:
sudo mkdir -p /etc/gitea /var/lib/gitea/{custom,data,log}
sudo chown -R git:git /var/lib/gitea
sudo chmod 750 /var/lib/gitea
sudo chown root:git /etc/gitea
sudo chmod 770 /etc/gitea
Set up Gitea as a systemd service:
sudo tee /etc/systemd/system/gitea.service > /dev/null <<EOF
[Unit]
Description=Gitea
After=syslog.target
After=network.target
Requires=network.target
[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/var/lib/gitea
[Install]
WantedBy=multi-user.target
EOF
Enable and start the service:
sudo systemctl enable gitea
sudo systemctl start gitea
Visit http://<your-server-ip>:3000 to complete the installation wizard.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
Set up Nginx to serve Gitea, improving performance and allowing the app to be accessed from a custom domain.
Create an Nginx server block:
sudo nano /etc/nginx/sites-available/gitea
Add the following configuration:
server {
server_name gitea.example.com;
location / {
proxy_pass http://127.0.0.1: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;
}
listen 80;
}
Enable the configuration and reload Nginx:
sudo ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure your Gitea installation with Let's Encrypt.
Install Certbot:
sudo apt install -y certbot python3-certbot-nginx
Obtain and apply an SSL certificate:
sudo certbot --nginx -d gitea.example.com
Set up automatic certificate renewal:
sudo crontab -e
0 12 * * * certbot renew --quiet && systemctl reload nginx
Logging and Debugging Gitea
🗃️ Enabling Debug Logs
To troubleshoot issues, enable debug-level logging in Gitea’s configuration file.
Edit the app.ini file:
sudo nano /etc/gitea/app.ini
Add or update the logging section:
[log]
LEVEL = Debug
MODE = file
Restart Gitea to apply changes:
sudo systemctl restart gitea
📄 Viewing Logs
If using Docker, view logs using:
docker logs gitea
For manual installations, access logs at:
sudo tail -f /var/lib/gitea/log/gitea.log
🛠️ Troubleshooting Common Issues
Check permissions if Gitea fails to start:
sudo chown -R git:git /var/lib/gitea
Analyze logs for common errors such as missing dependencies or misconfigurations.
📤 Exporting Logs
Send logs to an external system for advanced analysis:
tail -F /var/lib/gitea/log/gitea.log | nc <elk-server-ip> 5000
Backup and Restore
🗂️ File-Based Backups
Backup Gitea’s data directory:
tar -czvf gitea-backup.tar.gz /var/lib/gitea
🔄 Database Backups
For a SQLite-based Gitea setup:
sqlite3 /var/lib/gitea/data/gitea.db .backup gitea-backup.db
For MySQL:
mysqldump -u gitea_user -p gitea_db > gitea-db-backup.sql
📅 Automated Backup Scripts
Create a cron job for periodic backups:
crontab -e
## Add the following line (adjust paths as needed):
0 2 * * * tar -czvf /backups/gitea-$(date +\%F).tar.gz /var/lib/gitea
Updating and Upgrading Gitea
⬆️ Updating Docker Images
Pull the latest image and redeploy:
docker-compose down
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
Download the latest binary and replace the existing one:
wget -O /usr/local/bin/gitea https://dl.gitea.io/gitea/latest/gitea-latest-linux-amd64
chmod +x /usr/local/bin/gitea
sudo systemctl restart gitea
🔍 Checking for Updates
Check Gitea's GitHub releases for new versions:
curl -s https://api.github.com/repos/go-gitea/gitea/releases/latest | grep tag_name
Leveraging Gitea’s Unique Features
🔧 Enabling APIs
Enable Gitea’s API in the configuration file:
[api]
ENABLE_SWAGGER = true
Test the API with curl:
curl -H "Authorization: token <your-token>" http://<your-server-ip>:3000/api/v1/user
🌟 Advanced Configurations
Enable repository mirroring:
[repository]
ENABLE_MIRRORS = true
Integrate a CI/CD system using Gitea’s webhooks:
curl -X POST -H "Content-Type: application/json" \
-d '{"config": {"url": "http://ci-server.com/webhook", "content_type": "json"}, "events": ["push"], "active": true}' \
-H "Authorization: token <your-token>" \
http://<your-server-ip>:3000/api/v1/repos/<owner>/<repo>/hooks
Wrapping Up
By following this guide, you’ve successfully deployed, configured, and secured Gitea, along with enabling logging, backups, and updates. Gitea’s lightweight design and extensive customization make it an excellent choice for self-hosting. Start exploring its powerful features today to take full control of your Git hosting!
