Basic Setup

Use this guide to bootstrap a production-ready RustPBX instance: environment requirements, installation paths, initial configuration, and smoke tests.

1. Prerequisites

Runtime environment: x86_64 Linux with at least 4 vCPUs / 8 GB RAM (Debian, Ubuntu, CentOS Stream verified).
Dependencies: Docker or Podman for container deployments, or a Rust toolchain for bare metal builds; SQLite or PostgreSQL/MySQL according to your Cargo.toml feature set.
Networking: allocate a public IP, open SIP/HTTPS/diagnostics ports, and allow carrier or SBC addresses through the firewall.
Certificates: WebRTC/HTTPS endpoints require TLS certificates; the addons/acme plugin can automate issuance.

2. Installation Options

2.1 Container image (recommended)

Prepare config.toml plus the config/ subfolders described below.
Pull the maintained image:
- docker pull ghcr.io/restsend/rustpbx:latest
- Or from the commercial registry: docker pull docker.cnb.cool/miuda.ai/rustpbx:latest
Launch example:

docker run -d --name rustpbx \
  -v $(pwd)/config.toml:/app/config.toml \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/rustpbx.sqlite3:/app/rustpbx.sqlite3 \
  -p 8080:8080 -p 5060:5060/udp -p 12000-42000:12000-42000/udp \
  ghcr.io/restsend/rustpbx:latest

In Compose or Kubernetes, reference the same image, mount configs and the database as persistent volumes, and forward the required ports. Logs stream to stdout/stderr so they can be collected centrally.

2.2 Bare metal build

Install Rust (rustup default stable).
Run cargo build --release from the repo root to obtain target/release/rustpbx.
Place the binary under /usr/local/bin and manage the service via systemd, supervisord, or a similar init system.

2.3 CLI options

Flag	Description
`--conf <PATH>`	Path to the configuration file (TOML format)
`--super-username <NAME>`	Create or update a console super user (requires `--super-password`)
`--super-password <PASS>`	Password for the console super user
`--super-email <EMAIL>`	Email for the console super user (defaults to `username@localhost`)
`--skip-migrate`	Skip database migrations on startup (useful for read-only replicas)
`--tokio-console <ADDR>`	Start tokio-console server for async task debugging

Subcommands

Command	Description
`check-config`	Validate the configuration file and exit without starting the server. Verifies all required sockets are available and config syntax is valid.

# Validate config before deployment
rustpbx --conf config.toml check-config

# Create admin user and exit
rustpbx --conf config.toml --super-username admin --super-password changeme

# Skip migrations (e.g., read-only DB replica)
rustpbx --conf config.toml --skip-migrate

3. Initial Configuration

RustPBX reads runtime settings from config.toml plus the files under config/:

config.toml: global services such as [proxy], [console], [recording], [sipflow], [callrecord], [rwi], [rwi_webhook], [cluster], [storage], [ua], optional addons, listen addresses (http_addr, proxy.addr), authentication (proxy.user_backends, console.allow_registration, console.api_tokens), and logging (log_level, log_file, log_rotation).
Trunk files: add TOML snippets under config/trunks/ that describe dest, backup_dest, inbound_hosts, codec, max_calls, max_cps, and credentials.
Routing files: define inbound/outbound rules in config/routes/, mapping match conditions to trunks, queues, IVRs, or reject actions.
Queue / ACL / IVR: add queue definitions in config/queue/, IVR flows in config/ivr/, and security policies in config/acl/ if you need skills-based routing or IP controls.
Database initialization: when the server starts it automatically runs the SeaORM migrations defined in models/migration.rs, so no extra command is required. Use --skip-migrate to bypass this.

3.1 Port ranges

# RTP media proxy port range (defaults: 12000–42000)
rtp_start_port = 12000
rtp_end_port = 42000

# WebRTC media port range (defaults: 30000–40000)
webrtc_start_port = 30000
webrtc_end_port = 40000

Ensure these ranges are open in your firewall. The media proxy selects available ports dynamically within these bounds.

3.2 Logging & log rotation

log_level = "info"
log_file = "/var/log/rustpbx/app.log"
log_rotation = "daily"   # "never" (default), "hourly", or "daily"

When log_rotation is set, log files are archived with a timestamp suffix at each rotation boundary. HTTP access logs support structured AccessLogEventFormat for ELK/Loki pipeline ingestion.

3.3 JWT authentication for SIP

