Instalación

Esta página le lleva de la compra a un teléfono vinculado que envía su primer SMS. No supone ningún conocimiento previo del producto. Cuente con un cuarto de hora, la mitad dedicado a las descargas.

La instalación cabe en un solo comando. Un script instala Docker si falta, descarga los archivos de la última versión, comprueba que no han sido alterados, escribe la configuración, arranca la pasarela e instala un comando de explotación, sms-gateway. No tiene nada que compilar ni ninguna dirección de servidor que escribir.

Qué instala

La pasarela es un solo programa, que escucha en un solo puerto y guarda todo en una sola carpeta de datos (un volumen Docker). Funciona en un contenedor Docker, en su máquina.

Consecuencia práctica: hacer una copia de la carpeta de datos es hacer una copia de toda la instalación, y moverla es mover la pasarela (vea Copia de seguridad y restauración y Migrar a otro servidor).

Qué necesita

No se compila nada en su máquina: la pasarela se publica lista para funcionar en procesadores amd64 y arm64, y Docker elige la adecuada. Una máquina pequeña basta: la pasarela usa muy poca memoria, y el plan más pequeño de la mayoría de proveedores es suficiente para empezar.

El recorrido en cinco pasos

Paso 1: cree su cuenta y compre

Vaya a sms-gateway.araylab.com. El botón Comprar le pide primero que inicie sesión: introduzca su dirección de correo y recibirá un enlace de acceso. No hay contraseña que recordar. Llega a su espacio de cliente, vacío por ahora.

El pago lo gestiona Gumroad, que también emite la factura y se encarga del IVA. En Madagascar, el pago por Mobile Money (MVola, Orange Money, Airtel Money) se valida a mano: la licencia aparece después de esa validación, no al instante.

Una vez confirmado el pago, recibe un correo que anuncia que la licencia está lista. Por su seguridad, ese correo no contiene la clave: le remite a su espacio de cliente.

Paso 2: copie su clave de licencia

En el espacio de cliente, la licencia muestra su clave, con el formato XXXX-XXXX-XXXX-XXXX, y un botón para copiarla. Las instrucciones de instalación y el enlace de descarga de la aplicación Android aparecen también allí, en cuanto la licencia está activa.

Puede volver en cualquier momento para mostrar de nuevo la clave, y regenerarla si se ha filtrado (vea Regenerar la clave).

Paso 3: ejecute el comando de instalación

En la máquina que alojará la pasarela, en un terminal.

Linux (VPS, Oracle Cloud, servidor local, Raspberry Pi):

curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash

Sin opciones, el script le hace dos preguntas: si puede instalar Docker en caso de que falte, y si sus teléfonos llegarán a la pasarela mediante un nombre de dominio o en la red local (vea Elegir el modo). Para responder todo de antemano:

# Con un nombre de dominio: HTTPS automático (recomendado)
curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --domain sms.example.com --yes

# En la red local, sin nombre de dominio
curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --lan --yes

macOS: el mismo comando, con Docker Desktop instalado y arrancado antes. La instalación va a ~/sms-gateway, y el comando sms-gateway se coloca en esa carpeta.

Windows (se requiere Docker Desktop), en PowerShell abierto como administrador:

irm https://sms-gateway.araylab.com/install.ps1 | iex

En Windows, el script no pregunta por el modo: instala en modo red local por defecto. Para cambiarlo, defina estas variables en la misma ventana de PowerShell antes de ejecutar el comando:

$env:SMSGW_DOMAIN = "sms.example.com"
irm https://sms-gateway.araylab.com/install.ps1 | iex

Si falta Docker Desktop, el script de Windows ofrece instalarlo con winget, luego se detiene y le pide reiniciar Windows, arrancar Docker Desktop una vez y volver a ejecutar el comando. Instala en %ProgramData%\SmsGateway, abre el puerto 8080 en el cortafuegos de Windows para las redes privadas en modo red local, y abre el panel en su navegador.

