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
- Aplicación: Flask (Python 3.12) con SQLAlchemy. Interfaz HTML renderizada en el servidor con Bootstrap, más JavaScript propio para la marcación y los paneles.
- Base de datos: SQLite por defecto (
instance/marcacion.db); admite otra base medianteDATABASE_URL. - Servidor de aplicación: gunicorn detrás de nginx, que termina TLS y sirve
/static/. - Autenticación: usuarios locales y/o Microsoft Entra ID (OpenID Connect).
- Archivos: selfies y fotos de perfil en
instance/uploads/. - Mapas: Leaflet con teselas de OpenStreetMap. Estilos e íconos se cargan por CDN.
Requisitos
- Linux con Python 3.12 y
venv. - Un dominio con HTTPS (obligatorio: geolocalización, cámara, instalación como app y Entra ID lo exigen).
- nginx (o cualquier proxy inverso con TLS).
- Zona horaria del sistema operativo configurada a la de tu país (Paraguay:
America/Asuncion): la aplicación usa la hora local del servidor.
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).
| Variable | Descripción |
|---|---|
ENTRA_TENANT_ID, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET | Datos del registro de la aplicación en Entra ID. Si faltan (o están en ceros), Entra queda desactivado. |
ENTRA_REDIRECT_URI | Opcional. https://tu-dominio/auth/callback. Debe coincidir exactamente con el registrado en Azure. |
ENTRA_ADMIN_ROLE | Valor del rol de aplicación que concede administrador (por defecto Admin). |
ENTRA_ADMIN_EMAILS | Correos (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_OIDS | Identificadores de objeto (oid) de Entra ID de los administradores: es el identificador más sólido, porque el correo puede cambiar. |
ENTRA_ALLOW_GUESTS | 1 permite el ingreso de cuentas invitadas (B2B). Por defecto se rechazan. |
ENTRA_REAUTH_HOURS | Horas 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_ENABLED | 1 o 0 fuerza el login local. Sin definir, solo está activo si Entra no está configurado. |
SECRET_KEY | Clave 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_URL | URI de SQLAlchemy. Por defecto sqlite:///marcacion.db. |
SESSION_COOKIE_SECURE | Las cookies de sesión son Secure por defecto. Usa 0 solo en desarrollo local sin HTTPS. |
TRUST_PROXY | 1 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_HOSTS | Nombres 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
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
- Registros de aplicaciones → Nuevo registro (cuentas de este directorio organizativo).
- Plataforma Web, URI de redirección
https://tu-dominio/auth/callback. - Certificados y secretos: crea un secreto de cliente y copia su valor a
ENTRA_CLIENT_SECRET. - Permisos de API: Microsoft Graph → delegado →
User.Read(viene por defecto). - Roles de aplicación: crea un rol con valor
Adminy asígnalo a los administradores en Aplicaciones empresariales → Usuarios y grupos. - Opcional: activa Asignación requerida en la aplicación empresarial para limitar quién puede entrar.
- Opcional, para importar personas desde Entra ID: Permisos de API → Microsoft Graph → permiso de aplicación
User.Read.Ally 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
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
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
- Haz un respaldo de la base de datos (ver arriba).
- Copia los archivos nuevos de
app/(ogit pullsi el servidor es un clon). Guarda las copias de lo reemplazado fuera deapp/static/, que es público. - Si cambió
requirements.txt:.venv/bin/pip install -r requirements.txt. sudo systemctl restart marcaciony revisasudo journalctl -u marcacion -n 30.
Comandos útiles
| Comando | Para qué |
|---|---|
flask --app run create-admin correo "Nombre" | Crea un administrador local. |
flask --app run purge-selfies --days 90 | Polí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 --reset | Solo desarrollo: borra todo y carga datos de demostración. Se niega a ejecutarse si la base tiene usuarios reales. |
python -m pytest | Ejecuta las pruebas automáticas. |
journalctl -u marcacion -f | Sigue los registros de la aplicación. |
seed --reset elimina todos los datos. Está pensado solo para desarrollo y demostraciones.
Lista de verificación tras instalar
- El sitio abre por HTTPS y redirige desde HTTP.
- Puedes iniciar sesión (Microsoft y/o local) y el primer administrador ve la sección Administración.
- La zona horaria del servidor es la correcta (la hora del reloj de la pantalla de marcación coincide con la local).
- El navegador ofrece Instalar la aplicación y pide permiso de ubicación al marcar.
- Creaste al menos una ubicación y un turno (ver Gestión).
- Hay respaldos automáticos de la base de datos y de
instance/uploads.
© 2026 Login S.A. Todos los derechos reservados. Esta documentación es pública y no requiere iniciar sesión.