They Only Accept Fax

They Only AcceptFax

Introduction

In modern DevOps environments, the expectation is that communication channels are flexible, API‑first, and fully automated. Yet there are still scenarios where an external partner insists on using a fax machine as the only acceptable medium. This constraint may sound antiquated, but it surfaces regularly in homelab projects, legacy‑system integrations, and small‑scale production setups.

When a team discovers that a critical external contact will not entertain email, Slack, or any other digital channel, the instinct is to treat the fax requirement as a novelty. In reality, it becomes a concrete infrastructure challenge: how do you bridge a fax‑only workflow with contemporary self‑hosted services without introducing unnecessary complexity or security risks?

This guide walks you through the entire lifecycle of solving “they only accept fax” problems. You will learn:

• Why fax‑only communication still matters in certain contexts
• The architecture of a reliable fax‑to‑email gateway that can be deployed on a homelab server
• Step‑by‑step installation and configuration of open‑source components using Docker
• Security hardening, performance tuning, and operational best practices
• Troubleshooting techniques for common issues such as modem detection failures or email delivery errors

By the end of this article, you will have a production‑ready fax gateway that translates inbound faxes into searchable PDFs or images and forwards them automatically to your internal mail server, while keeping the entire stack under your control.

Understanding the Topic

What is a Fax‑to‑Email Gateway?

A fax‑to‑email gateway is a software service that receives fax signals from a telephone line (often via a modem or a VoIP‑based fax interface), converts the fax into a digital format (typically a PDF or TIFF), and then routes that file to an email address or a mail transfer agent (MTA). The reverse flow — email‑to‑fax — can also be supported, but the focus here is on inbound faxes that must be processed by an external party that insists on receiving them via fax.

Key components of a typical gateway:

Component	Role	Typical Implementation
Modem/Interface driver	Captures fax tones and data from the telephone line	mgetty, efax, or a USB fax modem driver
Fax reception engine	Parses the raw fax stream into a usable document	HylaFAX, Asterisk with fax module, or HylaFAX‑based Docker images
Document conversion	Transforms the fax into a standard file format	tesseract OCR, ImageMagick, or built‑in conversion utilities
Mail injection module	Sends the resulting file to an SMTP server	postfix, ssmtp, or direct sendmail calls
Configuration layer	Centralizes settings for flexibility	YAML or JSON config files, environment variables

History and Development

The concept of converting fax to email dates back to the early 2000s when businesses sought to eliminate paper archives. Early solutions required dedicated hardware and proprietary software. Open‑source projects such as HylaFAX (released in 1999) and later Asterisk’s fax modules made it possible to build fully software‑defined gateways.

In the last decade, containerization has simplified deployment. Projects like docker‑fax‑gateway and community‑maintained Dockerfiles now allow you to spin up a complete fax‑to‑email service with a single docker compose up -d command, making the solution portable across homelab servers, cloud VMs, or on‑premise hardware.

Key Features * Modem Agnosticism – Works with USB, PCI, or virtual fax modems.

• Multi‑Channel Support – Handles multiple concurrent fax sessions.
• PDF/TIFF Output – Stores faxes as searchable PDFs or high‑resolution images.
• SMTP Integration – Directly forwards documents to any configured mail server.
• Web UI (optional) – Provides status pages and basic management via a browser.
• Docker‑Ready – Entire stack can be orchestrated with Docker Compose, facilitating easy updates and rollbacks.

Pros and Cons | Advantages | Disadvantages |

|————|—————| | Full control over the conversion pipeline | Requires a physical or virtual modem device | | Can be integrated into existing CI/CD pipelines for audit trails | Modem driver compatibility can be finicky on newer kernels | | Open‑source components reduce licensing costs | Email deliverability depends on proper SPF/DKIM configuration | | Dockerized deployment simplifies scaling and testing | Fax quality is limited by the underlying modem’s resolution | | Extensible with custom scripts for additional processing | Real‑time fax transmission may experience latency on congested networks |

Use Cases and Scenarios

• Legacy Vendor Integration – Some external partners only accept faxes for contract signatures or purchase orders.
• Regulatory Document Archiving – Industries such as finance or healthcare may still require faxed signatures for certain forms.
• Small‑Scale Homelab Projects – Demonstrating a complete end‑to‑end workflow using open‑source tools.
• Disaster Recovery – Maintaining a fax‑only fallback channel when primary email services are unavailable.

