Cómo instalar Gitea en Ubuntu 24.04 con PostgreSQL y Nginx

Gitea es un servicio Git autohospedado escrito en Go: un único binario que ofrece repositorios, incidencias, pull requests, wikis, webhooks y un registro de paquetes, con un consumo de recursos muy bajo. En este tutorial instalarás Gitea en Ubuntu 24.04 a partir del binario oficial, con PostgreSQL como base de datos, Nginx como proxy inverso con HTTPS y acceso a los repositorios por SSH a través del servidor OpenSSH del sistema.

Requisitos previos

• Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath. Con 1 vCPU y 1 GB de RAM basta para un equipo pequeño; añade 2 GB si vas a usar Gitea Actions o muchos repositorios.
• Un usuario no root con privilegios sudo.
• Un subdominio (en esta guía, git.your_domain) con un registro DNS A que apunte a la IP pública del servidor.
• Los puertos 22, 80 y 443 accesibles desde Internet.

Paso 1: Instalar Git y PostgreSQL

Gitea necesita Git en el servidor para manejar los repositorios. Instala Git y PostgreSQL:

sudo apt update
sudo apt install git postgresql

Abre la consola de PostgreSQL:

sudo -u postgres psql

Crea un rol y una base de datos para Gitea. Sustituye your_strong_password por una contraseña larga y aleatoria:

CREATE ROLE gitea WITH LOGIN PASSWORD 'your_strong_password';
CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8;
\q

Comprueba que el rol puede conectarse por TCP:

psql -h 127.0.0.1 -U gitea -d giteadb -c "SELECT current_user;"

 current_user
--------------
 gitea
(1 row)

Paso 2: Crear el usuario del sistema y los directorios

Gitea se ejecuta con un usuario dedicado llamado git. Ese nombre es el que aparecerá en las URL SSH de clonado ([email protected]_domain:...). Necesita una shell válida porque las conexiones SSH de los usuarios entran a través de él, aunque Gitea limita lo que pueden ejecutar:

sudo adduser --system --shell /bin/bash --gecos 'Git Version Control' \
  --group --disabled-password --home /home/git git

Crea el directorio de trabajo, donde se guardan los repositorios y datos, y el de configuración:

sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R git:git /var/lib/gitea
sudo chmod -R 750 /var/lib/gitea
sudo mkdir /etc/gitea
sudo chown root:git /etc/gitea
sudo chmod 770 /etc/gitea

/etc/gitea queda con escritura para el grupo git solo mientras dura la instalación web, que necesita crear app.ini. Lo cerrarás en el paso 6.

Paso 3: Descargar el binario de Gitea

Consulta la última versión estable en https://dl.gitea.com/gitea/ o en la página de versiones de GitHub y guárdala en una variable, sustituyendo X.Y.Z por el número real. Descarga el binario y su suma de comprobación:

GITEA_VERSION=X.Y.Z
cd /tmp
wget "https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64"
wget "https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64.sha256"
sha256sum -c "gitea-${GITEA_VERSION}-linux-amd64.sha256"

gitea-X.Y.Z-linux-amd64: OK

Si tu servidor es ARM64, sustituye linux-amd64 por linux-arm64 en ambas URL.

Instala el binario en /usr/local/bin:

sudo install -m 755 "gitea-${GITEA_VERSION}-linux-amd64" /usr/local/bin/gitea
gitea --version

Gitea version X.Y.Z built with GNU Make ...

Paso 4: Crear el servicio de systemd

Crea la unidad de systemd:

sudo nano /etc/systemd/system/gitea.service

[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target postgresql.service
Wants=postgresql.service

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

[Install]
WantedBy=multi-user.target

Activa y arranca el servicio:

sudo systemctl daemon-reload
sudo systemctl enable --now gitea

Comprueba que está activo y responde en el puerto 3000:

systemctl is-active gitea
curl -sI http://127.0.0.1:3000 | head -n 1

active
HTTP/1.1 200 OK

Todavía no expongas el puerto 3000 a Internet: el asistente de instalación queda abierto hasta que lo completes, y lo harás a través de Nginx con HTTPS.

Paso 5: Configurar Nginx y HTTPS

Instala Nginx y Certbot, y abre los puertos en el cortafuegos. Permite SSH antes de activar UFW para no perder la conexión:

sudo apt install nginx certbot python3-certbot-nginx
sudo ufw allow OpenSSH
sudo ufw allow "Nginx Full"
sudo ufw enable

Crea el sitio de Gitea:

sudo nano /etc/nginx/sites-available/gitea

server {
    listen 80;
    listen [::]:80;
    server_name git.your_domain;

    client_max_body_size 512M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        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;
    }
}

client_max_body_size permite hacer git push por HTTPS de repositorios grandes y subir adjuntos; con el valor por defecto de Nginx (1 MB) fallarían con un error 413.

Activa el sitio, desactiva el sitio por defecto, recarga Nginx y solicita el certificado:

sudo ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d git.your_domain

Comprueba que la renovación automática funcionará:

sudo certbot renew --dry-run

