signalapp/Signal-Server: The Open-Source Java Backend for Signal Messaging

What Signal-Server Is and Why Most Engineers Read It

Signal-Server is the backend service that handles account registration, message routing, key distribution and other server-side functions for the Signal Private Messenger applications on Android, iOS and Desktop. Most developers who look at this repository are not looking to self-host a competing messaging service. They are studying how Signal's architecture handles end-to-end encryption at the server layer, examining how a production Java service at this scale is organized, or reviewing the AGPL-licensed source for compliance purposes.

The README is sparse. It covers three topics: how to build and test the server, how to report security issues, and a cryptography export notice. There is no architecture overview, no list of internal services, no database schema documentation and no deployment guide. Protocol documentation is referenced on the Signal website at https://signal.org/docs/ rather than in the repository itself. For developers expecting detailed operational documentation, the repository will be disappointing. The README explicitly acknowledges this: direct technical support is not available, and community help is handled through an unofficial forum at community.signalusers.org.

The FoundationDB Dependency and What It Implies

The build requirement that stands out immediately is FoundationDB. The README states the project "uses FoundationDB and requires the FoundationDB client library to be installed on the host system" before the build will succeed. FoundationDB is a distributed key-value store developed by Apple, released as open source and available for Linux and macOS. It is not part of a standard Java development environment and requires a separate installation step.

This dependency is a significant barrier for engineers who want to build the server on a generic development machine or in a CI environment that does not have FoundationDB installed. The README gives no guidance on which FoundationDB version to use or how to install it, only that the client library must be present. This is a design decision consistent with Signal's stated position that they cannot support custom deployments: the build process is documented for their own infrastructure, not as a general guide for others. Developers who have worked with FoundationDB in other contexts will find the build straightforward once the client library is in place.

Building and Testing Signal-Server

With the FoundationDB client library installed, the server is built and tested using the Maven wrapper:

$ ./mvnw clean test

This command cleans the previous build output, compiles the source and runs the test suite. The repository uses a Maven wrapper (mvnw and mvnw.cmd), which means a local Maven installation is not required: the wrapper downloads the correct Maven version on first run. The project layout shows a pom.xml at the root, a service/ directory containing the main server code, an integration-tests/ directory for integration testing, a websocket-resources/ directory and a spam-filter directory.

The repository also includes a TESTING.md file, which suggests additional documentation on the testing approach beyond what the README covers. The .github/ directory and .gitmodules file indicate the project uses GitHub Actions for CI and has git submodules. The api-doc/ directory likely contains OpenAPI or similar API documentation. None of these files are included in the README's minimal documentation, so their contents would require direct inspection.

The AGPLv3 License and Self-Hosting Constraints

Signal-Server is licensed under the GNU Affero General Public License version 3 (AGPLv3). The AGPLv3 is a copyleft license with a network use clause: if you run a modified version of AGPLv3-licensed software over a network and allow users to interact with it, you must make the complete corresponding source code available to those users under the same license. This is the key distinction between the AGPLv3 and the GPLv3: the GPLv3's source code disclosure obligation is triggered by distributing software, while the AGPLv3's obligation is triggered by network use.

For a developer who forks Signal-Server, modifies it and deploys it as a messaging service, the AGPLv3 requires them to provide source code to every user of that service. This is a real constraint for commercial deployments. For developers who read the code for study purposes or build internally without network distribution, the AGPLv3 imposes no special obligation beyond retaining the license and copyright notice. The copyright holder is Signal Messenger, LLC, as stated in the LICENSE file.

What Signal-Server's Repository Does Not Document

The gap between what the repository contains and what a developer needs to actually deploy Signal-Server is substantial. There is no docker-compose.yml or Kubernetes configuration. There is no documented list of environment variables, configuration files or required secrets beyond what can be inferred from the code. There are no deployment guides for AWS, Google Cloud or any specific infrastructure provider. The TESTING.md file exists but is separate from the README and its contents are not summarized.

Security reports are directed to [email protected] rather than to a public issue tracker. This means known security issues in Signal-Server are not visible through the GitHub issues list. The README gives no timeline for security disclosures and no bug bounty information. For an organization considering running Signal-Server internally, the absence of operational documentation means significant reverse-engineering work before deployment is feasible. The unofficial community forum at community.signalusers.org is where Signal directs self-hosters for help, but the quality and completeness of that community documentation varies.

Signal-Server vs Matrix/Synapse

Matrix is a federated, open standard for real-time communication. Synapse is the reference server implementation of the Matrix protocol, written in Python and maintained by the Matrix.org Foundation. The difference in approach is fundamental: Signal-Server is a centralized architecture where all Signal users connect to Signal's own servers, while Matrix/Synapse is federated, meaning anyone can run a Matrix server and users on different servers can communicate.

Federation makes Matrix/Synapse easier to self-host in a meaningful way: you run your own server, your users have accounts on it, and they can still communicate with users on other Matrix servers. Signal-Server, by contrast, is designed to operate as a single central service. Running your own Signal-Server does not give your users the ability to communicate with Signal's main network. The two projects serve different architecture goals and are not direct substitutes. Developers choosing between them are choosing between centralized end-to-end encryption and federated open messaging, which are distinct design philosophies.

Repository Activity and Cryptography Export Notice

The last push to Signal-Server was on 2026-09-25. There are no GitHub releases in the repository. The .java-version file in the repository root specifies the Java version the project targets, though the specific version is not visible in the README.

The README includes a substantial cryptography export notice, noting that the software has been classified by the U.S. Government under Export Commodity Control Number 5D002.C.1 and is eligible for export under the TSU exception in Section 740.13 of the BIS Export Administration Regulations. The notice recommends checking local laws before using the software in countries with restrictions on encryption software imports or use. The Wassenaar Arrangement website is referenced for more information. This notice is standard for cryptographic software distributed from the United States and applies to the repository itself, not only to compiled binaries.

Editorial conclusion

Developers who want to understand how Signal's backend architecture is structured will find the repository valuable as a reference. Self-hosting Signal-Server is a separate matter: the README does not document deployment, and the team refers self-hosters to an unofficial community forum. The AGPLv3 license means any modified version used over a network must have its source code made available. Before building, install the FoundationDB client library and verify that ./mvnw clean test completes without errors on your system. The cryptography export notice in the README applies in countries with restrictions on encryption software.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Project website
4. README
5. signalapp/Signal-Server on GitHub