Exposing Annif to the Internet

Annif exposes its functionality via a REST API and a Web UI in production environments. These interfaces can be configured to accept connections from the public internet or restricted to a private internal network.

Security considerations

Warning

When exposing Annif to the public internet, be aware that Annif on its own only provides a basic REST API and Web UI but does not include any authentication or authorization mechanisms. Due to its scope as a microservice, Annif also lacks built-in protections against server overload, Denial of Service (DoS) attacks, or other forms of malicious traffic.

Important

To mitigate security risks, Annif’s REST API and Web UI should always sit behind a reverse proxy, Web Application Firewall (WAF), or API gateway when exposed publicly. Common solutions include Nginx or Apache (configured as a reverse proxy), as well as managed services like Cloudflare or Fastly. The proxy service must handle:

• authorization and authentication (e.g. with a password or API key)
• rate limiting to prevent resource exhaustion
• request size limits to block oversized payloads
• traffic filtering to block malicious requests and automated bots
• method restrictions to limit access to specific API endpoints and/or the Web UI

By its nature, Annif performs computationally intensive tasks on incoming requests, which can consume significant CPU and memory resources. Uncontrolled traffic volume can lead to resource exhaustion, degrading or crashing the server. Specifically, a single large request or a flood of requests may cause excessive computation times or trigger out-of-memory errors.

We recommend running Annif in an isolated container or environment separate from critical services. This isolation ensures that if Annif becomes overloaded, it does not degrade the performance of other applications on the same host. Additionally, use a process manager or container orchestrator (e.g., systemd, Docker, Kubernetes) configured to automatically restart Annif if it crashes or becomes unresponsive.

Web component stack

Annif is based on Flask, which is a WSGI (Web Server Gateway Interface) application framework well suitable for development and debugging, but in production systems it is recommended to use a WSGI server in front.

Gunicorn is a good choice for the WSGI server. To start Annif behind Gunicorn run e.g.

gunicorn "annif:create_app()" --bind 0.0.0.0:8000 --timeout 600 --worker-class uvicorn.workers.UvicornWorker

This exposes port 8000, sets the timeout to 600 s to allow the Annif models to load in case they are large, and uses Uvicorn workers.

Server platform

The platform to run the above components can be a traditional server, but nowadays a more common approach is to employ containers. Docker image of Annif is available on quay.io/natlibfi/annif repository. The image includes Gunicorn as well as all optional dependencies of Annif (see how to customize the Annif image for example to reduce the size of the image).

Real world example

For a real-world example of Annif deployment, see the Finto AI service by the National Library of Finland, which runs on OpenShift Container Platform. See Finto AI's GitHub repository for the service configuration.

See also: Annif tutorial: production use

---

← Usage with Docker | Running as a WSGI service →