Marcación Documentación
Conoce el producto Iniciar sesión
Equipo técnico

Instalación y despliegue

Cómo poner Marcación Remota en un servidor propio: dependencias, configuración, Microsoft Entra ID, gunicorn con systemd, nginx con HTTPS, respaldos y actualizaciones.

Arquitectura

Requisitos

Instalación

cd /opt
git clone <repositorio> marcacion && cd marcacion
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env        # y completa los valores
chmod 600 .env

Crea el primer administrador si vas a usar usuarios locales:

.venv/bin/flask --app run create-admin admin@empresa.com.py "Nombre Apellido"

Las tablas se crean solas al primer arranque, y las columnas nuevas de versiones posteriores se agregan automáticamente al iniciar.

Variables de entorno

Se leen del archivo .env (la unidad de systemd lo carga con EnvironmentFile).

VariableDescripción
ENTRA_TENANT_ID, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRETDatos del registro de la aplicación en Entra ID. Si faltan (o están en ceros), Entra queda desactivado.
ENTRA_REDIRECT_URIOpcional. https://tu-dominio/auth/callback. Debe coincidir exactamente con el registrado en Azure.
ENTRA_ADMIN_ROLEValor del rol de aplicación que concede administrador (por defecto Admin).
ENTRA_ADMIN_EMAILSCorreos (o UPN) administradores. Pensado para el primer arranque; varios valores separados por coma, punto y coma o espacio. Si es posible, prefiere el rol de aplicación o ENTRA_ADMIN_OIDS.
ENTRA_ADMIN_OIDSIdentificadores de objeto (oid) de Entra ID de los administradores: es el identificador más sólido, porque el correo puede cambiar.
ENTRA_ALLOW_GUESTS1 permite el ingreso de cuentas invitadas (B2B). Por defecto se rechazan.
ENTRA_REAUTH_HOURSHoras tras las cuales un usuario de Entra ID debe volver a iniciar sesión, para revalidar su estado y rol (por defecto 24).
AUTH_LOCAL_ENABLED1 o 0 fuerza el login local. Sin definir, solo está activo si Entra no está configurado.
SECRET_KEYClave de sesión: al menos 32 caracteres aleatorios (la aplicación no arranca con una más corta). Si no se define, se genera en instance/secret.key (solo desarrollo). En producción defínela siempre.
DATABASE_URLURI de SQLAlchemy. Por defecto sqlite:///marcacion.db.
SESSION_COOKIE_SECURELas cookies de sesión son Secure por defecto. Usa 0 solo en desarrollo local sin HTTPS.
TRUST_PROXY1 respeta los encabezados X-Forwarded-* del proxy. Es necesario detrás de nginx: sin él, la dirección IP que ve la aplicación es la del proxy.
TRUSTED_HOSTSNombres de host aceptados, separados por coma. Si se omite y existe ENTRA_REDIRECT_URI, se usa su dominio.

Ejemplo de .env de producción:

ENTRA_TENANT_ID=<id-del-directorio>
ENTRA_CLIENT_ID=<id-de-la-aplicacion>
ENTRA_CLIENT_SECRET=<valor-del-secreto>
ENTRA_REDIRECT_URI=https://marcaciones.empresa.com/auth/callback
ENTRA_ADMIN_ROLE=Admin
ENTRA_ADMIN_OIDS=<oid-del-administrador>
AUTH_LOCAL_ENABLED=1
SECRET_KEY=<cadena-aleatoria-de-64-caracteres>
TRUST_PROXY=1
Protege el archivo .env

Contiene secretos. Mantén permisos 600, no lo subas a un repositorio y rota el secreto de cliente y la SECRET_KEY si alguna vez se expusieron.

Registrar la aplicación en Microsoft Entra ID

  1. Registros de aplicaciones → Nuevo registro (cuentas de este directorio organizativo).
  2. Plataforma Web, URI de redirección https://tu-dominio/auth/callback.
  3. Certificados y secretos: crea un secreto de cliente y copia su valor a ENTRA_CLIENT_SECRET.
  4. Permisos de API: Microsoft Graph → delegado → User.Read (viene por defecto).
  5. Roles de aplicación: crea un rol con valor Admin y asígnalo a los administradores en Aplicaciones empresariales → Usuarios y grupos.
  6. Opcional: activa Asignación requerida en la aplicación empresarial para limitar quién puede entrar.
  7. Opcional, para importar personas desde Entra ID: Permisos de API → Microsoft Graph → permiso de aplicación User.Read.All y Conceder consentimiento de administrador.

gunicorn con systemd

Archivo /etc/systemd/system/marcacion.service. Ejecuta la aplicación con un usuario de sistema dedicado y sin privilegios (sin sudo) y con el sistema de archivos protegido:

[Unit]
Description=Marcación Remota (Flask + gunicorn)
After=network-online.target
Wants=network-online.target

