Asterisk Docker

This project packages Asterisk, a popular open source framework for building communications applications, with a few extra tools (curl, sox, mpg123 etc.) in a convenient stand-alone docker image. New LTS releases are detected daily and built automatically.

For Asterisk version info, see https://www.asterisk.org/downloads/asterisk/all-asterisk-versions/

Features

• Automatic LTS Detection: Automatically detects and builds the latest Asterisk LTS version
• Registry-Aware: Checks Docker registry to avoid unnecessary rebuilds (source of truth)
• Multi-tag Strategy: Creates semantic tags (22.10.1, 22, latest-lts)
• Forgejo CI/CD: Automated builds via Forgejo Actions with scheduled checks
• Conditional Builds: Only builds when a new version is not already in registry

Quick Start

Manual Build

# Build latest LTS automatically (always builds)
./check-and-build.sh

# Check registry first, only build if not exists (requires auth)
./check-and-build.sh --check-registry

# Force rebuild
./check-and-build.sh --force

# Build specific version
./check-and-build.sh --version 22.10.1

# Build and push to registry
./check-and-build.sh --push

# Build, push, and run
./check-and-build.sh --push --run

Interactive Development

# Build and run with manual version
./run.sh

Version Policy

Asterisk follows this versioning policy:

• Even numbers (20, 22, 24...): LTS (Long Term Support) releases
• Odd numbers (21, 23...): Standard releases

This build system automatically tracks LTS releases only for stability.

CI/CD Automation (Forgejo)

The repository includes a Forgejo Actions workflow that:

1. Scheduled Checks: Runs daily (2 AM UTC) to check for new versions
2. Conditional Building: Only builds when a new LTS version is detected
3. Auto-tagging: Pushes images with version-specific and rolling tags
4. Manual Triggers: Supports manual workflow dispatch with options:
   • Force rebuild
   • Build specific version

Setup

1. Configure Secrets in your Forgejo repository:

   • REGISTRY_USERNAME: Your container registry username
   • REGISTRY_TOKEN: Your Forgejo access token (with package:read and package:write scope)

2. Enable Actions in repository settings

3. Workflow Triggers:

   • Automatic: Daily schedule
   • Manual: Actions tab → Build Asterisk Docker Image → Run workflow
   • On push: When build scripts change

Workflow Behavior

The workflow checks the actual Docker registry to determine if a build is needed:

Check Schedule (Daily)
        ↓
Detect Latest LTS Version
        ↓
Query Registry API
  (Does tag exist?)
        ↓
    ┌───┴───┐
Not Found    Exists
    ↓          ↓
Build & Push  Skip
              (fast - just a HEAD request)

Benefits of registry-based checking:

• No state files to manage (like .last-built-version)
• Source of truth is the actual registry
• Survives CI runner changes/restarts
• Can be run from any machine
• No artifact persistence needed

Scripts Reference

Script	Purpose
get-latest-lts.sh	Detect latest Asterisk LTS major version
check-registry.sh	Check if image exists in Docker registry
get-version-info.sh	Output version info as JSON for CI
check-and-build.sh	Check version and conditionally build locally
run.sh	Interactive development script

Docker Tags

Images are tagged with three strategies:

• Specific: git.flrn.eu/florian/asterisk:22.10.1
  • Pin to exact version
• Major version: git.flrn.eu/florian/asterisk:22
  • Track major branch
• Latest LTS: git.flrn.eu/florian/asterisk:latest-lts
  • Always the newest LTS

Configuration

Build Arguments

The Dockerfile accepts:

• AST_MAJOR_VERSION: Major version number (e.g., 22)
• AST_VERSION: Full version number (e.g., 22.10.1)

Environment Variables

Runtime environment:

• SMARTHOST: SMTP relay host for voicemail (format: host:port)
• SMARTHOST_FROM: SMTP default from

Volumes

• /etc/asterisk: Configuration files
• /var/spool/asterisk: Voicemail, recordings
• /var/log/asterisk: Log files
• /var/lib/asterisk/agi-bin: AGI scripts
• /var/lib/asterisk/sounds/prompts: Custom sound prompts
• /usr/local/bin: Custom binaries

Development

Project Structure

.
├── .forgejo/
│   └── workflows/
│       └── build-asterisk.yml    # CI/CD workflow
├── build/
│   ├── Dockerfile                # Container definition
│   ├── asterisk-build.sh         # Build script
│   └── asterisk-wrapper.sh       # Container entrypoint
├── etc/                          # Asterisk configs (mounted)
├── check-and-build.sh            # Local build script
├── check-registry.sh             # Registry existence check
├── get-latest-lts.sh             # Version detection
├── get-version-info.sh           # CI version helper
└── run.sh                        # Dev script

Registry Checking

The check-registry.sh script queries the Docker registry HTTP API to check if an image tag exists:

# Check if specific version exists
./check-registry.sh --version 22.10.1

# Output is JSON:
# {
#   "version": "22.10.1",
#   "major_version": "22",
#   "image": "git.flrn.eu/florian/asterisk:22.10.1",
#   "exists": true,
#   "needs_build": false,
#   "tags": ["..."]
# }

The script supports two methods:

1. Docker buildx (preferred): Uses docker buildx imagetools inspect if Docker is available
2. Registry API: Falls back to HTTP Registry API v2 for lightweight checks

Customizing the Build

To modify the Asterisk build:

1. Edit build/asterisk-build.sh to change compile options
2. Edit build/Dockerfile to change base image or add packages
3. Push changes - CI will rebuild with latest version

Troubleshooting

Build fails with "Could not resolve host"

Check network connectivity in your CI runner. The workflow requires outbound HTTPS access to:

• downloads.asterisk.org
• Your container registry

"No LTS version found"

The downloads page structure may have changed. Check get-latest-lts.sh and update the parsing logic.

Version not updating

Check that:

1. The registry check is working: ./check-registry.sh --version <version>
2. Registry credentials are correct (if private registry)
3. The image tag actually exists: docker pull <image>:<tag>

"Authentication required" error

If using a private registry, ensure REGISTRY_USERNAME and REGISTRY_TOKEN are set:

export REGISTRY_USERNAME=your-username
export REGISTRY_TOKEN=your-token

License

MIT - See your organization's policies

Co-Authored-By

AI assistants have been used in this project (mostly for the Action runners)