Saltar al contenido principal

mTLS y despliegue

Cómo proteger un proyecto de OneEntry con un token o un certificado mTLS y desplegar la aplicación en un servidor con Nginx, Docker y GitLab o GitHub.

Parte 1: Configurar mTLS​

Proteger la API​

  1. Token: genera un token en la configuración de OneEntry y envíalo en el encabezado de solicitud x-app-token.
  2. mTLS: activa mTLS en tu panel de OneEntry y genera un certificado en la configuración de OneEntry.

Configurar el certificado​

  1. En tu panel, abre la pestaña Access y cambia de token a mTLS.
  2. Genera un certificado nuevo en OneEntry (Settings → Application Certificates → Create New Certificate).
  3. Descárgalo y extráelo en una carpeta cert en la raíz de tu proyecto.

Configurar el entorno local (ejemplo con React)​

  1. Descarga setupProxy.js y guárdalo en la carpeta src.
  2. Establece el parámetro target con la dirección de tu proyecto.
  3. Instala http-proxy-middleware: npm install http-proxy-middleware.
  4. Inicia la aplicación.

Inicializar el SDK​

Con mTLS activado, la API no comprueba el token de la aplicación. Inicializa el SDK con la URL de tu proyecto como siempre. El SDK 1.0.175 sigue exigiendo un token no vacío, así que pasa cualquier cadena de relleno:

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'mtls', // not checked when mTLS is enabled
});

Parte 2: Configuración del servidor​

Preparar el servidor​

  1. Actualiza la información de los repositorios: apt update.
  2. Añade el repositorio de Docker e instala los paquetes: apt install nginx certbot docker-ce pwgen.

Configuración de UFW​

  1. Bloquea todas las conexiones entrantes: ufw default deny incoming.
  2. Permite todas las conexiones salientes: ufw default allow outgoing.
  3. Permite las conexiones TCP entrantes en los puertos 22, 80 y 443: ufw allow 22,80,443/tcp.

Configuración de SSH​

  1. Edita la configuración del daemon SSH: nano /etc/ssh/sshd_config.
  2. Establece PasswordAuthentication no.
  3. Reinicia el daemon SSH: systemctl restart ssh.

Configuración de Nginx​

  1. Elimina el archivo de configuración predeterminado: rm /etc/nginx/sites-available/default.
  2. Crea un nuevo archivo de configuración: nano /etc/nginx/sites-available/my_app.
  3. Descarga la configuración de Nginx de OneEntry y sustituye "your_domain.com" por tu dominio.
  4. Ejecuta: ln -s /etc/nginx/sites-available/my_app /etc/nginx/sites-enabled, sustituyendo "my_app" por el nombre de tu archivo de configuración.
  5. Emite los certificados SSL con Certbot: certbot certonly --webroot -w /var/www/html -d your_domain.
  6. Comprueba la renovación automática de certificados: certbot renew --dry-run.
  7. Edita la tarea cron de Certbot para que Nginx recargue su configuración después de emitir los certificados: nano /etc/cron.d/certbot, sustituyendo la última línea por: echo "0 */12 * * * root certbot -q renew && nginx -s reload" > /etc/cron.d/certbot
  8. Descomenta las líneas del archivo de configuración nano /etc/nginx/sites-available/my_app (donde my_app es el nombre de tu archivo de configuración).
  9. Comprueba la configuración de Nginx: nginx -t.
  10. Recarga Nginx después de cada cambio: nginx -s reload.

Parte 3: Desplegar la aplicación con GitLab o GitHub​

Acceso del runner. El usuario del runner de GitHub se une a los grupos docker y sudo, y el runner de GitLab se ejecuta en modo privilegiado con el socket de Docker del host. Ambos dan control de nivel root sobre el host, así que registra el runner solo para tu propio repositorio y no le permitas ejecutar trabajos de forks ni de merge requests que no sean de confianza. Las versiones de las imágenes son las que se usaron para probar esta guía; usa versiones actuales con soporte de gitlab/gitlab-runner y docker.

GitHub

Crear un usuario para el runner de GitHub​

  1. Genera una contraseña: pwgen -s 15 1.
  2. Crea un nuevo usuario: useradd -m github-runner.
  3. Establece una contraseña para él: passwd github-runner.
  4. Añade el nuevo usuario a los grupos: usermod -aG docker github-runner y usermod -aG sudo github-runner.
  5. Cambia el shell del usuario del runner: chsh -s /bin/bash github-runner.
  6. Cambia al nuevo usuario: sudo su - github-runner.

