Asterisk Docker Images

Production-ready Docker images for Asterisk PBX with advanced DRY template system, supporting 24 versions from 1.2.40 to 23.2.2 plus git development builds.

Quick Start

# Use pre-built images from Docker Hub
docker pull andrius/asterisk:latest
docker run --rm -p 5060:5060/udp andrius/asterisk:latest

# Check Asterisk version
docker run --rm andrius/asterisk:latest asterisk -V

# Use specific version for production
docker run --rm -p 5060:5060/udp andrius/asterisk:22.5.2_debian-trixie

# Or build latest stable version locally and run locally built container
./scripts/build-asterisk.sh 22.5.2
docker run --rm -p 5060:5060/udp 22.5.2_debian-trixie

Complete examples available in examples/ directory. Legacy code preserved in legacy branch.

📢 Stay Updated

Get notified about new Asterisk releases and Docker image updates:

Automated Announcements

Telegram: Join @asterisk_docker - Instant release notifications
Mastodon: @andrius_kai@mastodon.social - Federated updates

Follow for Updates

X/Twitter: @andrius_kai - Release announcements and project news
Threads: @andrius_kai - Updates and discussions

Container Registries

🐳 Docker Hub: andrius/asterisk - Primary registry
📦 GitHub Container Registry: ghcr.io/andrius/asterisk - Alternative registry

New releases are automatically announced on Telegram and Mastodon when builds complete successfully.

Supported Versions

All supported Asterisk versions with automatic variant detection. Generated build artifacts are placed in asterisk/VERSION-DIST/ directories (not tracked in git).

| Version | Tags | Distribution | Architectures | | ------- | ---- | ------------ | ------------- | | git | testing,dev | Trixie | amd64, arm64 | | 23.2.2 | 23 | Trixie | amd64, arm64 | | 22.8.2 | latest,stable,22 | Trixie | amd64, arm64 | | 22.8-cert1 | - | Trixie | amd64, arm64 | | 21.12.1 | 21 | Trixie | amd64, arm64 | | 20.18.2 | 20 | Trixie | amd64, arm64 | | 20.7-cert9 | 20-cert | Trixie | amd64, arm64 | | 19.8.1 | 19 | Bookworm | amd64 | | 18.26.4 | 18 | Trixie | amd64 | | 17.9.4 | 17 | Bookworm | amd64 | | 16.30.1 | 16 | Bookworm | amd64 | | 16.8-cert14 | 16-cert | Buster | amd64 | | 15.7.4 | 15 | Buster | amd64 | | 14.7.8 | 14 | Buster | amd64 | | 13.38.3 | 13 | Buster | amd64 | | 13.21-cert6 | 13-cert | Buster | amd64 | | 12.8.2 | 12 | Jessie | amd64 | | 11.25.3 | 11 | Jessie | amd64 | | 11.6-cert18 | 11-cert | Jessie | amd64 | | 10.12.4 | 10 | Jessie | amd64 | | 1.8.32.3 | 1.8 | Jessie | amd64 | | 1.6.2.24 | 1.6 | Jessie | amd64 | | 1.4.44 | 1.4 | Jessie | amd64 | | 1.2.40 | 1.2 | Stretch | amd64 |

Additional Tags

The build system supports semantic Docker tags for easier version management. These tags are defined in the additional_tags property of asterisk/supported-asterisk-builds.yml and automatically applied during builds.

Docker Tags Format

This project uses a dual-tagging system: version-specific tags in the format {version}_{os}-{distribution} (e.g., 22.5.2_debian-trixie) for precise deployment, and semantic tags (e.g., latest, stable, 22, 23-rc, 20-cert) for convenient version management.

Primary tags include the full OS and distribution context, while additional semantic tags are defined per version in the build matrix using the additional_tags property. Multi-architecture builds create unified manifests under the same tag names, automatically selecting the correct architecture.

For development, use semantic tags like asterisk:latest or asterisk:stable, and for production a specific tag like asterisk:22.5.2_debian-trixie that guarantee exact version and environment reproducibility.

Current Tag Meanings

latest - Points to the most current stable release (currently 22.5.2)
stable - Alias for the latest stable production version
22 - Major version tag for the Asterisk 22.x series
23-rc - Release candidate tag for Asterisk 23.x pre-releases
testing / git-latest / development - Latest git HEAD from Asterisk repository
20-cert - Certified release tag for Asterisk 20.x certified builds

Usage Examples

# Use semantic tags for consistent deployments
docker run --rm -p 5060:5060/udp asterisk:latest

# Target specific release types
docker run --rm asterisk:stable asterisk -V
docker run --rm asterisk:23-rc asterisk -V
docker run --rm asterisk:20-cert asterisk -V

