Installation#

Supported distributions#

Alpine#

Version

Platform

3.17

x86_64, aarch64

3.16

x86_64, aarch64

3.15

x86_64, aarch64

3.14

x86_64, aarch64

CentOS#

Version

Platform

9

x86_64, aarch64

8

x86_64, aarch64

Debian#

Version

Platform

11 “Bullseye”

x86_64, aarch64

10 “Buster”

x86_64, aarch64

Oracle#

Version

Platform

9

x86_64, aarch64

8

x86_64, aarch64

RED OS#

Version

Platform

7.3 “MUROM“

x86_64

Rocky#

Version

Platform

9

x86_64, aarch64

8

x86_64, aarch64

Ubuntu#

Version

Platform

22.04 “Jammy Jellyfish”

x86_64, aarch64

20.04 “Focal Fossa“

x86_64, aarch64

Installation on server#

Before you install Angie for the first time on a new machine, you need to set up the Angie packages repository. Afterward, you can install and update Angie from the repository using package manager.

Alpine#

  1. Install the prerequisites:

$ sudo apk add curl ca-certificates

  1. Import an official Angie signing key so apk could verify the packages authenticity. Fetch the key:

$ sudo curl -o /etc/apk/keys/angie-signing.rsa \
       https://angie.software/keys/angie-signing.rsa

  1. To set up the apk repository for Angie packages, run the following command:

$ echo "https://download.angie.software/angie/alpine/v$(egrep -o \
     '[0-9]+\.[0-9]+' /etc/alpine-release)/main" \
     | sudo tee -a /etc/apk/repositories >/dev/null

  1. To install Angie, run the following commands:

$ sudo apk update
$ sudo apk add angie
$ sudo service angie start

CentOS /Oracle / RED OS / Rocky#

  1. To set up the yum repository, create the file named /etc/yum.repos.d/nginx.repo with the following content:

[angie]
name=Angie repo
baseurl=https://download.angie.software/angie/centos/$releasever/
gpgcheck=1
enabled=1
gpgkey=https://angie.software/keys/angie-signing.gpg

  1. To install Angie, run the following command:

$ sudo yum install angie

Debian / Ubuntu#

  1. Install the prerequisites:

$ sudo apt install ca-certificates curl lsb-release

  1. Import an official Angie signing key so apt could verify the packages authenticity. Fetch the key:

$ sudo curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \
            https://angie.software/keys/angie-signing.gpg

  1. To set up the apt repository for Angie packages, run the following command:

$ echo "deb https://download.angie.software/angie/debian/ `lsb_release -cs` main" \
     | sudo tee /etc/apt/sources.list.d/angie.list >/dev/null

  1. To install Angie, run the following commands:

$ sudo apt update
$ sudo apt install angie

Dynamic Modules#

Angie allows extending basic functionality by loading modules dynamically. Modules have to be compiled to be used as dynamic against corresponding Angie release.

Angie repository provides following dynamic module packages:

angie-module-auth-spnego
angie-module-brotli
angie-module-dav-ext
angie-module-geoip2
angie-module-headers-more
angie-module-image-filter
angie-module-ndk
angie-module-njs
angie-module-perl
angie-module-rtmp
angie-module-set-misc
angie-module-xslt

Docker-container#

To deploy Angie instance in a Docker container use one of images available in our registry:

docker.angie.software/angie
docker.angie.software/angie:latest
docker.angie.software/angie:1.1.0
docker.angie.software/angie:1.1.0-debian
docker.angie.software/angie:1.1.0-alpine

Or build your own one using below Dockerfile of your choice

debian:latest#
FROM debian:latest

LABEL maintainer="Release Engineering Team <devops@tech.wbsrv.ru>"

ARG DEBIAN_FRONTEND=noninteractive

