Tengine

intermediate

Alibaba's NGINX fork with additional features and optimizations.

Overview

Tengine is Alibaba's high-performance fork of NGINX, developed to handle the massive traffic demands of Taobao and other Alibaba services. Born from real-world experience serving billions of requests daily, Tengine incorporates enterprise-grade features that are typically only available in NGINX Plus, including dynamic module loading, active health checks, and session persistence. The web server maintains full compatibility with standard NGINX configurations while adding performance optimizations and stability improvements battle-tested in production environments. This Docker deployment leverages Tengine's enhanced capabilities to provide a drop-in replacement for NGINX with superior performance characteristics and advanced load balancing features. The configuration supports both HTTP and HTTPS traffic with customizable server blocks and static content serving, making it ideal for organizations seeking NGINX compatibility with enterprise features. Tengine particularly benefits high-traffic applications, e-commerce platforms, and content delivery scenarios where Alibaba's optimizations for Chinese network conditions and massive scale operations provide measurable performance gains over standard NGINX deployments.

Key Features

Dynamic module loading without server restart or recompilation
Active upstream health checks with configurable failure detection
Session persistence using consistent hashing algorithms
Enhanced SSL/TLS performance with optimized certificate handling
Built-in request rate limiting with sliding window algorithms
Advanced load balancing with least connection and weighted round-robin
Integrated Lua scripting support for custom request processing
Enhanced logging with detailed performance metrics and timing data

Common Use Cases

1High-traffic e-commerce sites requiring session persistence and health checks
2Content delivery networks needing dynamic module loading capabilities
3API gateways requiring advanced load balancing without NGINX Plus licensing
4Chinese market deployments benefiting from Alibaba's network optimizations
5Migration from NGINX Plus to open-source alternative with similar features
6Microservices architectures needing sophisticated upstream management
7Development environments testing enterprise NGINX features without licensing costs

Prerequisites

Docker Engine 20.10+ and Docker Compose 2.0+ installed
Minimum 512MB RAM allocated for container operations
Ports 80 and 443 available on the host system
Basic understanding of NGINX configuration syntax and directives
SSL certificates prepared if enabling HTTPS functionality
Knowledge of upstream server configuration for load balancing scenarios

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  tengine: 
3    image: alibaba/tengine:latest
4    container_name: tengine
5    restart: unless-stopped
6    volumes: 
7      - ./nginx/conf.d:/etc/nginx/conf.d:ro
8      - ./nginx/html:/usr/share/nginx/html:ro
9    ports: 
10      - "80:80"
11      - "443:443"
12    networks: 
13      - tengine-network
14
15networks: 
16  tengine-network: 
17    driver: bridge

.env Template

.env

1# Tengine configuration

Usage Notes

1Docs: https://tengine.taobao.org/documentation.html
2NGINX-compatible - migrate configs directly
3Dynamic module loading without recompile
4Active upstream health checks (NGINX Plus feature, free here)
5Session persistence and consistent hashing built-in
6Alibaba's fork handling massive traffic at scale

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  tengine:
5    image: alibaba/tengine:latest
6    container_name: tengine
7    restart: unless-stopped
8    volumes:
9      - ./nginx/conf.d:/etc/nginx/conf.d:ro
10      - ./nginx/html:/usr/share/nginx/html:ro
11    ports:
12      - "80:80"
13      - "443:443"
14    networks:
15      - tengine-network
16
17networks:
18  tengine-network:
19    driver: bridge
20EOF
21
22# 2. Create the .env file
23cat > .env << 'EOF'
24# Tengine configuration
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/tengine/run | bash

Troubleshooting

tengine: [emerg] bind() to 0.0.0.0:80 failed: Restart Docker service and ensure no other web servers are running on ports 80/443
Dynamic module loading fails: Verify module compatibility with Tengine version and check /etc/nginx/modules directory permissions
Health check not working: Confirm upstream servers are accessible and health_check directive syntax matches Tengine documentation
Session persistence not maintaining sessions: Review consistent_hash configuration and verify upstream server stability
Configuration test fails after migration: Check for NGINX-specific directives not supported in Tengine and update syntax accordingly
SSL handshake errors: Verify certificate chain completeness and check ssl_protocols configuration for client compatibility

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

tengine

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download