Reviewed-on: https://gitea.tychosoft.com/public/coventry/pulls/56 Co-authored-by: David Sugar <firstname.lastname@example.org> Co-committed-by: David Sugar <email@example.com>
|15 hours ago|
|cmake||15 hours ago|
|server||15 hours ago|
|test||4 weeks ago|
|utils||1 week ago|
|vendor||3 months ago|
|.clang-tidy||1 month ago|
|.gitattributes||2 weeks ago|
|.gitignore||2 weeks ago|
|CHANGELOG.md||1 week ago|
|CMakeLists.txt||1 week ago|
|CONTRIBUTING.md||4 months ago|
|Dockerfile||15 hours ago|
|Doxyfile||1 month ago|
|LICENSE.md||1 year ago|
|README.md||1 month ago|
|TODO||1 year ago|
|bootstrap.sh||2 weeks ago|
|config.hpp.in||1 week ago|
Coventry is a simple to setup residential ip telephony gateway or small office voip server. Coventry would typically be used either stand-alone, such as off-grid facilities or boats, or connected thru an upstream adapter to a carrier provider, a residential apartment complex switch, etc. Other potential uses include remote property management, connecting security services, and general home automation. Coventry is meant to be runnable on embedded 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 by Coventry.
When used as a residential ip telephony gateway Coventry does 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. A premade oci image for the latest release is also found at https://reg.gnutelephony.org.
Coventry requires eXosip2 version 5.1.2 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.
When cmake is used to produce a Debug build this instance can be executed directly; 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. The preferred cmake build type for live installation and running of debug builds is RelWithDebugInfo.
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 firstname.lastname@example.org. Coventry packaging build support for some GNU/Linux distributions will be found on https://pkg.gnutelephony.org/coventry. I also have my own build infrastructure for Alpine 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.