RUN set -x \
     && apt-get update \
     && apt-get install --no-install-recommends --no-install-suggests -y \
          ca-certificates lsb-release curl \
     && curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \
          https://angie.software/keys/angie-signing.gpg \
     && echo "deb https://download.angie.software/angie/debian/ `lsb_release \
           -cs` main" > /etc/apt/sources.list.d/angie.list \
     && apt-get update \
     && apt-get install --no-install-recommends --no-install-suggests -y \
          angie angie-module-geoip2 angie-module-njs \
     && apt-get remove --auto-remove --purge -y lsb-release \
     && rm -Rf /var/lib/apt/lists \
          /etc/apt/sources.list.d/angie.list \
          /etc/apt/trusted.gpg.d/angie-signing.gpg \
     && ln -sf /dev/stdout /var/log/angie/access.log \
     && ln -sf /dev/stderr /var/log/angie/error.log

EXPOSE 80

CMD ["angie", "-g", "daemon off;"]
alpine:latest#
FROM alpine:latest

LABEL maintainer="Release Engineering Team <devops@tech.wbsrv.ru>"

RUN set -x \
     && apk add --no-cache ca-certificates curl \
     && curl -o /etc/apk/keys/angie-signing.rsa https://angie.software/keys/angie-signing.rsa \
     && echo "https://download.angie.software/angie/alpine/v$(egrep -o \
          '[0-9]+\.[0-9]+' /etc/alpine-release)/main" >> /etc/apk/repositories \
     && apk add --no-cache angie angie-module-geoip2 angie-module-njs \
     && rm /etc/apk/keys/angie-signing.rsa \
     && ln -sf /dev/stdout /var/log/angie/access.log \
     && ln -sf /dev/stderr /var/log/angie/error.log

EXPOSE 80

CMD ["angie", "-g", "daemon off;"]

Run docker build to build your image:

$ docker build -t myangie .

-t

image name

.

inside current directory with Dockerfile

Check new image running docker images:

$ docker images

   REPOSITORY              TAG             IMAGE ID       CREATED          SIZE
   myangie                 latest          5dc27ac5980f   13 seconds ago   15.5MB

Run the container with docker run:

$ docker run --rm --name myangie -p 8080:80 -d myangie

To use pre-built Docker image:

$ docker run --rm --name myangie -p 8080:80 -d docker.angie.software/angie

--rm

docker run option, automatically remove the container when it exits

--name

assign a name to the container

-p, --publish

publish a container’s port 80 to the 8080 on host

-d, --detach

run container in background

Check Angie running with curl for example:

$ curl -I localhost:8080

   HTTP/1.1 200 OK
   Server: Angie/1.1.0

Stop and remove the container ran with –rm:

$ docker stop myangie

To mount site’s static files and Angie’s configuration file from host filesystem into container, use docker run below as an example:

$ docker run --rm --name myangie -v /var/www:/usr/share/angie/html:ro \
             -v $(pwd)/angie.conf:/etc/angie/angie.conf:ro -p 8080:80 -d myangie

-v, --volume

bind mount a volume

:ro

prohibits writes to mounted files inside the container

Building from sources#

It is recommended to install Angie from packages. If, for any reason, you need an own build, archived sources are available for download:

  1. .tar.gz from site

$ curl -O https://download.angie.software/files/angie-1.1.0.tar.gz

Sources are available on GitHub as well

  1. Unarchive the sources:

$ tar xzf angie-1.1.0.tar.gz

  1. Build to be run inside sources directory

$ cd angie-1.1.0

  1. The build is configured using the configure script. It defines various aspects of the system, including the methods Angie is allowed to use for connection processing. At the end it creates a Makefile.

The configure script supports the linked parameters.

$ ./configure
$ make
$ make install

Please note

Warning

Angie sets up differently than Nginx, in particular:

  1. Paths to binary, configuration file, log files, dynamic modules and temporary files