Current State and Future Trends

The proliferation of VoIP services has shifted fax communication toward SIP‑based fax (T.38) and online fax providers. However, many small businesses still rely on analog phone lines, meaning a physical modem remains necessary. Future trends point toward:

• Container‑native fax modules that can be deployed as sidecars in Kubernetes environments.
• AI‑enhanced OCR for automatic metadata extraction from scanned faxes.
• Standardized APIs that allow fax gateways to be orchestrated via REST, enabling better integration with DevOps pipelines.

Comparison with Alternatives

Solution	Deployment Model	Cost	Flexibility
Commercial Online Fax Service	SaaS	Subscription	Limited customization
Proprietary Hardware Gateway	Appliance	High upfront	Moderate
Open‑Source Dockerized Gateway	Self‑hosted	Low (open source)	High (full control)
Asterisk with T.38 Module	Self‑hosted PBX	Low	High, but requires telephony stack

The open‑source Docker approach wins on cost and configurability, especially for homelab enthusiasts who already manage Docker containers for other services.

Real‑World Success Stories

• A boutique law firm integrated a Dockerized fax gateway to receive client‑signed contracts via fax. The PDFs were automatically stored in a secured bucket and linked to the firm’s case management system.
• A regional utility company used a HylaFAX‑based container to collect field‑technician reports sent over analog lines. The reports were parsed, tagged, and forwarded to the internal ticketing system, reducing manual data entry by 80 %.
• A community‑run homelab built a multi‑tenant fax‑to‑email service where each tenant could configure their own email destination, demonstrating the solution’s scalability.

Prerequisites Before you begin, ensure that your environment meets the following requirements.

System Requirements | Requirement | Minimum | Recommended |

|————-|———|————-| | CPU | 2 vCPU | 4 vCPU | | RAM | 2 GB | 4 GB | | Storage | 10 GB SSD | 20 GB SSD | | Network | 1 Gbps NIC | 1 Gbps NIC with VLAN support | | OS | Ubuntu 22.04 LTS | Debian 12 or Ubuntu 24.04 LTS |

Required Software with Specific Versions

Component	Version	Purpose
Docker Engine	24.0+	Container runtime
Docker Compose	2.20+	Multi‑container orchestration
mgetty	1.2.5+	Modem control and fax reception
HylaFAX	6.1+	Fax engine and document generation
Postfix (or similar MTA)	3.8+	Email delivery
OpenSSH	9.2+	Secure remote administration

Network and Security Considerations

• The fax modem must be accessible to the Docker host. If using a USB modem, ensure it is passed through to the container with appropriate permissions (--device /dev/ttyUSB0).
• Restrict inbound traffic to the SMTP port (25, 587, or 465) using firewall rules (ufw or iptables).
• Enable TLS for email transmission if your mail server supports it, to prevent plaintext credential exposure.

User Permissions and Access Levels Needed

• Root or sudo privileges to install Docker and load kernel modules for the modem.
• Membership in the dialout group to allow Docker to access /dev/ttyUSB* devices.
• A dedicated system user (e.g., faxgateway) for running the container processes, enhancing isolation.

Pre‑Installation Checklist

1. Verify modem detection: lsusb or dmesg | grep tty.
2. Install Docker Engine and Compose according to the official documentation.
3. Create a non‑root user for container execution and add to dialout.
4. Reserve a static IP address for the fax modem interface to avoid DHCP conflicts.
5. Draft a basic docker-compose.yml skeleton that will be expanded later.

Installation & Setup

Step‑by‑Step Installation Commands Below is a complete, reproducible installation workflow using Docker Compose. All commands assume you are operating as a user with sudo privileges. ```bash

1. Create a dedicated directory for the fax gateway

sudo mkdir -p /opt/fax-gateway sudo chown $USER:$USER /opt/fax-gateway

2. Navigate to the directory

cd /opt/fax-gateway

3. Create a docker-compose.yml file with the following content

cat > docker-compose.yml «‘EOF’ version: ‘3.8’

services: fax-engine: image: ghcr.io/hylafax/hylafax:latest container_name: $CONTAINER_NAMES-fax restart: unless-stopped environment: - HYAFAX_DB=/var/lib/hylafax - HYAFAX_LOG=/var/log/h ```