||1 week ago|
|cmake||1 week ago|
|server||1 week ago|
|test||2 weeks ago|
|utils||2 weeks ago|
|vendor||2 weeks ago|
|.clang-tidy||1 month ago|
|.gitattributes||9 months ago|
|.gitignore||5 months ago|
|AGENTS.md||3 weeks ago|
|CHANGELOG.md||1 week ago|
|CMakeLists.txt||1 week ago|
|CONTRIBUTING.md||1 year ago|
|Dockerfile||2 months ago|
|Doxyfile||2 weeks ago|
|LICENSE.md||3 weeks ago|
|README.md||3 weeks ago|
|TODO||3 weeks ago|
|bootstrap.sh||9 months ago|
|config.hpp.in||2 months ago|
Coventry is a simple to setup IP telephony server for residential gateways and small office users. Coventry interconnects SIP users and devices with advanced voice, messaging, and facility automation services. Coventry would be used either stand-alone, such as off-grid facilities or boats, or connected thru upstream adapters to a carrier provider, a residential apartment complex switch, a SIP trunking provider, etc.
Other potential uses include remote property management, connecting security services, and general home automation. Coventry is meant to be runnable on gnu/linux servers and routers or in a container. My preferred installation target is a dedicated 32 bit arm device running Alpine Linux. A 2 digit local dialing plan and a maximum of 80 locally connected sip devices are supported.
When used as a residential ip telephony gateway Coventry may not include dedicated operator consoles or application services. Simple common residential style ringing would be used for external calls. A local sip application or media server like Bordeaux could be added to Coventry. Otherwise application services would likely be externally hosted. External connections such as to the PSTN would also typically be handled thru an upstream adapter.
Coventry originally was a small stand-alone gnu sipwitch VoIP wifi access point for use on early Raspberry Pi's first deployed in 2013. A few were made for residential use at the time, and I also used it when speaking at conferences. The Coventry codebase has no common code with gnu sipwitch, but it does use ideas from the development of SipWitchQt, including a simplified threaded event driven actor messaging system and shared pointer objects to avoid lock contention, but does so using only the c++17 standard library.
Docker and Podman
Coventry is usable both stand-alone and in a container. The definition for building a coventry container is a multi-stage Dockerfile which also compiles Coventry directly from the current "HEAD" of your git checkout. There is a special ``docker-images'' target to produce a container automatically for you. The Dockerfile automatically stages all development tools and dependencies as well. You can build coventry and run it in a container with just git and docker (or podman) without requiring any development environment to be setup.
The primary goal of containerization was to make it easy to reliably build, test, and deploy Coventry services directly from oci containers, such as for use on MicroOS, Kubernetics, etc. Another goal is to make it easier for anyone to participate in Coventry development.
Because the Docker builds depend on a git checkout, the stand-alone tarballs do not have cmake/docker.cmake support. The stand-alone tarballs mostly are meant to feed traditional rpm and deb packaging services. If one wants to produce a docker image from a past release, you can simply checkout the associated git tag for that release and build your docker targets from that.
Coventry requires eXosip2 version 5.3.0 or later and either openssl or libressl to build and run. A typical "install" target is created to support local installation. This should include an example config file. On openrc systems this may install an init script. A logrotate config can also be added. All running directories that may be required are either made by "install" or created when the service executes. Execution in daemon mode is done by the init script. The coventry.conf file (or custom.conf) should be edited for any sip extensions you wish to use.
Installation should only be attempted with cmake release builds. The
preferred cmake build type for live installations is
cmake -D CMAKE_BUILD_TYPE=RelWithDebugInfo .. This retains debug symbols in release
builds which many gnu/linux packaging systems then strip off and separately
generate a debug package.
Many paths are set by cmake configuration for release builds, and these can be
CMAKE -D... . overrides. Some of these are listed with the
--version option, so you can always find what paths a given coventry binary has
been built for to use. Fully static releases can be built on Alpine Linux.
cmake -DCMAKE_BUILD_TYPE=Debug . is used to produce a Debug build it can
be executed directly for testing from the server build directory such as with
./server/coventry -vvvv, no further install is required. The debug build
uses the config file found in the test/ directory, and a test/custom.conf file
can be added with configuration overrides for local developer testing.
test target runs a unit test framework. At the moment this only verifies
some of the header libraries. It may be extended to support component level
unit testing in the future.
A simple test/custom.conf to test your server might look like:
[server] algorithm = md5 expires = 2m  name = dyfet display = David Sugar password = XXX  name = bordeaux display = Bordeaux password = XXX lines = 20
For clients, the user id used for authentication is the same as the extension number, and Coventry should be in the default route or set as default proxy.
dist target is used to make detached tarballs with sources. This can be
used to make packages for gnu/linux distributions and bsd ports, such as for
arch, debian, alpine, redhat, etc. If the CMakeLists.txt refers to an already
tagged release version, it will re-create the source tarball of that release at
the time it was tagged. The master branch is usually ahead of the last release,
so any new work will create a tarball based on your last git commit.
Detached tarballs can be used to configure and build this software without
git, such as on a ci builder. It should not be used to make local changes
outside of git, and cannot produce additional tarballs itself. The
target only works with a git clone.
Participation and Documentation
Basic documentation is provided as markdown files. User operation, server admin, and configuration should be similarly added here. An installation guide for various GNU/Linux distributions and BSD systems may also be added. Developer documentation can be generated from source file headers using Doxygen and the ``docgen'' target. Documentation generated from the latest release tag is found at https://doc.gnutelephony.org/coventry.
A more complete overview of participation is provided in CONTRIBUTING.md. This project uses cmake, and c++17 for core server development. I use the ctest framework for unit testing and gcovr for coverage reports. Coventry can be built with gcc or clang and can be tested on just about any posix platform, including bsd systems.
In addition to producing testable debug builds the project can also be built for running unit tests. This is enabled by default for debug builds. To produce coverage reports you can cmake a debug build with -DCOVERAGE_TYPE=gcov set. You can then use the make the "coverage" target and produce coverage reports with gcovr or lcov. The "lint" target will validate code using cppcheck.
I chose to focus on Alpine Linux for deployment on low end arm devices since it includes pre-packaged support for SIP device provisioning integrated with their web front-end. This should make it easier to create complete stand-alone residential deployments. Coventry has no restrictions on it's deployment or uses, and I do welcome participation, patches, and testing on any platform it can be adapted for and ran on, including BSD systems. However it is possible my initial project documentation will be very Alpine focused.
Support is offered thru https://git.gnutelephony.org/coventry/issues. When entering a new support issue, please mark it part of the support project. I also have email@example.com. I may maintain system packaging for some GNU/Linux distributions, including Arch and Debian. I also have my own build infrastructure for Alpine Linux using ProduceIt, and I publish apk binary packages thru https://public.tychosoft.com/alpine. In the future maybe other means of support will become possible.