RustPBX supports fast SIP registration via JWT tokens — extensions can register without supplying a password by presenting a signed JWT in a SIP header:

[proxy.jwt_auth]
enabled = true
secret = "your-jwt-secret-key"
user_id_claim = "userId"          # JWT claim containing the extension number
issuer = "auth.example.com"       # Optional: require specific issuer
audience = "rustpbx"              # Optional: require specific audience
sip_header_name = "X-Auth-Token"  # SIP header carrying the JWT
check_local_user = false          # Whether to also check local DB
ws_token_param = "token"          # URL param for WebSocket tokens
dev_mint_enabled = false          # Dev token mint endpoints (production: off)

When JWT auth is enabled, an INVITE/REGISTER carrying X-Auth-Token: <jwt> (or ?token=<jwt> on WebSocket) is authenticated against the JWT claims — no digest challenge is sent.

3.4 Emergency routing

[proxy.emergency]
enabled = true
numbers = ["110", "119", "120", "122", "911", "999"]
emergency_trunk = "emergency-carrier"

Calls to listed emergency numbers are immediately routed to the designated emergency_trunk, bypassing normal routing rules. The default number set covers major CN/US/UK emergency services.

3.5 Storage backends (recordings, CDR, SipFlow)

[storage]
type = "s3"               # "local" (default), "s3", "azure", "gcp"
[storage.s3]
vendor = "minio"          # "aws", "minio", "aliyun", "cos"
bucket = "rustpbx-recordings"
region = "us-east-1"
access_key = "AKIA..."
secret_key = "..."
endpoint = "https://s3.example.com"
root = "recordings/"

The [storage] section configures object storage for recording uploads, CDR archiving, and SipFlow offload. Configured once and shared across [recording], [callrecord], and [sipflow] subsystems.

rustpbx/
├── 📁 config/
│   ├── 📁 trunks/      → SIP trunk configurations
│   ├── 📁 routes/      → Inbound/outbound routing rules
│   ├── 📁 queue/       → Call queue definitions
│   ├── 📁 ivr/         → IVR flow definitions
│   ├── 📁 acl/         → Access control / IP policies
│   ├── 📁 recorders/   → Recording configurations
│   ├── 📁 sounds/      → Audio prompts and sounds
│   ├── 📁 cdr/         → Call detail records
│   ├── 📁 voicemail/   → Voicemail mailbox configs
│   ├── 📁 models/      → Voice models (VAD, ASR, Denoiser)
│   ├── 📁 cc/          → Contact center skill group configs
│   └── 📁 sipflow/     → SipFlow capture storage
└── 📄 config.toml      → Main configuration file

4. First boot and login

Start the service:
- Container: docker run ... as shown above.
- Bare metal: /static/docs/rustpbx/rustpbx --conf config.toml
- Create admin on first run: /static/docs/rustpbx/rustpbx --conf config.toml --super-username admin --super-password changeme
Open the console (default http://<host>:8080/console/).
Sign in with the administrator credentials, change the password immediately, and enable MFA if integrated.
Check the console status page and ensure every component reports “Healthy.” Investigate network or certificate issues before moving on.

4.1 API Token Authentication (optional)

For external systems that need programmatic access to the REST API (e.g., automation scripts, CRM integration), you can configure static API tokens in config.toml:

[console]
api_tokens = [
  { token = "pbx-api-token-xxxx", scopes = ["call.control", "recording"], description = "CRM integration" },
  { token = "pbx-monitor-token-yyyy", scopes = ["diagnostics"], description = "Monitoring system" },
]

Tokens are sent as Authorization: Bearer <token> headers.
Scopes control access: call.control, recording, diagnostics, routing, extension, sip_trunk, etc.
Token-authenticated requests are exempt from CSRF checks (they use Bearer auth, not cookies).

5. Quick validation checklist

Create a test trunk: register a carrier or soft-switch connection and confirm authentication options.
Add a routing rule: create inbound/outbound routes for a test number that forwards to a temporary extension or queue.
Register a softphone: create an extension and sign in from a SIP endpoint or WebRTC phone.
Place a test call: verify both parties connect and that recordings/CDRs appear in the console.
Reload & evaluate: run Settings → Reload and use Diagnostics → Routing → Evaluate to make sure the new rule hits the intended trunk.

Once these checks pass, the cluster is ready for pilot traffic. Dive into the other chapters for advanced routing, billing, and troubleshooting practices.