# Major version targeting
docker run --rm asterisk:22 asterisk -V

Configuration

Additional tags are configured per version in the build matrix:

# In asterisk/supported-asterisk-builds.yml
latest_builds:
  - version: "22.5.2"
    additional_tags: "latest,stable,22"
    os_matrix:
      - os: "debian"
        distribution: "trixie"
        architectures: ["amd64", "arm64"]

When building, both version-specific tags (22.5.2_debian-trixie) and semantic tags (latest, stable, 22) are created for the same image.

Key Features

DRY Template System
Automatic Variant Detection: Smart selection based on Asterisk version patterns
Version-Specific Module Selection: Automatic enforcement of chan_sip removal (v21+) and chan_websocket inclusion (v23+)
Multi-Stage Builds: Optimized images (unpacked image size is about 232MB)
Daily Release Discovery: Automated detection and configuration of new Asterisk releases
Comprehensive Support: All Asterisk versions from 1.2.x through 23.x with appropriate OS distributions
Modern Features: PJSIP, WebRTC, ARI, WebSocket transport for compatible versions
Opus Codec Support: Digium binary Opus codec automatically included for Asterisk 20+ on x86_64 (arm64 supports Opus passthrough)

Architecture

DRY Template System

The build system uses template inheritance to eliminate duplication:

Base Templates: Common packages and Asterisk configuration (37 build + 21 runtime packages)
Distribution Layer: OS-specific package versions (libicu76 for Trixie, libicu72 for Bookworm)
Variant Layer: Version-specific features (modern, asterisk10, legacy-addons)

templates/
├── base/                          # Common packages & configuration
│   ├── asterisk-base.yml.template
│   └── common-packages.yml
├── distributions/                 # OS-specific package versions
│   ├── debian-trixie.yml          # libicu76, libpqxx-7.10
│   ├── debian-bookworm.yml        # libicu72, libpqxx-6.4
│   ├── debian-buster.yml          # libicu63, libpqxx-6.2
│   ├── debian-jessie.yml          # libicu52, libpqxx-4.0
│   └── debian-stretch.yml         # libicu57, libpqxx-4.0
├── variants/                      # Version-specific templates
│   ├── modern.yml.template        # Asterisk 12+ with PJSIP
│   ├── asterisk10.yml.template    # Asterisk 1.8-11.x transitional
│   └── legacy-addons.yml.template # Asterisk 1.2-1.6 with addons
├── dockerfile/                    # Jinja2 Dockerfile generation
└── partials/                      # Build scripts & health checks

Automatic Variant Detection

| Version Range | Variant | Features | | ------------- | --------------- | --------------------------------- | | 1.2.x - 1.6.x | legacy-addons | Separate addons, chan_sip only | | 1.8.x - 11.x | asterisk10 | Pre-PJSIP, chan_sip, transitional | | 12.x+ | modern | PJSIP, WebRTC, ARI, full features |

Version-Specific Requirements

The build system automatically enforces version-specific module requirements during configuration generation (see lib/template_generator.py:224 - _apply_version_overrides() method):

Asterisk 21+ (PJSIP-only requirement):

Automatically adds chan_sip to the exclude list
As per official deprecation, chan_sip was removed in Asterisk 21
Only chan_pjsip is available for SIP communications
Example: asterisk/21.10.2-trixie/build.sh:88 contains menuselect --disable chan_sip

Asterisk 23+ and git (WebSocket requirement):

Automatically adds chan_websocket to the channels list
Sets features.websockets = true in configuration
Includes full WebSocket stack: chan_websocket, res_http_websocket, res_pjsip_transport_websocket
Example: asterisk/23.0.0-rc2-trixie/build.sh:73 contains menuselect --enable chan_websocket

Asterisk 20+ (Opus codec):

Automatically downloads and installs Digium binary Opus codec at build time
Provides codec_opus.so (transcoding) and format_ogg_opus.so (OGG Opus file support)
x86_64/amd64 only — Digium does not provide arm64 binaries
arm64 images include res_format_attr_opus.so for Opus passthrough (no transcoding)
Version capped at Asterisk 23 codec URL (latest available from Digium)

These overrides are applied automatically during ANY config generation:

./scripts/regenerate-all-configs.sh - applies to all 24 versions
./scripts/build-asterisk.sh VERSION --force-config - applies to specific version
Configuration happens at template merge time (before Dockerfile generation)

Implementation Details:

Only applies to modern versions (Asterisk 12+)
Git builds treated as latest (version 99 for comparison)
Integrates seamlessly with DRY template system
Preserves user customizations in templates while enforcing mandatory requirements

Project Structure

.
├── asterisk/                       # Build artifacts (auto-generated)
├── configs/generated/              # Gen

Asterisk

Install / Use

README