Al final, cada script muestra la dirección del panel y el código de instalación que sirve para crear la cuenta de administrador (paso 4). En Linux y macOS, sms-gateway url vuelve a mostrar la dirección y sms-gateway setup-code el código, mientras no exista ninguna cuenta.

¿Prefiere leer el script antes? Enviar un script descargado a bash es confiar en él. Puede descargarlo, leerlo y luego ejecutarlo:

curl -fsSL https://sms-gateway.araylab.com/install.sh -o install.sh
less install.sh
sudo bash install.sh --domain sms.example.com

El script, por su parte, comprueba todo lo que descarga después con una suma SHA-256 publicada: un archivo que no coincide detiene la instalación antes de instalar nada.

Qué hace el script, en orden

1. Comprueba que se ejecuta como root en una máquina Linux amd64 o arm64 (o en macOS).
2. Instala Docker si falta, con el script oficial de Docker, después de preguntarle (o sin preguntar con --yes).
3. Busca la última versión publicada (o la indicada con --version), descarga sus archivos y comprueba su suma.
4. Pregunta el modo si ninguna opción lo ha fijado. En modo dominio, comprueba que el dominio apunta a esta máquina y que los puertos 80 y 443 están libres. Un problema da un aviso y una pregunta, no una parada: puede corregir el DNS después.
5. En modo red local, instala avahi-daemon, que hace que el nombre <nombre-de-la-máquina>.local se resuelva en su red.
6. Escribe la configuración en /opt/sms-gateway/.env, legible solo por root. Una configuración existente se conserva: volver a ejecutar el comando actualiza la pasarela sin borrar sus ajustes.
7. Descarga la pasarela, la arranca y espera a que responda (dos minutos como máximo).
8. Instala el comando sms-gateway y muestra la dirección del panel, el código de instalación y los pasos siguientes.

Las opciones (Linux y macOS)

Cómo se combinan las opciones:

• Sin --domain ni --lan, el script pregunta. Con --yes y sin modo en una primera instalación, se detiene: no hay modo por defecto, porque el modo equivocado da teléfonos que nunca se conectan.
• Al volver a ejecutarlo sobre una instalación existente, el modo y el puerto ya registrados se conservan. Indicar de nuevo --domain o --lan cambia el modo: la dirección pública cambia, y los teléfonos ya vinculados deben vincularse de nuevo.
• --port solo se tiene en cuenta en la primera instalación. Después, prevalece el puerto registrado en la configuración; cambie GATEWAY_PORT en el archivo .env (vea Ajustes que puede cambiar).
• --yes también responde sí a los avisos. En modo dominio, una instalación con un DNS erróneo o con los puertos 80/443 ocupados continúa igualmente: la pasarela funciona, pero el HTTPS no lo hará hasta que corrija la causa.

Paso 4: abra el panel, cree el administrador, pegue la clave

Abra la dirección mostrada por el script. Una instalación nueva abre la pantalla Crear la primera cuenta: Token de instalación, nombre, dirección de correo, contraseña. La contraseña debe tener al menos 12 caracteres. Esta primera cuenta es el superadministrador, y la pantalla que la crea se cierra definitivamente en cuanto existe una cuenta.

El token de instalación es el código de instalación mostrado al final del script. Demuestra que quien crea la cuenta tiene acceso a la máquina: sin él, el primer desconocido que encontrara en internet una pasarela recién instalada podría hacerse su administrador. Si ya no lo tiene delante:

El código desaparece en cuanto se crea la cuenta: los comandos anteriores responden entonces que ya no queda ninguno, y es lo esperado.

Crear la cuenta no inicia la sesión: la pantalla confirma la creación y luego le lleva a la pantalla de inicio de sesión, donde escribe la dirección de correo y la contraseña que acaba de elegir.

Una vez conectado, aparece una ventana Activar esta pasarela. Pegue la clave copiada en el paso 2. Se aceptan espacios, guiones y minúsculas. No hay nada más que escribir: la pasarela ya sabe cómo llegar a nuestro servidor de licencias.

