Primeros pasos#
Esta guía lleva un Angie recién instalado desde la página de bienvenida del paquete hasta un servidor que aloja archivos y reenvía solicitudes a una aplicación, sirve unos y otras por HTTPS con certificados que obtiene por sí mismo e informa de sus propias estadísticas. Si ya usa nginx, migre su configuración en lugar de reconstruirla a mano.
Cada paso amplía el archivo que deja el anterior, así que recórralos en orden. Solo el paso de HTTPS es opcional: es el único que necesita un nombre de dominio público, y nada de lo que sigue depende de él.
Necesita Angie instalado desde un paquete en un Linux basado en systemd y una cuenta que pueda usar sudo. En Alpine y FreeBSD, la página de instalación ofrece los comandos service que se usan en lugar de systemctl.
Módulos relacionados
Módulo HTTP: root sirve archivos, status_zone mantiene contadores.
Módulo HTTP Proxy: proxy_pass reenvía solicitudes a la aplicación.
Módulo HTTP ACME: obtiene y renueva el certificado HTTPS.
Módulo API: sirve las estadísticas de
/status/.Módulo HTTP SSL: ssl_certificate toma una variable de ACME.
Comprobación de la instalación#
Confirme la versión instalada. El paquete instala el ejecutable en
/usr/sbin, que en Debian no está en el PATH de un usuario
normal, así que ejecútelo con sudo:
$ sudo angie -v
Angie version: Angie/1.12.4
Inicie el servicio y solicite la página predeterminada:
$ sudo systemctl start angie
$ curl -I localhost
HTTP/1.1 200 OK
Server: Angie/1.12.4
...
La respuesta proviene del servidor de bienvenida que trae el paquete; el siguiente paso muestra dónde está definido.
Los cambios de configuración se aplican con una recarga, no con un reinicio: el proceso maestro vuelve a leer la configuración e inicia nuevos procesos de trabajo, mientras que los antiguos terminan las solicitudes que están atendiendo antes de salir. Para el conjunto completo de comandos de inicio, detención, recarga y rotación de registros, las señales que hay detrás y los parámetros de línea de comandos, consulte Control en tiempo de ejecución.
Estructura de la configuración#
El archivo de configuración principal es angie.conf; su ubicación
está compilada en el binario:
$ sudo angie -V 2>&1 | tr ' ' '\n' | grep conf-path
--conf-path=/etc/angie/angie.conf
El archivo se organiza en contextos: bloques que agrupan las directivas que corresponden a un tipo de tráfico:
events — procesamiento general de conexiones
http — tráfico HTTP
mail — tráfico de correo
stream — tráfico TCP y UDP
Los archivos bajo /etc/angie/http.d/ se incluyen dentro de
http, así que contienen bloques server y directivas de nivel
http. Un bloque server describe un servidor virtual, y un bloque
location dentro de él describe cómo manejar un conjunto de URI de
solicitud.
La página de bienvenida proviene de /etc/angie/http.d/default.conf,
el único servidor que define el paquete. Esta guía reemplaza ese archivo y
deja angie.conf tal como se instaló.
La herencia entre contextos, las reglas de sintaxis y las unidades de tamaño y tiempo que usan los parámetros de las directivas se tratan en Archivos de configuración.
Servicio de archivos estáticos#
Empiece con archivos en disco. Cree dos directorios con un archivo cada uno; el contenido nombra el directorio, así que una respuesta muestra de dónde vino el archivo:
$ sudo mkdir -p /data/www /data/images
$ echo 'Hello from /data/www' | sudo tee /data/www/index.html
Hello from /data/www
$ echo 'Hello from /data/images' | sudo tee /data/images/example.png
Hello from /data/images
El segundo archivo solo hace las veces de una imagen; un PNG real se comporta igual.
Reemplace el contenido de /etc/angie/http.d/default.conf por:
server {
listen 80;
location / {
root /data/www;
}
location /images/ {
root /data;
}
}
Pruebe la configuración y recargue:
$ sudo angie -t && sudo systemctl reload angie
Ambos archivos ahora son accesibles, y uno que falte da un 404:
$ curl localhost/index.html
Hello from /data/www
$ curl localhost/images/example.png
Hello from /data/images
$ curl -o /dev/null -w '%{http_code}\n' localhost/images/missing.png
404
Ambas son ubicaciones de prefijo: un URI de solicitud coincide
cuando empieza con la cadena dada y gana el prefijo coincidente más largo.
/index.html coincidió con location /, el prefijo más corto
posible, que captura todo lo que las demás ubicaciones no cubren.
La directiva root no nombra el directorio desde el que servir —
nombra el directorio al que se añade el URI de solicitud completo, por lo que
location /images/ necesita root /data, no
/data/images: el URI /images/example.png añadido a
/data da /data/images/example.png.
Nota
Cuando una solicitud no hace lo que espera, la respuesta está casi siempre
en los registros de acceso y de errores, que de forma predeterminada se
escriben en /var/log/angie/.
Cómo se compara una solicitud con los servidores virtuales y las ubicaciones, incluidas las ubicaciones con expresiones regulares y el orden en que se comprueban, se describe en Conexiones, sesiones, solicitudes, registros. Las directivas que asignan URI a archivos — root, alias, index, try_files — están en la referencia de módulos HTTP.
Proxy a una aplicación#
La segunda tarea habitual de Angie es situarse delante de una aplicación y reenviarle las solicitudes. Aquí el propio Angie hace de aplicación: un segundo servidor, escuchando solo en el puerto de loopback 8080, sirve un directorio propio. Reemplácelo por la aplicación real más adelante.
$ sudo mkdir -p /data/app
$ echo 'Hello from the application' | sudo tee /data/app/index.html
Hello from the application
Ponga ese servidor en un archivo propio:
server {
listen 127.0.0.1:8080;
root /data/app;
}
En default.conf, reemplace root en location / por
proxy_pass, y haga coincidir las imágenes por extensión en lugar de
por prefijo:
server {
listen 80;
location / {
proxy_pass http://127.0.0.1:8080;
}
location ~ \.(gif|jpg|png)$ {
root /data;
}
}
Pruebe la configuración y recargue:
$ sudo angie -t && sudo systemctl reload angie
Las solicitudes ahora llegan a la aplicación, excepto las de imágenes:
$ curl localhost/
Hello from the application
$ curl localhost/images/example.png
Hello from /data/images
La segunda ubicación empieza con ~, lo que la convierte en una
ubicación de expresión regular en lugar de prefijo. Angie comprueba primero
las ubicaciones de prefijo y recuerda la coincidencia más larga, luego prueba
las expresiones regulares en el orden en que aparecen; si una de ellas
coincide, gana. Eso es lo que permite que un único patrón corto separe las
solicitudes de imágenes de la ubicación general que hay encima, de modo que
Angie las atiende desde disco sin pasar por la aplicación.
proxy_pass cuenta con un amplio conjunto de directivas complementarias — para cabeceras de solicitud, tiempos de espera, almacenamiento en búfer y caché — documentadas en el módulo Proxy. Para repartir las solicitudes entre varios servidores de aplicación en lugar de uno solo, defina un bloque upstream y haga proxy hacia él por su nombre.
HTTPS automático#
Este paso necesita un nombre de dominio que resuelva a la dirección pública de este host, y el puerto 80 accesible desde internet: la autoridad de certificación valida la propiedad obteniendo un archivo por HTTP. Sin ambos, pase al siguiente paso; nada de lo que sigue depende de este.
Angie obtiene y renueva los certificados por sí mismo, mediante
ACME, sin cliente externo
ni tarea cron de renovación. Añada un acme_client encima del bloque
server (una directiva de nivel http) y haga referencia al cliente desde el
servidor, poniendo sus propios nombres en lugar de example.com y
www.example.com:
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80;
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
location / {
proxy_pass http://127.0.0.1:8080;
}
location ~ \.(gif|jpg|png)$ {
root /data;
}
}
Angie resuelve el nombre de la autoridad de certificación a través de
/etc/resolv.conf de forma predeterminada, así que no hace falta
ninguna directiva resolver. En un host sin conectividad IPv6, añada
resolver conf ipv6=off; encima del bloque server para que deje de
pedir registros AAAA que no puede usar.
El certificado se emite para los nombres de dominio listados en
server_name en todos los servidores que hacen referencia al mismo
cliente; las entradas que no son nombres de dominio, como las expresiones
regulares y _, se omiten con una advertencia en el registro de
errores. El certificado llega a ssl_certificate a través de una
variable en lugar de una ruta de archivo, así que no hay nada que instalar ni
que rotar a mano.
Pruebe la configuración y recargue:
$ sudo angie -t && sudo systemctl reload angie
Angie empieza a escuchar en el puerto 443 en cuanto se aplica la configuración, pero no puede completar un handshake TLS hasta que llega el certificado, así que mientras tanto las solicitudes a ese puerto fallan durante el handshake. La emisión no es instantánea; depende de la autoridad de certificación. Una vez que el certificado esté en su lugar:
$ curl -I https://www.example.com/
HTTP/1.1 200 OK
...
Si nunca llega, consulte el estado del cliente en
/status/http/acme_clients/example en la API del siguiente paso y los
mensajes de ACME en el registro de errores; si eso no es
suficiente, active el registro de depuración.
Nota
Mientras todavía esté ajustando la configuración, apunte acme_client al directorio de pruebas (staging) de la autoridad de certificación — para Let's Encrypt, https://acme-staging-v02.api.letsencrypt.org/directory — para que los intentos fallidos no cuenten contra los límites de frecuencia de producción. Cambie a la URL de producción en cuanto aparezca un certificado.
La validación por DNS y TLS-ALPN, los certificados comodín, la vinculación de cuenta externa y el cambio desde Certbot se tratan en Configuración de ACME; las directivas y variables están en el módulo ACME.
Estadísticas del servidor#
Angie informa de su propio estado a través de una API REST integrada. Añada una ubicación para ella, restringida a solicitudes locales, y asigne al servidor una status_zone para que se recopilen sus contadores:
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80;
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
status_zone site;
location / {
proxy_pass http://127.0.0.1:8080;
}
location ~ \.(gif|jpg|png)$ {
root /data;
}
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
}
Si se saltó el paso de HTTPS, añada solo las líneas resaltadas. El
default.conf del paquete incluía esta misma ubicación
/status/; desapareció cuando reemplazó ese archivo, así que vuelva a
ponerla.
Pruebe la configuración y recargue; la API entonces responde con JSON:
$ sudo angie -t && sudo systemctl reload angie
$ curl localhost/status/angie/
{
"version": "1.12.4",
"build_time": "2026-10-16T06:58:49Z",
"address": "192.0.2.10",
"generation": 1,
"load_time": "2026-10-16T10:23:06.011Z"
}
/status/connections informa de las conexiones aceptadas, descartadas,
activas e inactivas. Los contadores por servidor y por ubicación son
opcionales: un server aparece bajo /status/http/server_zones/
y una location bajo /status/http/location_zones/, cada uno
solo una vez que lleva su propia status_zone. El servidor anterior
lleva una, sus ubicaciones no:
$ curl localhost/status/http/server_zones/site
{
"ssl": {
"handshaked": 3,
"reuses": 0,
"timedout": 0,
"failed": 0
},
"requests": {
"total": 5,
"processing": 1,
"discarded": 0
},
"responses": {
"200": 3,
"404": 1
},
"data": {
"received": 412,
"sent": 1418
}
}
El objeto ssl está presente porque el servidor escucha con
ssl; sin él, la zona empieza en requests.
El árbol completo de endpoints — grupos de servidores, cachés, resolutores DNS, zonas de memoria compartida, clientes ACME y, en Angie PRO, la configuración dinámica — está documentado en el módulo API. Si prefiere verlo en lugar de consultarlo con curl, el panel web Console Light muestra los mismos datos.
Próximos pasos#
Guías paso a paso para tareas concretas: SSL, OIDC, clústeres, paneles de monitorización y métricas personalizadas. | |
La referencia de todas las directivas y variables, agrupadas por módulo. | |
Enlaces cortos que llevan directamente a la documentación de una directiva. | |
Si también usa nginx en otro lugar, traslade esas configuraciones. |
Contenido