Servidor Git Autoalojado con minimal-git-server

Esta guía explica cómo ejecutar un servidor Git ligero usando la imagen Docker ghcr.io/mcarbonne/minimal-git-server. El servidor proporciona acceso SSH con un shell restringido que permite crear, listar, renombrar y eliminar repositorios Git, además de las operaciones normales de Git (clone, push, pull, etc.).

Requisitos previos

• Docker y Docker Compose instalados en la máquina anfitriona.
• Git cliente en cualquier máquina que vaya a acceder al servidor.
• Cliente SSH (normalmente ya disponible en Linux/macOS; en Windows se puede usar PowerShell con OpenSSH o Git Bash).

Inicio rápido

1. Crear la estructura de directorios

mkdir git-server
cd git-server
mkdir repos ssh

Donde:

2. Crear el archivo de configuración config.yml

El servidor autentica a los usuarios mediante claves públicas SSH. Cada usuario debe tener una entrada en config.yml. El usuario tony se usa en los ejemplos; reemplaza la clave con tu propia clave pública.

Crea config.yml:

users:
  - name: tony
    public_key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... (tu clave pública aquí)"

Puedes añadir varios usuarios. El servidor buscará este archivo dentro del contenedor en /srv/config.yml.

Importante: La clave pública debe estar en el formato de una sola línea como aparece en ~/.ssh/id_ed25519.pub o ~/.ssh/id_rsa.pub. Sin saltos de línea adicionales.

3. Crear docker-compose.yml

Guarda el siguiente contenido como docker-compose.yml:

services:
  git-server:
    image: ghcr.io/mcarbonne/minimal-git-server:2
    container_name: git-server
    restart: unless-stopped
    ports:
      - "2222:22"
    volumes:
      - ./ssh:/srv/ssh
      - ./repos:/srv/git
      - ./config.yml:/srv/config.yml:ro

4. Iniciar el contenedor

docker compose up -d

Verifica que el contenedor esté funcionando:

docker ps

5. Configurar el cliente SSH (en tu máquina local)

Añade una entrada a tu archivo ~/.ssh/config para simplificar la conexión:

Host gitbox
    HostName localhost
    Port 2222
    User tony

Ahora prueba la conexión:

ssh gitbox

Deberías ver un mensaje de bienvenida con la lista de comandos disponibles:

Availables commands :
create:  [REPO_NAME] create a git repo
exists:  [REPO_NAME] if REPO_NAME exists and is a valid git repository, return 0 otherwise 1
list:    list all available repositories
remove:  [TARGET] remove TARGET directory/repo
rename:  [SOURCE TARGET] rename SOURCE to TARGET. Might either be folders of git repos
show:    [REPO_NAME] show clone URL

Nota: Si ves "Permission denied", verifica que la clave pública en config.yml sea correcta y que tu agente SSH local o archivo de clave esté bien configurado.

Administración de repositorios

Todos los comandos se envían vía SSH usando el alias gitbox.

Listar todos los repositorios

ssh gitbox list

Crear un nuevo repositorio

ssh gitbox create miproyecto.git

Los nombres de repositorio deberían terminar en .git (convención de repositorio desnudo), aunque el servidor también funciona sin el sufijo.

Comprobar si existe un repositorio

ssh gitbox exists miproyecto.git

Sale con código 0 si existe, 1 si no.

Mostrar la URL de clonación de un repositorio

ssh gitbox show miproyecto.git

La salida será algo como:

Clone URL: git@gitbox:miproyecto.git

Renombrar un repositorio

ssh gitbox rename nombreviejo.git nombrenuevo.git

Eliminar un repositorio

ssh gitbox remove miproyecto.git

Operaciones Git (clone, push, pull)

Después de que exista un repositorio, usa los comandos normales de Git con el alias SSH gitbox.

Clonar un repositorio

git clone git@gitbox:miproyecto.git

O, si el repositorio ya es conocido:

git clone gitbox:miproyecto.git

Añadir un remoto a un repositorio local existente

git remote add origin git@gitbox:miproyecto.git

Enviar cambios al servidor (push)

git push -u origin main

Traer cambios del servidor (pull)

git pull origin main

Todas las operaciones normales de Git funcionan exactamente igual que con GitHub, GitLab o cualquier otro servidor Git basado en SSH.

Añadir o eliminar usuarios

1. Edita config.yml en el anfitrión.

   • Añade un nuevo bloque de usuario bajo users:.
   • Elimina el bloque de un usuario existente.

2. Reinicia el contenedor para recargar la configuración:

docker compose restart

Ejemplo con dos usuarios

users:
  - name: tony
    public_key: "ssh-ed25519 AAAA...tony@work"
  - name: alice
    public_key: "ssh-rsa AAAAB3...alice@home"

Después de reiniciar, cada usuario puede conectarse con su propia clave SSH y usar los mismos comandos.

Copias de seguridad y restauraciones

Todos los repositorios se almacenan en el anfitrión bajo ./repos. Las claves de host SSH están en ./ssh.

Copia de seguridad

tar czf git-server-backup.tar.gz repos/ ssh/ config.yml

Restauración

tar xzf git-server-backup.tar.gz -C /ruta/a/git-server/
docker compose up -d

Solución de problemas

"Permission denied (publickey)"

• Asegúrate de que la clave pública en config.yml coincida exactamente con la clave privada que usa tu cliente SSH.
• Verifica que ~/.ssh/config use el User y Port correctos.
• Revisa los logs del contenedor: docker logs git-server.

No se puede clonar: repositorio no encontrado

• Primero crea el repositorio con ssh gitbox create nombrerepositorio.git.
• Usa el nombre exacto que muestra ssh gitbox list.

El contenedor no arranca

• Busca errores con docker compose logs.
• Asegúrate de que config.yml sea YAML válido y esté en el mismo directorio que docker-compose.yml.
• Comprueba que el puerto 2222 del anfitrión no esté ya en uso.

Detener y eliminar el servidor

docker compose down

Para eliminar también todos los repositorios y la configuración (irreversible):

rm -rf repos ssh config.yml

Personalización

• Cambiar el puerto SSH: Modifica el mapeo ports en docker-compose.yml (ej. "2223:22") y actualiza tu ~/.ssh/config en consecuencia.
• Usar un nombre de host diferente: Reemplaza localhost por la IP o nombre de dominio de tu servidor en la configuración SSH y en los remotos de Git.
• Rutas de volúmenes: Los directorios ./repos y ./ssh se pueden mover a cualquier ubicación (por ejemplo, un disco externo). Actualiza los volúmenes en consecuencia.

Consideraciones de seguridad

• El servidor ejecuta un shell mínimo y restringido en una imagen de Alpine Linux: los usuarios no pueden ejecutar comandos arbitrarios del sistema.
• Las claves SSH son el único método de autenticación (sin contraseñas).
• Actualizaciones periódicas: ejecuta docker compose pull y recrea el contenedor para obtener la imagen más reciente.
• Cortafuegos: expone el puerto SSH (ej. 2222) solo a redes de confianza.

Resumen de comandos útiles

Esta configuración te proporciona un servidor Git autoalojado completamente funcional con un consumo mínimo de recursos, ideal para equipos pequeños o proyectos personales.