Si nuestro servidor no responde en ese momento, la ventana indica Nuestro servidor no responde. Su clave se registra igualmente y nada se suspende: la pasarela envía con normalidad y reintenta la activación por sí sola. Una avería por nuestra parte nunca se trata como una licencia no válida. Detalles en Licencia.

Paso 5: instale la aplicación Android y vincule el teléfono

1. Descargue la aplicación desde su espacio de cliente, en el propio teléfono o en un ordenador y luego cópiela. La aplicación no está en Play Store: el enlace solo se da a los titulares de una licencia.
2. Instálela. Android le pide permitir la instalación desde la fuente utilizada (navegador o gestor de archivos). Permítalo para esta instalación.
3. En el panel, abra Dispositivos y haga clic en Vincular un dispositivo. Aparece un código QR, con un código de respaldo para un teléfono cuya cámara no funcione. Es válido durante cinco minutos y solo se puede usar una vez; Generar un código nuevo le da otro.
4. En la aplicación, escanee el código QR. El teléfono se conecta a la pasarela y aparece en línea en Dispositivos, con sus tarjetas SIM.
5. Envíe un SMS de prueba desde Envío rápido y luego respóndale desde otro teléfono: la respuesta aparece en Conversaciones.

La aplicación pide quedar exenta de la optimización de batería y muestra una notificación permanente: es lo que la mantiene activa en segundo plano. Mantenga el teléfono enchufado. Todo lo relativo a los teléfonos (SIM, cuota diaria, mantener el teléfono despierto) está en Dispositivos.

Si escribe la dirección a mano en lugar de escanear, escríbala completa, con https:// o http:// (https://sms.example.com o http://server.local:8080). Sin ello, la aplicación supone una conexión HTTPS, que falla en una instalación en red local.

Elegir el modo: dominio o red local

Es la única elección real de la instalación, y decide la dirección que marcan los teléfonos. Esa dirección se escribe en cada código QR de vinculación y el teléfono la conserva. Una dirección errónea da un código QR que se escanea perfectamente y un teléfono que nunca llega a nada.

Elija el modo dominio siempre que pueda: no tiene ninguna de las reservas siguientes.

Qué implica el modo red local

• La aplicación Android solo acepta conexiones sin cifrar hacia un nombre .local. Una dirección IP simple como http://192.168.1.20:8080 la rechaza el teléfono. Por eso el instalador usa http://<nombre-de-la-máquina>.local:8080.
• Compruebe que el teléfono resuelve ese nombre antes de seguir: abra http://<nombre-de-la-máquina>.local:8080/health en el navegador del teléfono, conectado al mismo wifi. Una respuesta {"status":"ok",...} significa que la vinculación puede funcionar.
• La sesión del panel circula sin cifrar por su red. El instalador fija GATEWAY_INSECURE_COOKIES=true; si no, los navegadores se negarían a mantener su sesión en HTTP simple. Aceptable en una red de empresa que usted controla, no en un wifi compartido.
• El nombre de la máquina no debe cambiar, ya que está escrito en los códigos QR. Renombrarla obliga a vincular de nuevo los teléfonos.
• Un wifi de invitados suele aislar a sus dispositivos: el teléfono ve internet pero no la máquina. La prueba /health anterior lo revela. Ponga los teléfonos en la red interna.

Todo lo específico de este recorrido (dirección fija, wifi de invitados, acceso desde el exterior) está en Servidor local.

Qué implica el modo dominio

• El DNS debe apuntar a la máquina antes de poder obtener el certificado. El script le avisa si no es así; el certificado se obtiene automáticamente en cuanto el DNS es correcto.
• Los puertos 80 y 443 deben ser accesibles desde internet, el 80 incluido: sirve para demostrar que el dominio es suyo. Ábralos en el cortafuegos de la máquina y en su proveedor de alojamiento, que a menudo también filtra.
• No se expone nada más: un pequeño servidor web (Caddy) gestiona el HTTPS delante de la pasarela, que solo escucha en la máquina.
• Si un proxy como Cloudflare está delante del dominio, desactívelo mientras se obtiene el certificado.