prefix=/etc/angie
conf-path=/etc/angie/angie.conf
error-log-path=/var/log/angie/error.log
http-log-path=/var/log/angie/access.log
lock-path=/var/run/angie.lock
modules-path=/usr/lib/angie/modules
pid-path=/var/run/angie.pid
sbin-path=/usr/sbin/angie
http-client-body-temp-path=/var/cache/angie/client_temp
http-fastcgi-temp-path=/var/cache/angie/fastcgi_temp
http-proxy-temp-path=/var/cache/angie/proxy_temp
http-scgi-temp-path=/var/cache/angie/scgi_temp
http-uwsgi-temp-path=/var/cache/angie/uwsgi_temp

.. pid-path=/run/angie.pid
.. lock-path=/run/angie.lock

  1. Built-in modules

http_addition_module
http_auth_request_module
http_dav_module
http_flv_module
http_gunzip_module
http_gzip_static_module
http_mp4_module
http_random_index_module
http_realip_module
http_secure_link_module
http_slice_module
http_ssl_module
http_stub_status_module
http_sub_module
http_v2_module
mail
mail_ssl_module
stream
stream_realip_module
stream_ssl_module
stream_ssl_preread_module

  1. Dynamic module packages available in the repository

angie-module-auth-spnego
angie-module-brotli
angie-module-dav-ext
angie-module-geoip2
angie-module-headers-more
angie-module-image-filter
angie-module-ndk
angie-module-njs
angie-module-perl
angie-module-rtmp
angie-module-set-misc
angie-module-xslt

The configure script supports the following parameters:

--help prints a help message.

--prefix=path defines a directory that will keep server files. This same directory will also be used for all relative paths set by configure (except for paths to libraries sources) and in the angie.conf configuration file.
It is set to the /usr/local/angie directory by default.

--sbin-path=path sets the name of an Angie executable file. This name is used only during installation.
By default the file is named prefix/sbin/angie.

--modules-path=path defines a directory where Angie dynamic modules will be installed.
By default the prefix/modules directory is used.

--conf-path=path sets the name of an angie.conf configuration file. If needs be, Angie can always be started with a different configuration file, by specifying it in the command-line parameter -c file.
By default the file is named prefix/conf/angie.conf.

--error-log-path=path sets the name of the primary error, warnings, and diagnostic file. After installation, the file name can always be changed in the angie.conf configuration file using the error_log directive.
By default the file is named prefix/logs/error.log.

--pid-path=path sets the name of an angie.pid file that will store the process ID of the main process. After installation, the file name can always be changed in the angie.conf configuration file using the pid directive.
By default the file is named prefix/logs/angie.pid.

--lock-path=path sets a prefix for the names of lock files. After installation, the value can always be changed in the angie.conf configuration file using the lock_file directive.
By default the value is prefix/logs/angie.lock.

--user=name sets the name of an unprivileged user whose credentials will be used by worker processes. After installation, the name can always be changed in the angie.conf configuration file using the user directive.
The default user name is nobody.

--group=name sets the name of a group whose credentials will be used by worker processes. After installation, the name can always be changed in the angie.conf configuration file using the user directive.
By default, a group name is set to the name of an unprivileged user.

--build=name sets an optional Angie build name.

--builddir=path sets a build directory.

--with-select_module / --without-select_module enables or disables building a module that allows the server to work with the select() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.

--with-poll_module / --without-poll_module enables or disables building a module that allows the server to work with the poll() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.

--with-threads enables the use of thread pools.

--with-file-aio enables the use of asynchronous file I/O (AIO) on FreeBSD and Linux.

--with-http_ssl_module enables building a module that adds the HTTPS protocol support to an HTTP server.
This module is not built by default. The OpenSSL library is required to build and run this module.

--with-http_v2_module enables building a module that provides support for HTTP/2.
This module is not built by default.

--with-http_realip_module enables building the http_realip module that changes the client address to the address sent in the specified header field.
This module is not built by default.

--with-http_addition_module enables building the http_addition module that adds text before and after a response.
This module is not built by default.

--with-http_xslt_module / --with-http_xslt_module=dynamic enables building the http_xslt module that transforms XML responses using one or more XSLT stylesheets.
This module is not built by default. The libxml2 and libxslt libraries are required to build and run this module.

