Tutoriales de VPS
Desplegar GitLab CE en un VPS (2026): tutorial completo de Docker Compose, HTTPS, SSH, copias de seguridad y Runner
Despliega GitLab CE en un VPS con Docker Compose, configura HTTPS con dominio, puertos SSH, primer inicio de sesión, optimización para equipos de bajos recursos, copias de seguridad y actualización, y la configuración de GitLab Runner, y soluciona problemas comunes de arranque y clonación.

Desplegar GitLab CE en un VPS (2026): tutorial completo de Docker Compose, HTTPS, SSH, copias de seguridad y Runner
Si quieres montar GitLab en un VPS, no te apresures a copiar un solo docker run. GitLab mete repositorios de código, Merge Requests, Issues, Container Registry y CI/CD en un solo sistema, y el precio es que consume más recursos que Gitea y depende más de dominios, puertos y copias de seguridad correctos.
Este artículo usa la imagen oficial GitLab CE 19.2.1, desplegada mediante Docker Compose. El SSH del host sigue usando el 22, mientras que la clonación por SSH de GitLab pasa al 2222; la parte web se sirve directamente por HTTPS con el Nginx integrado de GitLab y Let's Encrypt. El Runner va en otro VPS, para que las tareas de compilación no arrastren el repositorio de código.
La línea base oficial de GitLab para un nodo único normal es 8 vCPU y 16GB de memoria; la opción con memoria limitada puede bajar hasta 2GB de memoria más 1GB de Swap, pero está limitada a unos 5 desarrolladores y repositorios de menos de 100MB, y puede ir notablemente más lenta. En la práctica, puedes verlo así:
| Uso | Configuración sugerida | Notas |
|---|---|---|
| Prueba temporal, repositorios personales pequeños | 2–4 vCPU, 4GB de memoria, 40GB SSD | Requiere ajuste de memoria baja; no se recomienda ejecutar el Runner al mismo tiempo |
| Uso diario de un equipo pequeño | 4 vCPU, 8GB de memoria, 80GB NVMe | Más adecuado como configuración inicial |
| CI intensivo, Registry, muchos artefactos | 8 vCPU, 16GB o más | Mejor separar el Runner y el almacenamiento de objetos |
La lectura/escritura aleatoria de SSD/NVMe importa más que simplemente acumular CPU. Si aún no has decidido la configuración, puedes consultar primero la guía de selección de configuración de VPS. Si solo necesitas un repositorio Git privado ligero y no necesitas una plataforma DevOps completa, el tutorial de instalación de Gitea suele salir más económico.
Tampoco calcules el disco solo por el código fuente de los repositorios. La base de datos, LFS, Packages, Container Registry, los registros de CI y los Artifacts crecen, y las copias de seguridad también necesitan espacio temporal adicional. Antes de ponerlo en producción, enumera el número previsto de usuarios, el tamaño total de los repositorios, los artefactos por compilación y los días de retención, y deja en el disco al menos espacio para una copia de seguridad completa. Un disco lleno suele detener GitLab antes que una CPU insuficiente.
Primero apunta los registros A/AAAA de gitlab.example.com a la dirección pública del VPS. Sustituye el dominio y el correo de abajo por los tuyos; durante la validación de Let's Encrypt, el 80 y el 443 deben ser accesibles desde internet público.
Comprueba el uso de puertos:
sudo ss -lntup | grep -E ':22|:80|:443|:2222'
El 22 debería seguir siendo usado por el SSH del host, mientras que el 80, el 443 y el 2222 quedan para el contenedor de GitLab. Crea los directorios persistentes:
sudo mkdir -p /srv/gitlab/{config,logs,data}
sudo mkdir -p /srv/gitlab-backups
Antes de configurar UFW, mantén abierta la sesión SSH actual y prueba desde una terminal nueva, para no quedarte fuera:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw enable
sudo ufw status numbered
El grupo de seguridad del proveedor de nube también debe permitir los mismos puertos. Si no estás familiarizado con la operación, consulta primero el tutorial de UFW para evitar el bloqueo de SSH.
Tras instalar Docker en Ubuntu o Debian, confirma primero que el servicio y el plugin de Compose estén disponibles:
sudo systemctl enable --now docker
docker --version
docker compose version
df -h /srv/gitlab
GitLab no admite oficialmente trasladar este ejemplo de producción directamente a Docker Desktop for Windows. En un servidor de producción tampoco pongas el directorio de datos en sistemas de archivos de red de alta latencia como NFS o EFS; Gitaly es muy sensible a la E/S aleatoria.
Crea el directorio del proyecto y el archivo Compose:
sudo mkdir -p /opt/gitlab
cd /opt/gitlab
sudo nano compose.yaml
Escribe la siguiente configuración:
services:
gitlab:
image: gitlab/gitlab-ce:19.2.1-ce.0
container_name: gitlab
restart: always
hostname: gitlab.example.com
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url 'https://gitlab.example.com'
gitlab_rails['gitlab_shell_ssh_port'] = 2222
letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['[email protected]']
ports:
- '80:80'
- '443:443'
- '2222:22'
volumes:
- /srv/gitlab/config:/etc/gitlab
- /srv/gitlab/logs:/var/log/gitlab
- /srv/gitlab/data:/var/opt/gitlab
shm_size: '256m'
logging:
driver: json-file
options:
max-size: '20m'
max-file: '5'
Aquí debes cambiar al mismo tiempo hostname, external_url, el correo de contacto y el DNS. 2222:22 es la asignación del puerto del host al puerto SSH del contenedor, mientras que gitlab_shell_ssh_port = 2222 se encarga de que la página web genere la Clone URL correcta; omitir cualquiera de ellos hará que los usuarios se conecten al puerto equivocado.
Comprueba primero el resultado renderizado y luego inicia:
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 gitlab
No uses latest en producción. Fijar la versión de parche no solo evita una actualización repentina al reconstruir, sino que restaurar una copia de seguridad también requiere exactamente la misma versión de GitLab y el mismo tipo CE/EE. Para las comprobaciones de estado, los registros y los principios de reversión de Compose, consulta la lista de verificación de configuración de producción de Docker Compose.
GitLab necesita unos minutos para inicializar la base de datos y los servicios internos la primera vez. Que el contenedor muestre running no significa que la página ya esté disponible; si ves un 502 durante un rato, comprueba primero el progreso:
docker exec -it gitlab gitlab-ctl status
docker compose logs --tail=200 gitlab
curl -I https://gitlab.example.com
Si Let's Encrypt falla, confirma primero que el dominio ya está activo en el DNS público, que el 80/443 no está bloqueado por el grupo de seguridad y que no hay un registro CAA incorrecto. No uses un example.com que no se pueda resolver públicamente para solicitar realmente un certificado.
Cuando la página funcione, lee la contraseña temporal de root:
docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password
El nombre de usuario es root. Tras iniciar sesión, cambia la contraseña de inmediato, rellena el correo del administrador y crea una cuenta normal para el uso diario. Este archivo de contraseña temporal se elimina automáticamente 24 horas después del primer reinicio, así que no copies la contraseña en scripts ni en historiales de chat.
Primero crea un proyecto vacío en GitLab y luego haz un push por HTTPS. Después, añade tu clave pública SSH local en Preferences → SSH Keys del menú del avatar y prueba:
ssh -T -p 2222 [email protected]
La primera conexión preguntará si aceptas la Host Key; verifica la huella antes de confirmar. La dirección SSH correcta debería ser similar a:
ssh://[email protected]:2222/your-name/demo.git
Si la página sigue mostrando 22, comprueba la ortografía de gitlab_shell_ssh_port y reconstruye el contenedor; si se rechaza el 2222, revisa en orden docker compose ps, ss -lntup, UFW y el grupo de seguridad de la nube. No asignes el 22 del contenedor al 22 del host solo por comodidad, o entrará en conflicto con el SSH que usas para gestionar el VPS.
Un VPS de 4GB solo es adecuado para uso personal y de baja frecuencia. Puedes añadir las siguientes tres líneas al GITLAB_OMNIBUS_CONFIG de Compose y luego reconstruir el contenedor:
puma['worker_processes'] = 0
sidekiq['concurrency'] = 10
prometheus_monitoring['enable'] = false
docker compose up -d
docker exec -it gitlab gitlab-ctl status
free -h
docker stats --no-stream gitlab
Puma en un solo proceso reduce la concurrencia, una menor concurrencia de Sidekiq hace que las tareas en segundo plano se acumulen, y desactivar el Prometheus integrado también elimina la capacidad de monitorización. El Swap puede reducir el riesgo de OOM repentino, pero una vez que la paginación es continua, GitLab irá muy lento. Cuando Puma o Sidekiq se reinicien repetidamente o aparezcan registros de OOM del kernel, prioriza ampliar la memoria en lugar de seguir apagando servicios clave.
La imagen Docker de GitLab no incluye un servicio SMTP. Sin correo, las invitaciones, los restablecimientos de contraseña, las alertas y las notificaciones de copia de seguridad se ven afectados; conviene conectar un SMTP de confianza en la configuración de Omnibus y enviar un correo de prueba desde la Rails Console o el panel de administración.
Tras el lanzamiento, completa al menos estos ajustes:
- Desactiva el registro de usuarios cuando no necesites una comunidad pública;
- Activa la autenticación de dos factores para administradores y mantenedores;
- Restringe la visibilidad de proyectos y los permisos predeterminados;
- Revisa periódicamente administradores, Access Tokens, Deploy Keys y Runners;
- No ejecutes el Runner en el mismo host que GitLab y no uses ejecutores privilegiados para proyectos no confiables.
También revisa en el Admin Area la visibilidad predeterminada de proyectos, los permisos de nuevos usuarios y la política de retención máxima de Artifacts. Si realmente necesitas habilitar el registro público, al menos combínalo con verificación por correo, aprobación del administrador y limitación de frecuencia. Tras configurar SMTP, no te limites a ver que se guardó correctamente; provoca realmente un correo de restablecimiento de contraseña y confirma que el dominio del remitente, los rebotes y la política de spam funcionan bien.
Crea una copia de seguridad de los datos de negocio:
docker exec -t gitlab gitlab-backup create
ls -lh /srv/gitlab/data/backups
Este archivo contiene datos como la base de datos, los repositorios, las subidas y los artefactos, pero no equivale a una copia de seguridad de toda la máquina. La configuración, gitlab-secrets.json, las claves privadas TLS y las SSH Host Keys siguen en /srv/gitlab/config y deben guardarse por separado:
sudo tar -C /srv/gitlab -czf \
/srv/gitlab-backups/gitlab-config-$(date +%F).tar.gz config
sudo ls -lh /srv/gitlab-backups
Si usas almacenamiento de objetos externo, gitlab-backup tampoco copiará el Bucket por ti. Sincroniza ambos tipos de copia de seguridad con otro servidor u otro almacenamiento de objetos y realiza simulacros de restauración con regularidad; ver solo los archivos de copia de seguridad no cuenta como recuperable. Para el enfoque completo, consulta simulacro de copia de seguridad y restauración en VPS.
Se recomienda conservar tres tipos de puntos de restauración —"diario, semanal, antes de actualizar"— y registrar el tag de GitLab correspondiente a cada copia de seguridad. Tras sincronizar, verifica en el lado remoto el tamaño o la suma de comprobación del archivo, para que si el disco local se daña no pierdas también las copias de seguridad. Cuando Registry, LFS o Artifacts usen un Bucket externo, la copia de seguridad de negocio y la instantánea del almacenamiento de objetos deben estar en la misma ventana de mantenimiento, para reducir inconsistencias de referencias tras la restauración.
Antes de restaurar, prepara un GitLab nuevo que funcione correctamente y tenga exactamente la misma versión y Edition. Detén Puma y Sidekiq antes de ejecutar la restauración:
docker exec -it gitlab gitlab-ctl stop puma
docker exec -it gitlab gitlab-ctl stop sidekiq
docker exec -it gitlab gitlab-backup restore BACKUP=REPLACE_WITH_BACKUP_ID
docker restart gitlab
docker exec -it gitlab gitlab-rake gitlab:check SANITIZE=true
La restauración reescribe la base de datos, así que solo puede ejecutarse en una ventana de mantenimiento o en una máquina aislada de simulacro de restauración. Antes de restaurar, también hay que restaurar la configuración y los Secrets correspondientes.
Antes de actualizar, registra la versión actual, completa una copia de seguridad y consulta la Upgrade Path oficial de GitLab. Al cruzar varias versiones menores o mayores, debes pasar por las versiones de parada designadas; las paradas de GitLab 19 incluyen 19.2, 19.5, 19.8 y 19.11, y en cada paso hay que esperar a que terminen las migraciones en segundo plano.
Al actualizar un parche dentro de la misma versión menor, primero cambia la imagen en Compose al tag fijado de destino y luego ejecuta:
docker compose pull
docker compose up -d
docker compose logs --tail=200 gitlab
docker exec -it gitlab gitlab-rake gitlab:check SANITIZE=true
Después verifica la página web, el push por SSH, el Runner y las migraciones en segundo plano. Una vez migrada la base de datos, no puedes revertir simplemente cambiando el tag de la imagen a la versión anterior; una reversión correcta requiere restaurar la imagen antigua, la configuración antigua y la copia de seguridad de la versión correspondiente.
El Runner ejecuta código de los proyectos, así que es mejor ponerlo en un VPS independiente. Primero crea un Runner en la página de Runners del proyecto, del grupo o del administrador en GitLab, y obtén el Runner Authentication Token que empieza por glrt-. El flujo antiguo de Registration Token está obsoleto, así que no copies tutoriales antiguos.
Inicia un contenedor de versión fijada en el VPS del Runner:
sudo mkdir -p /srv/gitlab-runner/config
docker run -d --name gitlab-runner --restart always \
-v /srv/gitlab-runner/config:/etc/gitlab-runner \
-v /var/run/docker.sock:/var/run/docker.sock \
gitlab/gitlab-runner:alpine-v19.2.1
docker exec -it gitlab-runner gitlab-runner register \
--non-interactive \
--url 'https://gitlab.example.com' \
--token 'glrt-REPLACE_WITH_RUNNER_AUTH_TOKEN' \
--executor docker \
--docker-image alpine:3.22 \
--description 'vps-docker-runner'
Verifica con un .gitlab-ci.yml mínimo:
stages: [test]
runner-check:
stage: test
image: alpine:3.22
script:
- echo "GitLab Runner is working"
- uname -a
Montar el Docker Socket significa que el Runner puede controlar el demonio Docker del host, lo que no es un aislamiento fuerte. Deja que solo lo usen proyectos de confianza y no compartas este Runner con proyectos públicos. Cuando necesites caché, compilar imágenes y un aislamiento de seguridad más fino, puedes consultar la guía de Runner autoalojado de GitHub Actions para entender riesgos similares.
| Síntoma | Qué revisar primero | Causa común |
|---|---|---|
| La página muestra 502 durante mucho tiempo | gitlab-ctl status, registros del contenedor, memoria | Inicialización sin terminar, OOM, fallo de un servicio interno |
| Falla la solicitud del certificado HTTPS | DNS, 80/443, CAA | Dominio aún no activo o puerto de validación bloqueado |
| La dirección SSH sigue mostrando 22 | GITLAB_OMNIBUS_CONFIG | gitlab_shell_ssh_port no configurado o no aplicado |
| Conexión al 2222 rechazada | Puertos de Compose, UFW, grupo de seguridad | Puerto no asignado o regla de firewall ausente |
| El Runner sigue offline | Registros del Runner, URL, certificado | URL incorrecta, Token incorrecto o cadena de certificados no confiable |
| El Job sigue pending | Scope del Runner, tags, estado de pausa | El proyecto no tiene un Runner en línea que coincida |
| La copia de seguridad no se puede restaurar | Versión, CE/EE, Secrets | Versión de destino distinta o falta la copia de seguridad de la configuración |
El orden general de diagnóstico es revisar primero los recursos, luego el estado del contenedor y por último los registros del servicio correspondiente:
free -h
df -h
docker compose ps
docker compose logs --tail=200 gitlab
docker exec -it gitlab gitlab-ctl tail
docker logs --tail=200 gitlab-runner
- Si necesitas alojamiento de código, MR, permisos, Registry y CI/CD todo en uno, elige GitLab, pero prepara suficiente memoria y tiempo de mantenimiento.
- Si solo necesitas Git privado ligero, Issues y colaboración básica, elige Gitea, más llevadero en un VPS de bajos recursos.
- Si mantienes el código en GitHub y solo quieres controlar la máquina de compilación, elige el Runner autoalojado de GitHub Actions.
Primero completa cuatro cosas en un VPS no crítico: inicio de sesión HTTPS, push por SSH, un Job de CI mínimo y restauración en otra máquina. Cuando las cuatro funcionen, migra los repositorios de producción; de lo contrario, "el contenedor puede arrancar" todavía está muy lejos de un GitLab utilizable.