El comando sms-gateway

Instalado en Linux y macOS, se ejecuta como root (o con sudo) desde cualquier carpeta.

Volver a ejecutar el comando de instalación tiene el mismo efecto que sms-gateway update.

En Windows, no existe el comando sms-gateway. Abra PowerShell en %ProgramData%\SmsGateway y use Docker Compose directamente:

Mantenga el ordenador encendido y Docker Desktop configurado para arrancar con Windows: la pasarela solo funciona mientras Docker Desktop está en marcha.

Detener o reiniciar no pierde nada. Mientras la pasarela está parada, los teléfonos guardan los mensajes salientes y entrantes en su propia cola y los entregan cuando vuelve.

Regenerar la clave

En el espacio de cliente, Regenerar la clave sustituye su clave de licencia por una nueva. Hágalo si la clave se ha filtrado (un ticket de soporte, una captura de pantalla, un antiguo proveedor), o para liberar la licencia antes de instalar en otra máquina.

La pasarela instalada no se detiene. Sin embargo, ya no puede renovar su activación mientras lleve la antigua clave: abra Licencia en el panel e introduzca allí la nueva clave. Dos regeneraciones deben separarse al menos un minuto.

Resolución de problemas

Empiece siempre por sms-gateway status y luego sms-gateway logs.

Acceso a la red

La máquina necesita acceso HTTPS saliente a:

Si bck1.araylab.com está bloqueado, nada deja de funcionar, pero la pantalla de licencia seguirá diciendo que nuestro servidor no responde.

Ajustes que puede cambiar

El instalador escribe la configuración en /opt/sms-gateway/.env (legible solo por root; en Windows, %ProgramData%\SmsGateway\.env). Para una instalación estándar, no tiene nada que añadir. Todo lo que ajusta en el día a día (ventana de envío, reintentos, zona horaria, notificaciones, reglas de enrutamiento...) se configura en el panel, en Ajustes y las pantallas relacionadas, no aquí: vea Ajustes. Ningún ajuste del panel tiene una variable equivalente, y ninguna variable de abajo se puede cambiar desde el panel.

Después de editar el archivo .env, aplique el cambio con sms-gateway restart (en Windows: docker compose up -d en la carpeta de instalación). Una actualización o una nueva ejecución del instalador conserva el archivo; solo reescribe la versión y, si vuelve a indicar --domain o --lan, las líneas del modo.

En el archivo .env

Estas líneas las escribe el instalador. Puede editarlas, sabiendo qué controla cada una.

El archivo también lista, comentados, los ajustes siguientes (una actualización añade esa lista una vez a un .env escrito por una versión anterior). Quite el # delante de una línea para usarla y luego reinicie. El docker-compose.yml proporcionado transmite cada uno de ellos a la pasarela; ausente o vacío, la pasarela aplica su valor por defecto. Como viven en .env y no en docker-compose.yml, una actualización los conserva.

Interacciones que conviene conocer:

• El modo son cuatro líneas que van juntas: GATEWAY_PUBLIC_URL, GATEWAY_DOMAIN, COMPOSE_PROFILES y GATEWAY_BIND (más GATEWAY_INSECURE_COOKIES). Cambiar una sin las demás da, por ejemplo, un sitio HTTPS que funciona y teléfonos que no se vinculan. Para cambiar de modo o de dominio, vuelva a ejecutar el instalador con --domain o --lan: las reescribe juntas.
• Cambiar GATEWAY_PUBLIC_URL no actualiza los teléfonos ya vinculados: conservan la dirección de su código QR. Vincúlelos de nuevo después de un cambio así.
• Un GATEWAY_TRUSTED_PROXIES demasiado amplio (por ejemplo 0.0.0.0/0) permite a cualquiera hacerse pasar por cualquier dirección IP y eludir el bloqueo de inicio de sesión. Vacío, la pasarela ve a todos los visitantes con la dirección del proxy, y todos comparten los mismos límites.