--with-http_image_filter_module / --with-http_image_filter_module=dynamic enables building the http_image_filter module that transforms images in JPEG, GIF, PNG, and WebP formats.
This module is not built by default.

--with-http_geoip_module / --with-http_geoip_module=dynamic enables building the http_geoip module that creates variables depending on the client IP address and the precompiled MaxMind databases.
This module is not built by default.

--with-http_sub_module enables building the http_sub module that modifies a response by replacing one specified string by another.
This module is not built by default.

--with-http_dav_module enables building the http_dav module that provides file management automation via the WebDAV protocol.
This module is not built by default.

--with-http_flv_module enables building the http_flv module that provides pseudo-streaming server-side support for Flash Video (FLV) files.
This module is not built by default.

--with-http_mp4_module enables building the http_mp4 module that provides pseudo-streaming server-side support for MP4 files.
This module is not built by default.

--with-http_gunzip_module enables building the http_gunzip module that decompresses responses with “Content-Encoding: gzip” for clients that do not support gzip encoding method.
This module is not built by default.

--with-http_gzip_static_module enables building the http_gzip_static module that enables sending precompressed files with the “.gz” filename extension instead of regular files.
This module is not built by default.

--with-http_auth_request_module enables building the http_auth_request module that implements client authorization based on the result of a subrequest.
This module is not built by default.

--with-http_random_index_module enables building the http_random_index module that processes requests ending with the slash character (‘/’) and picks a random file in a directory to serve as an index file.
This module is not built by default.

--with-http_secure_link_module enables building the http_secure_link module.
This module is not built by default.

--with-http_degradation_module enables building the http_degradation.
This module is not built by default.

--with-http_slice_module enables building the http_slice module that splits a request into subrequests, each returning a certain range of response. The module provides more effective caching of big responses.
This module is not built by default.

--with-http_stub_status_module enables building the http_stub_status module that provides access to basic status information.
This module is not built by default.

--without-http_api_module disables building a module API, providing HTTP RESTful interface for accessing in JSON format information about a web server instance.

--without-http_charset_module disables building the http_charset module that adds the specified charset to the “Content-Type” response header field and can additionally convert data from one charset to another.

--without-http_gzip_module disables building a module that compresses responses of an HTTP server. The zlib library is required to build and run this module.

--without-http_ssi_module disables building the http_ssi module that processes SSI (Server Side Includes) commands in responses passing through it.

--without-http_userid_module disables building the http_userid module that sets cookies suitable for client identification.

--without-http_access_module disables building the http_access module that allows limiting access to certain client addresses.

--without-http_auth_basic_module disables building the http_auth_basic module that allows limiting access to resources by validating the user name and password using the “HTTP Basic Authentication” protocol.

--without-http_mirror_module disables building the http_mirror module that implements mirroring of an original request by creating background mirror subrequests.

--without-http_autoindex_module disables building the http_autoindex module that processes requests ending with the slash character (‘/’) and produces a directory listing in case the http_index module cannot find an index file.

--without-http_geo_module disables building the http_geo module that creates variables with values depending on the client IP address.

--without-http_map_module disables building the http_map module that creates variables with values depending on values of other variables.

--without-http_split_clients_module disables building the http_split_clients module that creates variables for A/B testing.

--without-http_referer_module disables building the http_referer module that can block access to a site for requests with invalid values in the “Referer” header field.

--without-http_rewrite_module disables building a module that allows an HTTP server to redirect requests and change URI of requests. The PCRE library is required to build and run this module.

--without-http_proxy_module disables building an HTTP server proxying module.

--without-http_fastcgi_module disables building the http_fastcgi module that passes requests to a FastCGI server.

--without-http_uwsgi_module disables building the http_uwsgi module that passes requests to a uwsgi server.

--without-http_scgi_module disables building the http_scgi module that passes requests to an SCGI server.

--without-http_grpc_module disables building the http_grpc module that passes requests to a gRPC server.

