go-sip/deploys/README.md

Physical-host deployment

Production services run directly on Debian 13 (Trixie) physical/virtual host processes managed by systemd. Docker is permitted only for disposable local or ECS smoke validation; it is not a production runtime dependency.

The pinned baseline is versions.lock.json: Go 1.27.1, 0.1.0-p1.20260919, Debian 13 amd64 and Asterisk 22.10.1. The Go release package contains only our SIP Agent/Dispatcher business binaries and their systemd units. SaaS-provided MQ, OSS, AI and other infrastructure are endpoints, not packages deployed by this project; local chain validation may use isolated fixtures/mocks only. Secrets, certificates, SIP credentials, broker URLs and phone-log keys are injected separately.

Before every real outbound attempt, obtain a fresh user confirmation in the current conversation and display the exact SIP channel, raw target number and packet-capture plan. Real SIP outbound calls are permitted only from 09:00 (inclusive) through 20:00 (exclusive), Asia/Shanghai time; outside that window the Agent/Dispatcher must fail closed rather than wait, retry, delay or switch trunks. A prior confirmation does not authorize retries or another target; stop after a failed attempt until a new confirmation is received.

One deployment directory

deploys/ is the only deployment directory for local checks, physical-host packages, Asterisk installation, configuration examples and systemd services. There is no separate draft service set or compatibility deployment directory.

Local and isolated checks

From the project root:

make check
make release
./dist/sip-go-agent agent --help
./dist/sip-go-agent dispatcher --help

make release creates a local-development binary, module copies, SHA-256 checksums and a manifest. A dirty-source marker is preserved; a local build is not a signed production candidate or proof of external service acceptance.

For an isolated Dispatcher-to-Agent startup check, prepare the strict Dispatcher JSON configuration from config/dispatcher.json.example, inject its referenced credentials outside the repository, and supply the deployment-owned endpoint inventory and mTLS files. The local acceptance script also requires a loopback RabbitMQ URL because dispatcher --once must prove it can publish through the configured broker; it fails closed when the URL is absent:

GO_SIP_LOCAL_MQ_URL=amqp://guest:guest@127.0.0.1:33252/ \
  ./scripts/acceptance-local.sh

The command below is the long-running endpoint check:

SIP_GO_AGENT_MODE=mock \
DISPATCHER_DB=./dispatcher.db \
DISPATCHER_AGENT_ENDPOINTS_FILE=./deploys/config/agent-endpoints.example.json \
MTLS_CA_FILE=/path/to/ca.pem \
MTLS_CERT_FILE=/path/to/dispatcher.pem \
MTLS_KEY_FILE=/path/to/dispatcher.key \
./dist/sip-go-agent dispatcher --config /path/to/dispatcher.json --once

The Dispatcher probes the configured Agent, verifies its boot identity and activates a session before use. Tenant commands cannot select an endpoint or certificate. Agent RPC listening uses AGENT_GRPC_LISTEN and deployment-provided mTLS files; an Agent-side peer allowlist can be supplied with MTLS_PEER_CERT_FINGERPRINTS. Never place credentials or private keys in this repository.

Dispatcher owns its SQLite database; Agent owns a separate AGENT_SPOOL and has no business database. These are single-node, single-Agent/Cell/tenant checks, not multi-Cell or production acceptance. Local protocol tests do not replace the mandatory deployment/capture diagnostics below. Mock is not authorization for real calls or paid provider requests.

Build an uploadable package

From the project root:

deploys/build-package.sh
deploys/packages/sip-go-agent-0.1.0-p1.20260919-linux-amd64.tar.gz

The package includes its SHA-256 manifest, a non-root systemd deployment layout, and the fail-closed non-production capture-first entrypoint. The installer installs that entrypoint as /usr/local/sbin/agent-call-nonprod-evidence and adds a dedicated validated sudoers rule for rogee; it does not install tcpdump or silently weaken production gates. A dirty/unapproved source manifest is intentionally rejected by the installer unless --allow-nonproduction is supplied for smoke work.

Install on Debian 13

Upload and extract the archive on the target host, then run as root:

tar -xzf sip-go-agent-0.1.0-p1.20260919-linux-amd64.tar.gz
./install.sh

The installer verifies Debian 13 amd64, package checksums and the release manifest; creates rogee, /opt/sip-go-agent, /etc/sip-go-agent and /var/lib/sip-go-agent, installs both systemd units, and does not overwrite existing environment or PKI files. Configure the injected values and approved static Cell artifact, then start explicitly:

systemctl enable sip-go-agent-agent.service sip-go-agent-dispatcher.service
systemctl start sip-go-agent-dispatcher.service sip-go-agent-agent.service

Use ./install.sh --start only after the environment, mTLS identity, broker ACL and static Cell artifact have been reviewed. Production mode never silently falls back to Mock.

Non-production capture-first gate

Development, mock, mixed and non-production real validation must use cell/nonprod-call-evidence.sh as the single capture-first entrypoint. It refuses production, validates the approved trunk and whitelist target, verifies tcpdump raw-capture capability, records the pre-call Debian/systemd/ECS-facing facts plus Asterisk/PJSIP/channel/media state, enables the PJSIP logger, captures SIP UDP 5060 and RTP UDP 10000-10800 before the call command starts, and always stops capture/logger and writes redacted status plus SHA-256 facts on success or failure. Real calls reserve a daily attempt in /var/lib/sip-go-agent/state/real-call-attempts.tsv per trunk + original target; the fourth attempt is rejected fail-closed, while --preflight-only does not consume quota. Existing real evidence is counted when seeding the ledger.

Run it only after a fresh current-conversation confirmation naming the exact trunk, raw target and capture plan; the command after -- must execute as the non-root rogee user. Do not invoke the Agent directly for a non-production real/mixed call, do not retry inside the wrapper, and do not treat a missing PCAP or state snapshot as a pass. The private call output and raw capture stay under the mode-0700 evidence directory and must not be copied into repository long-term evidence without redaction.

Cell boundary

Asterisk remains the SIP owner and is installed as the separately approved physical Asterisk 22.10.1 Cell service. Asterisk and the SIP Agent are the only business-code services in this repository. The Go package does not rewrite pjsip.conf, embed SIP credentials, or run Asterisk in Docker. Management owns the immutable static Cell artifact and its systemd/maintenance release; the Go Agent consumes the approved artifact and reports the applied revision.

RabbitMQ, OSS, AI providers and SaaS APIs are external infrastructure. They are not installed by deploys/; their production ACLs/endpoints are supplied by SaaS, while local validation uses explicitly isolated test infrastructure. For non-ECS/offline Alibaba OSS validation, use deploys/env/dispatcher.offline-oss.env.example (public oss-cn-beijing.aliyuncs.com); keep dispatcher.env.example's internal endpoint for the separately managed production ECS profile.