Ajustes avanzados

La pasarela también lee las dos variables siguientes. No figuran en el archivo que escribe el instalador, porque una instalación de cliente rara vez las necesita.

No toque estas. Existen en el programa, pero una instalación de cliente no las necesita:

Las copias de seguridad no tienen variable: la copia automática se ajusta en el panel, en Ajustes > Copia de seguridad y exportación. Vea Copia de seguridad.

Dos reglas se aplican a todas las variables:

• Un valor vacío cuenta como ausente: se aplica el valor por defecto.
• Un valor no válido detiene la pasarela al arrancar, con un mensaje que nombra la variable, en lugar de funcionar con un valor que usted no eligió. Vea la sección siguiente.

Cuando la pasarela se niega a arrancar

El mensaje está en sms-gateway logs, en una línea que contiene gateway stopped. La pasarela se reinicia en bucle hasta que se corrige la causa.

Por qué se rechaza una dirección http:// simple: en HTTP, la sesión del panel circularía sin cifrar por internet. Solo se acepta sin HTTPS un nombre .local (modo red local) o localhost.

Por qué se rechaza el modo carrier sin tabla: no enrutaría nada por operador, y usted creería pagar la tarifa dentro de la misma red cuando paga la de otra red.

Una restauración que falla (vea Copia de seguridad y restauración) nunca impide el arranque: la pasarela arranca con la base de datos que tiene y registra el error.

La clave maestra

En el primer arranque, la pasarela crea una clave maestra, secret.key, en su carpeta de datos. Protege los secretos de los teléfonos vinculados, los secretos de webhooks y su clave de licencia guardada en la base de datos, e identifica su máquina ante nuestro servidor de licencias (solo se envía una huella derivada de ella, nunca la clave).

Perderla obliga a vincular de nuevo todos los teléfonos y a volver a introducir la clave de licencia. Vive junto a la base de datos, no dentro: una exportación de la base de datos sola no la contiene, mientras que el archivo de sms-gateway backup, que copia toda la carpeta de datos, sí.

Qué contiene la carpeta de datos

El contenedor está blindado: no puede escribir en ningún sitio salvo en esta carpeta y en un espacio temporal usado para las exportaciones de la base de datos. Si sustituye el docker-compose.yml proporcionado por su propia configuración, conserve la línea hostname: sms-gateway (sin ella, cada recreación del contenedor parece una mudanza para nuestro servidor de licencias) y el montaje de /tmp (sin él, la exportación de la base de datos falla).

Copia de seguridad

Toda la instalación vive en la carpeta de datos. La copia más sencilla es:

sudo sms-gateway backup

Ejecutada desde la carpeta donde quiere el archivo, detiene la pasarela los pocos segundos de la copia (los teléfonos guardan sus mensajes mientras tanto), escribe sms-gateway-backup-<fecha>.tar.gz en la carpeta actual, la vuelve a arrancar y espera a que responda. Ese archivo contiene la clave maestra junto con la base de datos: guárdelo como el documento más sensible de la instalación, y no en la misma máquina.

La pasarela también hace copias de seguridad automáticas, sin interrumpir los envíos: cada día a las 03:00 en la zona horaria de la plataforma por defecto, siete copias conservadas, en la carpeta de datos. Cambie la hora, la frecuencia y el número de copias, o desactívela, en Ajustes > Copia de seguridad y exportación, que también lista y restaura las copias y exporta sus datos en CSV o JSON. Estas copias se quedan en la máquina: descargue una, o copie un archivo de sms-gateway backup, para guardar una copia en otro lugar.

Todo se detalla en Copia de seguridad y restauración.

Las guías de alojamiento

Esta página cubre la instalación en sí. Lo específico de cada tipo de máquina tiene su propia guía:

Siguiente