--without-http_memcached_module disables building the http_memcached module that obtains responses from a memcached server.

--without-http_limit_conn_module disables building the http_limit_conn module that limits the number of connections per key, for example, the number of connections from a single IP address.

--without-http_limit_req_module disables building the http_limit_req module that limits the request processing rate per key, for example, the processing rate of requests coming from a single IP address.

--without-http_empty_gif_module disables building a module that emits single-pixel transparent GIF.

--without-http_browser_module disables building the http_browser module that creates variables whose values depend on the value of the “User-Agent” request header field.

--without-http_upstream_hash_module disables building a module that implements the hash load balancing method.

--without-http_upstream_ip_hash_module disables building a module that implements the ip_hash load balancing method.

--without-http_upstream_least_conn_module disables building a module that implements the least_conn load balancing method.

--without-http_upstream_random_module disables building a module that implements the random load balancing method.

--without-http_upstream_keepalive_module disables building a module that provides caching of connections to upstream servers.

--without-http_upstream_zone_module disables building a module that makes it possible to store run-time state of an upstream group in a shared memory zone.

--with-http_perl_module / --with-http_perl_module=dynamic enables building the embedded Perl module.
This module is not built by default.

--with-perl_modules_path=path defines a directory that will keep Perl modules.

--with-perl=path sets the name of the Perl binary.

--http-log-path=path sets the name of the primary request log file of the HTTP server. After installation, the file name can always be changed in the angie.conf configuration file using the access_log directive.
By default the file is named prefix/logs/access.log.

--http-client-body-temp-path=path defines a directory for storing temporary files that hold client request bodies. After installation, the directory can always be changed in the angie.conf configuration file using the client_body_temp_path directive.
By default the directory is named prefix/client_body_temp.

--http-proxy-temp-path=path defines a directory for storing temporary files with data received from proxied servers. After installation, the directory can always be changed in the angie.conf configuration file using the proxy_temp_path directive.
By default the directory is named prefix/proxy_temp.

--http-fastcgi-temp-path=path defines a directory for storing temporary files with data received from FastCGI servers. After installation, the directory can always be changed in the angie.conf configuration file using the fastcgi_temp_path directive.
By default the directory is named prefix/fastcgi_temp.

--http-uwsgi-temp-path=path defines a directory for storing temporary files with data received from uwsgi servers. After installation, the directory can always be changed in the angie.conf configuration file using the uwsgi_temp_path directive.
By default the directory is named prefix/uwsgi_temp.

--http-scgi-temp-path=path defines a directory for storing temporary files with data received from SCGI servers. After installation, the directory can always be changed in the angie.conf configuration file using the scgi_temp_path directive.
By default the directory is named prefix/scgi_temp.

--without-http disables the HTTP server.

--without-http-cache disables HTTP cache.

--with-mail / --with-mail=dynamic enables POP3/IMAP4/SMTP mail proxy server.

--with-mail_ssl_module enables building a module that adds the SSL/TLS protocol support to the mail proxy server.
This module is not built by default. The OpenSSL library is required to build and run this module.

--without-mail_pop3_module disables the POP3 protocol in mail proxy server.

--without-mail_imap_module disables the IMAP protocol in mail proxy server.

--without-mail_smtp_module disables the SMTP protocol in mail proxy server.

--with-stream / --with-stream=dynamic enables building the stream_core module for generic TCP/UDP proxying and load balancing.
This module is not built by default.

--with-stream_ssl_module enables building a module that adds the SSL/TLS protocol support to the stream module.
This module is not built by default. The OpenSSL library is required to build and run this module.

--with-stream_realip_module enables building the stream_realip module that changes the client address to the address sent in the PROXY protocol header.
This module is not built by default.

--with-stream_geoip_module / --with-stream_geoip_module=dynamic enables building the stream_geoip module that creates variables depending on the client IP address and the precompiled MaxMind databases.
This module is not built by default.

--with-stream_ssl_preread_module enables building the stream_ssl_preread module that allows extracting information from the ClientHello message without terminating SSL/TLS.
This module is not built by default.