Congratulations, all simulated renewals succeeded:
  /etc/letsencrypt/live/git.your_domain/fullchain.pem (success)

Paso 6: Completar la instalación web

Abre https://git.your_domain en el navegador. Verás la página de configuración inicial. Rellena estos campos:

En Configuración opcional:

• Configuración del servidor y servicios de terceros: marca Deshabilitar el registro automático si no quieres que cualquiera pueda crear una cuenta.
• Configuración de la cuenta de administrador: crea aquí el administrador. Si lo dejas vacío, el primer usuario que se registre será administrador.

Pulsa Instalar Gitea. Cuando termine, se te redirigirá a la página de inicio con la sesión iniciada.

Gitea ha escrito su configuración en /etc/gitea/app.ini. Quita ahora el permiso de escritura sobre el directorio y el archivo:

sudo chmod 750 /etc/gitea
sudo chmod 640 /etc/gitea/app.ini

Para que Gitea solo escuche en local y el puerto 3000 no sea accesible aunque cambies el cortafuegos, edita app.ini:

sudo nano /etc/gitea/app.ini

En la sección [server], añade o modifica esta línea:

HTTP_ADDR = 127.0.0.1

Reinicia Gitea y comprueba que ahora escucha solo en 127.0.0.1:

sudo systemctl restart gitea
sudo ss -tlnp | grep 3000

LISTEN 0      4096       127.0.0.1:3000       0.0.0.0:*    users:(("gitea",pid=...,fd=...))

Paso 7: Probar el acceso por SSH

Gitea gestiona el archivo /home/git/.ssh/authorized_keys: cada clave pública que un usuario añade en su perfil se escribe ahí con un comando forzado, de modo que la conexión solo puede ejecutar operaciones Git. No hace falta tocar la configuración de sshd.

En tu equipo local, copia tu clave pública (por ejemplo ~/.ssh/id_ed25519.pub) y añádela en Gitea desde Configuración > Claves SSH / GPG > Añadir clave. Después, prueba la conexión:

ssh -T [email protected]_domain

Hi there, your_user! You've successfully authenticated with the key named mi-portatil, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.

Crea un repositorio vacío desde el botón + > Nuevo repositorio (por ejemplo prueba) y súbele contenido desde tu equipo:

mkdir prueba && cd prueba
git init -b main
echo "# prueba" > README.md
git add README.md
git commit -m "Primer commit"
git remote add origin [email protected]_domain:your_user/prueba.git
git push -u origin main

Recarga la página del repositorio en el navegador: el README.md debe aparecer.

Paso 8: Copias de seguridad

Gitea incluye el comando dump, que genera un zip con los repositorios, la base de datos y la configuración. Ejecútalo como el usuario git desde un directorio donde pueda escribir:

sudo mkdir -p /var/backups/gitea
sudo chown git:git /var/backups/gitea
cd /var/backups/gitea
sudo -u git /usr/local/bin/gitea dump --config /etc/gitea/app.ini --work-path /var/lib/gitea

... Packing dump files...
... Finish dumping in file /var/backups/gitea/gitea-dump-1758772800.zip

Para automatizarlo cada noche, abre el crontab del usuario git:

sudo crontab -u git -e

0 3 * * * cd /var/backups/gitea && /usr/local/bin/gitea dump --config /etc/gitea/app.ini --work-path /var/lib/gitea --quiet && find /var/backups/gitea -name 'gitea-dump-*.zip' -mtime +7 -delete

Copia los archivos fuera del servidor para que la copia sirva si este se pierde.

Paso 9: Actualizar Gitea

Actualizar Gitea consiste en reemplazar el binario; las migraciones de base de datos se aplican solas al arrancar. Haz antes una copia con gitea dump, descarga la nueva versión como en el paso 3 y sustituye el binario:

sudo systemctl stop gitea
sudo install -m 755 "gitea-${GITEA_VERSION}-linux-amd64" /usr/local/bin/gitea
sudo systemctl start gitea
gitea --version

Lee las notas de versión antes de saltar entre versiones mayores, ya que algunas cambian opciones de configuración.

Solución de problemas

• Error 502 Bad Gateway: Gitea no está en marcha. Revisa sudo journalctl -u gitea -n 50.
• git push por HTTPS falla con 413: aumenta client_max_body_size en el sitio de Nginx y recarga el servicio.
• ssh -T pide contraseña: la clave no está registrada en Gitea o el cliente usa otra. Prueba con ssh -i ~/.ssh/id_ed25519 -T [email protected]_domain y revisa que /home/git/.ssh/authorized_keys pertenece a git con permisos 600.
• Las URL de clonado muestran localhost:3000: ROOT_URL en la sección [server] de app.ini debe ser https://git.your_domain/. Corrígelo y reinicia Gitea.

Conclusión

Ya tienes Gitea funcionando en Ubuntu 24.04 con PostgreSQL, Nginx, HTTPS y acceso por SSH, con copias de seguridad diarias. Como siguientes pasos, configura el correo en la sección [mailer] de app.ini para las notificaciones, crea organizaciones para agrupar repositorios y activa Gitea Actions con un runner (act_runner) si quieres CI/CD integrado.