Skip to main content

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.

(Insert a “deployment topology” diagram here.)

2. Installation Options​

  1. Prepare config.toml plus the config/ subfolders described below.
  2. Pull the maintained image: docker pull docker.cnb.cool/miuda.ai/rustpbx:latest.
  3. 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 15060:15060/udp \
  docker.cnb.cool/miuda.ai/rustpbx:latest
  1. 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​

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

3. Initial Configuration​

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

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

(Insert a “config directory structure” screenshot or diagram.)

4. First boot and login​

  1. Start the service and open the console (default https://<host>:<port>/console/).
  2. Sign in with the administrator defined in the [console] section, change the password immediately, and enable MFA if integrated.
  3. Check the console status page and ensure every component reports “Healthy.” Investigate network or certificate issues before moving on.

5. Quick validation checklist​

  1. Create a test trunk: register a carrier or soft-switch connection and confirm authentication options.
  2. Add a routing rule: create inbound/outbound routes for a test number that forwards to a temporary extension or queue.
  3. Register a softphone: create an extension and sign in from a SIP endpoint or WebRTC phone.
  4. Place a test call: verify both parties connect and that recordings/CDRs appear in the console.
  5. 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.