--without-stream_limit_conn_module disables building the stream_limit_conn module that limits the number of connections per key, for example, the number of connections from a single IP address.

--without-stream_access_module disables building the stream_access module that allows limiting access to certain client addresses.

--without-stream_geo_module disables building the stream_geo module that creates variables with values depending on the client IP address.

--without-stream_map_module disables building the stream_map module that creates variables with values depending on values of other variables.

--without-stream_split_clients_module disables building the stream_split_clients module that creates variables for A/B testing.

--without-stream_return_module disables building the stream_return module that sends some specified value to the client and then closes the connection.

--without-stream_set_module disables building the stream_set module that sets a value for a variable.

--without-stream_upstream_hash_module disables building a module that implements the hash load balancing method.

--without-stream_upstream_least_conn_module disables building a module that implements the least_conn load balancing method.

--without-stream_upstream_random_module disables building a module that implements the random load balancing method.

--without-stream_upstream_zone_module disables building a module that makes it possible to store run-time state of an upstream group in a shared memory zone.

--with-google_perftools_module enables building the google_perftools module that enables profiling of Angie worker processes using Google Performance Tools.
The module is intended for Angie developers and is not built by default.

--with-cpp_test_module enables building the ngx_cpp_test_module.

--add-module=path enables an external module.

--add-dynamic-module=path enables an external dynamic module.

--with-compat enables dynamic modules compatibility.

--with-cc=path sets the name of the C compiler.

--with-cpp=path sets the name of the C preprocessor.

--with-cc-opt=parameters sets additional parameters that will be added to the CFLAGS variable. When using the system PCRE library under FreeBSD, ‑‑with‑cc‑opt=“‑I /usr/local/include“ should be specified. If the number of files supported by select() needs to be increased it can also be specified here such as this: ‑‑with‑cc‑opt=“‑D FD_SETSIZE=2048“.

--with-ld-opt=parameters sets additional parameters that will be used during linking. When using the system PCRE library under FreeBSD, ‑‑with‑ld‑opt=“‑L /usr/local/lib“ should be specified.

--with-cpu-opt=cpu enables building per specified CPU: pentium, pentiumpro, pentium3, pentium4, athlon, opteron, sparc32, sparc64, ppc64.

--without-pcre disables the usage of the PCRE library.

--with-pcre forces the usage of the PCRE library.

--with-pcre=path sets the path to the sources of the PCRE library. The library distribution needs to be downloaded from the PCRE site and extracted. The rest is done by angie’s ./configure and make. The library is required for regular expressions support in the location directive and for the http_rewrite module.

--with-pcre-opt=parameters sets additional build options for PCRE.

--with-pcre-jit builds the PCRE library with “just-in-time compilation” support (the pcre_jit directive).

--without-pcre2 disables use of the PCRE2 library instead of the original PCRE library.

--with-zlib=path sets the path to the sources of the zlib library. The library distribution (version 1.1.3 — 1.2.11) needs to be downloaded from the zlib site and extracted. The rest is done by Angie’s ./configure and make. The library is required for the http_gzip module.

--with-zlib-opt=parameters sets additional build options for zlib.

--with-zlib-asm=cpu enables the use of the zlib assembler sources optimized for one of the specified CPUs: pentium, pentiumpro.

--with-libatomic forces the libatomic_ops library usage.

--with-libatomic=path sets the path to the libatomic_ops library sources.

--with-openssl=path sets the path to the OpenSSL library sources.

--with-openssl-opt=parameters sets additional build options for OpenSSL.

--with-debug enables the debugging log.

Example of parameters usage:

./configure \
     --sbin-path=/usr/sbin/angie/ \
     --conf-path=/etc/angie/angie.conf \
     --pid-path=/var/run/angie.pid \
     --with-http_ssl_module \
     --with-pcre=../pcre2-10.40 \
     --with-zlib=../zlib-1.2.13

After configuration, Angie is compiled and installed using make.