HUB
Sign inSign up

valkm/recuerdame_bot

By valkm

•Updated about 8 hours ago

Recordatorios personales para Telegram, instalables en NAS con Docker Compose.

Image
0

2.1K

valkm/recuerdame_bot repository overview

⁠🤖 Recuérdame Bot

Tu asistente personal de recordatorios en Telegram. Fechas naturales, recurrencias, notas y alertas para tu NAS o tu vida personal, en un bot ligero con Docker.

⁠Arquitecturas

La etiqueta latest ofrece imágenes linux/amd64 y linux/arm64. Docker selecciona automáticamente la arquitectura compatible.

⁠Instalación directa con Docker Compose

⁠Ejemplo Compose usando directamente Docker Hub

Si quieres crear tu propio docker-compose.yml sin clonar el repositorio, puedes partir de este ejemplo. Sustituye los valores de ejemplo por los tuyos antes de arrancar: Importante recuerdame, en el compose, va sin tilde, para evitar que dé errores el contenedor.

services:
  mibot:
    image: valkm/recuerdame_bot:latest
    container_name: recuerdame_bot
    restart: unless-stopped
    init: true
    environment:
      BOT_TOKEN: "PEGA_AQUI_EL_TOKEN_DE_BOTFATHER"
      ALLOWED_USER_IDS: "123456789"
      ALERT_API_TOKEN: "CAMBIA_ESTO_POR_UN_SECRETO_LARGO_Y_ALEATORIO"
      TZ: Europe/Madrid
    volumes:
      - ./data:/app/data
    ports:
      - "8787:8080"
    healthcheck:
      test:
        - CMD
        - python
        - -c
        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health', timeout=10)"
      interval: 1m
      timeout: 15s
      retries: 3
      start_period: 60s
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    networks:
      - mibot-net
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

networks:
  mibot-net:

El puerto 8787 queda accesible desde la red local del NAS. La API requiere ALERT_API_TOKEN; no configures un reenvío de este puerto desde Internet. Desde esa carpeta, arranca el bot con:

mkdir -p data
docker compose pull
docker compose up -d

Para fijar una versión, cambia latest por la etiqueta deseada, por ejemplo valkm/recuerdame_bot:1.1.1.

Abre el bot en Telegram y envía /menu. La guía de instalación completa y la configuración de Synology están más abajo.

Versión documentada: v1.1.1 · Consulta el historial de cambios⁠.