[Service]
User=marcacion
Group=www-data
WorkingDirectory=/opt/marcacion
EnvironmentFile=/opt/marcacion/.env
RuntimeDirectory=marcacion
RuntimeDirectoryMode=0750
ExecStart=/opt/marcacion/.venv/bin/gunicorn \
    --workers 1 --threads 4 --timeout 60 --no-control-socket \
    --bind unix:/run/marcacion/marcacion.sock -m 007 \
    --access-logfile - --error-logfile - \
    run:app
Restart=on-failure
RestartSec=5
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ReadWritePaths=/opt/marcacion/instance
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
RestrictNamespaces=true
LockPersonality=true
RestrictRealtime=true
CapabilityBoundingSet=

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now marcacion
sudo systemctl status marcacion
systemd-analyze security marcacion   # nivel de exposición del servicio
Límite de intentos de inicio de sesión

Los intentos fallidos se registran en la base de datos, así que el límite se mantiene tras reinicios y aunque haya varios procesos. Detrás de nginx, configura TRUST_PROXY=1 para que se cuenten por la IP real del cliente y agrega además un límite de frecuencia en nginx para /login (ver abajo).

nginx con HTTPS

Archivo /etc/nginx/conf.d/marcacion.conf (certbot agrega el bloque 443 y la redirección):

limit_req_zone $binary_remote_addr zone=marcacion_login:10m rate=10r/m;

upstream marcacion_app {
    server unix:/run/marcacion/marcacion.sock fail_timeout=0;
}

server {
    server_name marcacion.empresa.com;
    server_tokens off;
    client_max_body_size 6m;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # nunca se sirven archivos ocultos ni copias de respaldo
    location ~ /\. { deny all; }
    location ~* \.(bak|swp|new|orig|old|log|sql|db)(-[^/]*)?$ { deny all; }

    location /static/ {
        alias /opt/marcacion/app/static/;
        expires 7d;
        add_header Cache-Control "public";
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
        add_header X-Content-Type-Options "nosniff" always;
    }

    location = /login {
        limit_req zone=marcacion_login burst=8 nodelay;
        limit_req_status 429;
        proxy_pass http://marcacion_app;
        proxy_http_version 1.1;
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_redirect off;
    }

    location / {
        proxy_pass http://marcacion_app;
        proxy_http_version 1.1;
        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;
        proxy_set_header X-Forwarded-Host $host;
        proxy_redirect off;
        proxy_read_timeout 60s;
    }
}
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d marcacion.empresa.com --redirect
Archivos estáticos y caché

Con la caché de 7 días de /static/, la aplicación agrega ?v=<fecha de modificación> a cada archivo estático: al actualizar la aplicación, los navegadores descargan los cambios de inmediato sin esperar a que venza la caché. Las librerías de terceros (Bootstrap, íconos, Chart.js, Leaflet y la tipografía) se sirven desde /static/vendor/, sin depender de CDN externos.

Las rutas /manifest.webmanifest, /sw.js, /offline, /docs/ y /producto las atiende la aplicación y son públicas (no requieren iniciar sesión).

Respaldos

Respalda dos cosas: la base de datos y la carpeta instance/uploads (selfies y fotos). No incluyas instance/secret.key ni .env en respaldos sin cifrar. Guarda las copias fuera del servidor y prueba la restauración periódicamente. Para SQLite, usa la API de respaldo para obtener una copia consistente con la aplicación en marcha:

cd /opt/marcacion
.venv/bin/python -c "import sqlite3; s=sqlite3.connect('instance/marcacion.db'); d=sqlite3.connect('/ruta/respaldos/marcacion-$(date +%F).db'); s.backup(d)"
tar czf /ruta/respaldos/uploads-$(date +%F).tgz instance/uploads

Actualizar a una versión nueva

  1. Haz un respaldo de la base de datos (ver arriba).
  2. Copia los archivos nuevos de app/ (o git pull si el servidor es un clon). Guarda las copias de lo reemplazado fuera de app/static/, que es público.
  3. Si cambió requirements.txt: .venv/bin/pip install -r requirements.txt.
  4. sudo systemctl restart marcacion y revisa sudo journalctl -u marcacion -n 30.

Comandos útiles

ComandoPara qué
flask --app run create-admin correo "Nombre"Crea un administrador local.
flask --app run purge-selfies --days 90Política de retención: elimina del disco las selfies con más de N días (la marcación se conserva).
flask --app run seed --resetSolo desarrollo: borra todo y carga datos de demostración. Se niega a ejecutarse si la base tiene usuarios reales.
python -m pytestEjecuta las pruebas automáticas.
journalctl -u marcacion -fSigue los registros de la aplicación.
No uses seed en producción

seed --reset elimina todos los datos. Está pensado solo para desarrollo y demostraciones.

Lista de verificación tras instalar


© 2026 Login S.A. Todos los derechos reservados. Esta documentación es pública y no requiere iniciar sesión.