diff --git a/docs/about/faq.md b/docs/about/faq.md index 54bddd4b..b06055fa 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -44,6 +44,58 @@ For convenience, we also [build container images with headscale](../setup/instal we don't officially support deploying headscale using Docker**. On our [Discord server](https://discord.gg/c84AZQhmpx) we have a "docker-issues" channel where you can ask for Docker-specific help to the community. +## Scaling / How many clients does Headscale support? + +It depends. As often stated, Headscale is not enterprise software and our focus +is homelabbers and self-hosters. Of course, we do not prevent people from using +it in a commercial/professional setting and often get questions about scaling. + +Please note that when Headscale is developed, performance is not part of the +consideration as the main audience is considered to be users with a moddest +amount of devices. We focus on correctness and feature parity with Tailscale +SaaS over time. + +To understand if you might be able to use Headscale for your usecase, I will +describe two scenarios in an effort to explain what is the central bottleneck +of Headscale: + +1. An environment with 1000 servers + + - they rarely "move" (change their endpoints) + - new nodes are added rarely + +2. An environment with 80 laptops/phones (end user devices) + + - nodes move often, e.g. switching from home to office + +Headscale calculates a map of all nodes that need to talk to each other, +creating this "world map" requires a lot of CPU time. When an event that +requires changes to this map happens, the whole "world" is recalculated, and a +new "world map" is created for every node in the network. + +This means that under certain conditions, Headscale can likely handle 100s +of devices (maybe more), if there is _little to no change_ happening in the +network. For example, in Scenario 1, the process of computing the world map is +extremly demanding due to the size of the network, but when the map has been +created and the nodes are not changing, the Headscale instance will likely +return to a very low resource usage until the next time there is an event +requiring the new map. + +In the case of Scenario 2, the process of computing the world map is less +demanding due to the smaller size of the network, however, the type of nodes +will likely change frequently, which would lead to a constant resource usage. + +Headscale will start to struggle when the two scenarios overlap, e.g. many nodes +with frequent changes will cause the resource usage to remain constantly high. +In the worst case scenario, the queue of nodes waiting for their map will grow +to a point where Headscale never will be able to catch up, and nodes will never +learn about the current state of the world. + +We expect that the performance will improve over time as we improve the code +base, but it is not a focus. In general, we will never make the tradeoff to make +things faster on the cost of less maintainable or readable code. We are a small +team and have to optimise for maintainabillity. + ## Which database should I use? We recommend the use of SQLite as database for headscale: @@ -56,6 +108,9 @@ We recommend the use of SQLite as database for headscale: The headscale project itself does not provide a tool to migrate from PostgreSQL to SQLite. Please have a look at [the related tools documentation](../ref/integration/tools.md) for migration tooling provided by the community. +The choice of database has little to no impact on the performance of the server, +see [Scaling / How many clients does Headscale support?](#scaling-how-many-clients-does-headscale-support) for understanding how Headscale spends its resources. + ## Why is my reverse proxy not working with headscale? We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have