Configurar el runner de GitHub​

  1. Crea un runner: en la configuración de tu repositorio, abre Actions → Runners y haz clic en New self-hosted runner.
  2. Sigue las instrucciones del bloque Download y ejecuta el primer comando del bloque Configure.
  3. Añade el runner al inicio automático del sistema: sudo ./svc.sh install. Introduce la contraseña que generaste antes.
  4. Inicia el runner: sudo ./svc.sh start.
  5. En Actions → Runners, comprueba que el runner está en ejecución.
  6. Vuelve al usuario root.
  7. Crea un directorio de trabajo: mkdir -p /var/apps/frontend.
  8. Concede permisos al usuario github-runner: chown -R github-runner:docker /var/apps/frontend.

Configurar las variables de entorno en GitHub​

  1. Crea las variables DOMAIN, MTLS_USER_CERT y MTLS_USER_KEY en tu repositorio de GitHub (Settings → Secrets and Variables).
  2. Genera un certificado en OneEntry y coloca el certificado y la clave en las variables. Establece DOMAIN con la dirección de tu proyecto sin https.
  3. Descarga el archivo docker-compose.yml y los dos archivos comprimidos .github y .docker.
  4. Coloca docker-compose.yml y los dos archivos comprimidos en la carpeta raíz de tu proyecto y extráelos (después puedes eliminar los archivos comprimidos).
  5. Haz push a tu repositorio.
  6. Sigue la ejecución en la pestaña Actions.
  7. Abre la aplicación en el navegador para comprobar que está disponible.
GitLab

Preparar la configuración del runner de GitLab (executor Docker)​

  1. Crea los directorios necesarios: mkdir -p /var/apps/gitlab-runner/volumes/etc/gitlab-runner.

  2. Crea docker-compose.yaml:

    cat <<EOT > /var/apps/gitlab-runner/docker-compose.yaml
    version: '3'
    services:
      runner:
        image: 'gitlab/gitlab-runner:v16.2.0'
        restart: always
        container_name: 'gitlab-runner'
        privileged: true
        volumes:
          - './volumes/etc/gitlab-runner:/etc/gitlab-runner'
          - '/var/run/docker.sock:/var/run/docker.sock'
    EOT

Registro del runner de GitLab​

  1. Abre Settings → CI/CD → Runners y haz clic en New project runner.
  2. Establece las etiquetas docker, frontend y crea el runner.
  3. Ve al directorio del runner: cd /var/apps/gitlab-runner.
  4. Ejecuta el comando para iniciar el proceso de registro: docker compose run runner register.
  5. Introduce la URL de GitLab, por ejemplo https://gitlab.com/.
  6. Copia el token de registro de la sección Runners del proyecto en GitLab y pégalo en la terminal.
  7. Establece el executor en docker.
  8. Establece la imagen predeterminada en docker:20.10.16.

Configuración de variables de entorno en GitLab​

  1. Crea las variables DOMAIN, MTLS_USER_CERT y MTLS_USER_KEY en tu repositorio de GitLab (Settings → CI/CD → Variables).
  2. Genera un certificado en OneEntry, coloca el certificado y la clave en las variables y establece DOMAIN con la dirección de tu proyecto sin https.
  3. Descarga docker-compose.yml, el archivo .gitlab-ci.yml y el archivo .docker, colócalos en la raíz de tu proyecto y extrae los archivos comprimidos (después puedes eliminarlos).

Configuración del runner de GitLab​

  1. Edita el archivo de configuración: nano volumes/etc/gitlab-runner/config.toml.
  2. Establece el parámetro privileged en true para habilitar Docker-in-Docker.
  3. Cambia el valor de volumes a ['/var/run/docker.sock:/var/run/docker.sock', '/cache'] para que Docker funcione correctamente.
  4. Añade user = 'gitlab-runner' al principio del archivo para ejecutar el runner como ese usuario.
  5. Guarda los cambios y sal del editor.

Iniciar y comprobar el runner de GitLab​

  1. Inicia el runner: docker compose up -d.
  2. En GitLab, comprueba que el runner está activo; su estado se muestra en la sección Runners del proyecto.

Configurar un runner adicional en el host (executor shell)​

  1. Sigue las instrucciones para instalar un runner adicional que se ejecute directamente en el host, no en Docker.
  2. Establece las etiquetas del runner: shell, frontend.

Permisos del runner​

  1. Añade el usuario al grupo: usermod -aG docker gitlab-runner.
  2. Para cambiar el propietario y el grupo de un archivo o directorio: chown -R gitlab-runner:docker /var/apps/frontend.

Comprobación final​

  1. Comprueba que todos los runners están configurados y listos.
  2. Haz push a tu repositorio.
  3. Sigue el progreso en Build → Pipelines.
  4. Abre la aplicación en el navegador para comprobar que está disponible.