Gitea VPS - Getting Started Guide

Software Included

Component	Details
Ubuntu	24.04 LTS
Gitea	1.25 (SQLite, Git LFS)
Nginx	Reverse proxy with SSL
Gitea Actions Runner	Built-in CI/CD (host executor)
Certbot	Let's Encrypt SSL
Fail2Ban	SSH + Gitea brute-force protection

Step 1 - Your Credentials

Log in to your client panel and open your VPS service details. Find the IP address and root password (for SSH).

Gitea login:

• Username: admin
• Password: the Admin Password you entered during the order

Step 2 - Access Gitea

Gitea is available immediately after your VPS is created. If you entered a domain during the order:

https://your-domain.com

If no domain was specified, use the server IP:

https://your.server.ip

Log in with username admin and the Admin Password from Step 1.

Note: Gitea uses a self-signed SSL certificate by default. Your browser will show a security warning - this is expected. Click "Advanced" and proceed. You can install a proper Let's Encrypt certificate later (see Step 5).

Step 3 - Create Your First Repository

Click the + button in the top right corner and select New Repository. Fill in the repository name and click Create Repository.

Clone your repository using HTTPS or SSH:

# HTTPS
git clone https://your-domain.com/admin/my-repo.git

# SSH (add your public key in Settings > SSH/GPG Keys first)
git clone git@your-domain.com:admin/my-repo.git

Git SSH uses port 22 (the standard SSH port). Gitea automatically manages SSH keys - when you add a public key in the web interface, it becomes available for Git operations immediately.

Step 4 - Set Up a Custom Domain

If you didn't enter a domain during the order, or want to change it later, follow these steps:

1. Create a DNS A record pointing your domain to the server IP:

   Type	Name	Value
   A	git	your.server.ip

2. SSH into your server and edit the Gitea config:

   nano /etc/gitea/app.ini

   Update these lines in the [server] section:

   DOMAIN     = git.yourdomain.com
   SSH_DOMAIN = git.yourdomain.com
   ROOT_URL   = https://git.yourdomain.com/

3. Update Nginx and restart services:

   sed -i "s/server_name .*/server_name git.yourdomain.com;/g" /etc/nginx/sites-available/gitea
   systemctl restart gitea
   systemctl reload nginx

DNS changes usually take a few minutes, but can take up to 24 hours. Check the status at dnschecker.org.

Step 5 - Enable Let's Encrypt SSL (Optional)

If you have a domain pointing to your server, you can replace the self-signed certificate with a free Let's Encrypt certificate. Connect via SSH:

ssh root@your.server.ip

/opt/setup/get-ssl.sh git.yourdomain.com

The script will verify DNS, obtain a certificate, configure Nginx for HTTPS, and update the Gitea config automatically. The certificate renews automatically.

Note: Make sure your domain's A record points to the server IP before running the script. SSL is optional - Gitea works fine with the self-signed certificate.

Step 6 - CI/CD with Gitea Actions

Your Gitea instance comes with a built-in CI/CD runner (Gitea Actions). It is compatible with GitHub Actions workflow syntax. To use it, create a workflow file in your repository:

.gitea/workflows/build.yaml

Example workflow:

name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Gitea Actions!"

The runner executes jobs directly on the host (no Docker required). To check the runner status:

systemctl status act_runner

Fail2Ban - Brute-Force Protection

Your server comes with Fail2Ban pre-configured to protect both SSH and the Gitea web interface from brute-force attacks.

Rule	Max Attempts	Ban Duration
SSH	5 failed logins	1 hour
Gitea web login	5 failed logins	1 hour

Useful commands:

# Check banned IPs
fail2ban-client status sshd
fail2ban-client status gitea

# Unban an IP
fail2ban-client set sshd unbanip 1.2.3.4

If you accidentally lock yourself out, connect via VNC console in your client panel and unban your IP.

Server Credentials

Gitea admin credentials are stored in /root/.gitea_credentials.

Useful Commands

# Service management
systemctl status gitea          # check Gitea status
systemctl restart gitea         # restart Gitea
systemctl status act_runner     # check CI/CD runner status

# Gitea admin CLI
sudo -u git gitea admin user list --config /etc/gitea/app.ini
sudo -u git gitea admin user change-password --username admin --password "newpass" --config /etc/gitea/app.ini

# Database backup (SQLite)
cp /var/lib/gitea/data/gitea.db /root/gitea-backup-$(date +%Y%m%d).db

# View Gitea logs
tail -f /var/lib/gitea/log/gitea.log

Updates

Gitea is installed as a standalone binary and does not update automatically. To update manually, download the new version and replace the binary:

# Download new version (replace X.Y.Z with the desired version)
wget -O /tmp/gitea https://dl.gitea.com/gitea/X.Y.Z/gitea-X.Y.Z-linux-amd64
chmod +x /tmp/gitea

# Replace binary and restart
systemctl stop gitea
cp /tmp/gitea /usr/local/bin/gitea
systemctl start gitea

OS updates can be applied via SSH:

apt update && apt upgrade -y

• Gitea Documentation: docs.gitea.com
• Gitea Actions Guide: docs.gitea.com/usage/actions/overview
• Gitea on GitHub: github.com/go-gitea/gitea