⁠Funciones

  • Crear recordatorios escribiendo en lenguaje natural (Recuérdame comprar leche.... o con /recordar.
  • Repeticiones diarias, semanales y mensuales, con opciones para pausar, reactivar y cambiar la frecuencia.
  • Botones para completar, posponer o cancelar un recordatorio; las repeticiones de avisos sin respuesta se pueden configurar.
  • Posibilidad de cancelar varios eventos de una vez, con el comando /cancelar seguido de la ID, Ej, /cancelar 21,22,23
  • Notas, etiquetas y enlaces asociados a recordatorios.
  • Detección de información de lanzamientos al enviar algunas URL compatibles. La fecha extraída depende del contenido y los metadatos públicos de cada sitio; conviene confirmarla antes de crear el recordatorio.
  • Menú interactivo en Telegram mediante /menu y menú de comandos nativo.
  • Historial y resumen de actividad.
  • API HTTP local para enviar alertas desde scripts y otros contenedores.
  • Aviso a los usuarios autorizados cuando el bot arranca, con versión y hora.
  • Estado del BOT
  • Interpretación ampliada de fechas explícitas en español, incluidos días de la semana, y validación de fechas y horas indicadas.
  • Comando /donate para apoyar voluntariamente el proyecto; no desbloquea funciones adicionales.

⁠📦 Requisitos

  • Docker Engine y Docker Compose.
  • Un bot de Telegram creado mediante @BotFather⁠.
  • El ID numérico de cada usuario autorizado.

⁠🤖 Para crear nuestro bot en Telegram

  • Abre Telegram.
  • Busca @BotFather⁠.
  • Ejecuta /newbot.
  • Ponle un nombre, por ejemplo MiBot Personal.
  • Elige un nombre de usuario terminado en bot.
  • Guarda el token que te proporcione.
  • Obtén tu identificador numérico de usuario.

Busca @userinfobot⁠ en Telegram y ejecuta /start para consultar tu ID numérico.

⁠🐳 Instalación con Docker Compose (IMPORTANTE LEER!, para el tema de permisos)

  1. Copia o clona este repositorio en una carpeta del servidor. En Synology, por ejemplo, /volume1/docker/recuerdame-bot.

  2. Edita docker-compose.yml y cambia BOT_TOKEN, ALLOWED_USER_IDS y ALERT_API_TOKEN por tus valores.

  3. Crea la carpeta persistente /data y prepara los permisos. Antes de arrancar el contenedor, crea el directorio de datos para la SQlite:

    mkdir -p data
    

    La aplicación se ejecuta dentro del contenedor con un usuario sin privilegios (UID/GID 10001:10001). Para que SQLite pueda crear y modificar la base de datos, el directorio persistente debe pertenecer a ese usuario. En Synology y otros sistemas Linux, ejecuta:

    sudo chown -R 10001:10001 data
    sudo chmod 755 data
    

    A continuación, descarga la imagen y arranca el servicio:

    docker compose pull
    docker compose up -d
    

    Importante: si SQLite muestra el error unable to open database file, comprueba los permisos del directorio /data y verifica que el usuario 10001 tiene permisos de escritura.

  4. Cuando el contenedor haya arrancado, revisa el estado y los registros:

    docker compose ps
    docker compose logs --tail=50
    

    El contenedor debe aparecer como healthy y los registros deben mostrar que el bot ha iniciado el polling correctamente.

  5. Abre el bot en Telegram y envía /start o /menu.

El bot usa long polling: no requiere dominio, certificado HTTPS ni puertos entrantes en el router. La API de alertas queda accesible en la red local mediante el puerto 8787 del NAS.

⁠⚙️ Configuración

VariableObligatoriaValor inicialDescripción
BOT_TOKENSí—Token del bot emitido por BotFather.
ALLOWED_USER_IDSSí—ID o lista de ID de Telegram separados por comas. Solo estos usuarios pueden usar el bot y recibir alertas.
ALERT_API_TOKENSí—Secreto de acceso a la API de alertas. Usa una cadena larga y aleatoria.
TIMEZONENoEurope/MadridZona horaria para fechas y horas de recordatorios.
TZNoEurope/MadridZona horaria del contenedor.
API_HOSTNo0.0.0.0Interfaz donde escucha la API dentro del contenedor.
API_PORTNo8080Puerto interno de la API.
DB_PATHNo/app/data/mibot.dbRuta de SQLite dentro del contenedor.
REMINDER_REPEAT_MINUTESNo30Minutos entre avisos persistentes (admite de 5 a 1440).
REMINDER_MAX_RETRIESNo3Número máximo de reintentos (admite de 0 a 10; 0 los desactiva).
LOG_LEVELNoINFONivel de registro, por ejemplo INFO o DEBUG.

Para más de un usuario, escribe los ID separados por comas, por ejemplo 111111111,222222222. No uses nombres de usuario como sustituto de los ID.

Para generar ALERT_API_TOKEN puedes generarlo con el comando:

openssl rand -hex 32

⁠⌨️ Comandos de Telegram

Los comandos del menú nativo y de /help siguen este orden:

NºComandoUso
1/menuAbrir el menú interactivo.
2/recordarCrear un recordatorio. También puedes enviar directamente el texto sin comando.
3/cancelar ID[, ID, ...]Cancelar uno o varios recordatorios, o detener recurrencias, conservando el historial.
4/hoyVer los recordatorios de hoy.
5/semanaVer los próximos siete días.
6/proximosMostrar los próximos recordatorios ordenados por fecha.
7/lista [#etiqueta]Mostrar recordatorios activos; opcionalmente filtrar por etiqueta.
8/etiqueta ID #Libros #CasaAsignar o quitar etiquetas.
9/nota ID textoAñadir o cambiar una nota. Usa /nota ID borrar para quitarla.
10/frecuencia ID diaria|semanal|mensualCambiar la periodicidad de una recurrencia.
11/pausar IDPausar una recurrencia.
12/reactivar IDReactivar una recurrencia pausada.
13/historial [límite]Consultar acciones recientes (límite de 1 a 20; por defecto 15).
14/estadisticas [días]Resumen de actividad (de 1 a 365 días; por defecto 30).
15/salirSalir de una acción guiada en curso.
16/helpVer ayuda y ejemplos.
17/estadoConsultar el estado del bot y la configuración de avisos persistentes.
18/donateInformación para apoyar voluntariamente el proyecto; no desbloquea funciones adicionales.

/start también abre el menú interactivo como alias de inicio.

Ejemplos:

Recuérdame comprar leche mañana a las 18:30
/recordar renovar certificado dentro de 20 días
/recordar revisar copias cada semana #NAS nota: comprobar el último backup
/cancelar 22, 21, 20
/proximos
/lista #NAS
/nota 12 descargar en epub
/etiqueta 12 #Libros
/etiqueta 12 borrar

Si no indicas una hora, el bot usa las 09:00 en la zona horaria configurada.

⁠🔌 API local de alertas

Desde el propio servidor, define en la terminal el mismo ALERT_API_TOKEN que configuraste en docker-compose.yml y envía un aviso con:

# Define ALERT_API_TOKEN con el mismo valor del Compose antes de usar curl.
curl -X POST "http://127.0.0.1:8787/notify" \
  -H "Authorization: Bearer $ALERT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"NAS","message":"El backup ha terminado","severity":"info"}'

La API admite info, warning y critical; el título y el mensaje son obligatorios. El endpoint /health sirve para comprobar que la API está activa:

curl "http://127.0.0.1:8787/health"

El puerto 8787 queda publicado en las interfaces de red del NAS. Para que otro contenedor acceda a la API, ambos servicios deben compartir una red Docker y ese contenedor debe usar http://mibot:8080/notify junto con el token. No configures un reenvío desde Internet.

⁠💾 Datos, copias y actualización

La base SQLite vive en data/ y persiste al recrear el contenedor. Se crea por primera vez al crear el contenedor. Haz una copia antes de actualizar o migrar el NAS. Para una copia SQLite consistente mientras el bot está en uso, puedes usar la API de backup integrada de Python dentro del contenedor:

stamp=$(date +%Y%m%d-%H%M%S)
docker compose exec -T -e BACKUP="/app/data/mibot-backup-$stamp.sqlite3" mibot \
  python -c 'import os, sqlite3; src=sqlite3.connect("/app/data/mibot.db"); dst=sqlite3.connect(os.environ["BACKUP"]); src.backup(dst); dst.close(); src.close(); print("Copia creada:", os.environ["BACKUP"])'

Para actualizar a la imagen publicada más reciente, sin borrar data/:

docker compose pull
docker compose up -d

Si prefieres construir desde el código fuente, usa el archivo adicional:

docker compose -f docker-compose.yml -f docker-compose.source.yml up -d --build

⁠🔐 Seguridad

  • Protege tus credenciales: no publiques tokens, ID privados ni el docker-compose.yml después de reemplazar los valores de ejemplo por credenciales reales. .gitignore excluye la base de datos y sus copias.
  • API de alertas: requiere ALERT_API_TOKEN y se publica en la red local del NAS. No configures un reenvío del puerto desde Internet.
  • Acceso limitado: el bot solo acepta mensajes de los ID incluidos en ALLOWED_USER_IDS.
  • Docker aislado: el contenedor no monta el socket de Docker ni puede administrar otros contenedores.
  • Una instancia por token: ejecuta un solo proceso de polling para cada bot de Telegram.

Consulta la guía completa en GitHub⁠, incluyendo todas las variables, comandos de Telegram y configuración de Synology.

Tag summary

Content type

Image

Digest

sha256:c527905c6…

Size

51.4 MB

Last updated

1 day ago

docker pull valkm/recuerdame_bot