mirror of
https://github.com/juanfont/headscale.git
synced 2024-11-24 18:45:24 +00:00
8c7d8ee34f
* Setup mkdocs-redirects * Restructure existing documentation * Move client OS support into the documentation * Move existing Client OS support table into its own documentation page * Link from README.md to the rendered documentation * Document minimum Tailscale client version * Reuse CONTRIBUTING.md" in the documentation * Include "CONTRIBUTING.md" from the repository root * Update FAQ and index page and link to the contributing docs * Add configuration reference * Add a getting started page and explain the first steps with headscale * Use the existing "Using headscale" sections and combine them into a single getting started guide with a little bit more explanation. * Explain how to get help from the command line client. * Remove duplicated sections from existing installation guides * Document requirements and assumptions * Document packages provided by the community * Move deb install guide to official releases * Move manual install guide to official releases * Move container documentation to setup section * Move sealos documentation to cloud install page * Move OpenBSD docs to build from source * Simplify DNS documentation * Add sponsor page * Add releases page * Add features page * Add help page * Add upgrading page * Adjust mkdocs nav * Update wording Use the term headscale for the project, Headscale on the beginning of a sentence and `headscale` when refering to the CLI. * Welcome to headscale * Link to existing documentation in the FAQ * Remove the goal header and use the text as opener * Indent code block in OIDC * Make a few pages linter compatible Also update ignored files for prettier * Recommend HTTPS on port 443 Fixes: #2164 * Use hosts in acl documentation thx @efficacy38 for noticing this Ref: #1863 * Use mkdocs-macros to set headscale version once
154 lines
5.0 KiB
Markdown
154 lines
5.0 KiB
Markdown
|
|
|
|
|
|
|
|
An open source, self-hosted implementation of the Tailscale control server.
|
|
|
|
Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat.
|
|
|
|
**Note:** Always select the same GitHub tag as the released version you use
|
|
to ensure you have the correct example configuration and documentation.
|
|
The `main` branch might contain unreleased changes.
|
|
|
|
## What is Tailscale
|
|
|
|
Tailscale is [a modern VPN](https://tailscale.com/) built on top of
|
|
[Wireguard](https://www.wireguard.com/).
|
|
It [works like an overlay network](https://tailscale.com/blog/how-tailscale-works/)
|
|
between the computers of your networks - using
|
|
[NAT traversal](https://tailscale.com/blog/how-nat-traversal-works/).
|
|
|
|
Everything in Tailscale is Open Source, except the GUI clients for proprietary OS
|
|
(Windows and macOS/iOS), and the control server.
|
|
|
|
The control server works as an exchange point of Wireguard public keys for the
|
|
nodes in the Tailscale network. It assigns the IP addresses of the clients,
|
|
creates the boundaries between each user, enables sharing machines between users,
|
|
and exposes the advertised routes of your nodes.
|
|
|
|
A [Tailscale network (tailnet)](https://tailscale.com/kb/1136/tailnet/) is private
|
|
network which Tailscale assigns to a user in terms of private users or an
|
|
organisation.
|
|
|
|
## Design goal
|
|
|
|
Headscale aims to implement a self-hosted, open source alternative to the Tailscale
|
|
control server.
|
|
Headscale's goal is to provide self-hosters and hobbyists with an open-source
|
|
server they can use for their projects and labs.
|
|
It implements a narrow scope, a single Tailnet, suitable for a personal use, or a small
|
|
open-source organisation.
|
|
|
|
## Supporting Headscale
|
|
|
|
If you like `headscale` and find it useful, there is a sponsorship and donation
|
|
buttons available in the repo.
|
|
|
|
## Features
|
|
|
|
Please see ["Features" in the documentation](https://headscale.net/about/features/).
|
|
|
|
## Client OS support
|
|
|
|
Please see ["Client and operating system support" in the documentation](https://headscale.net/about/clients/).
|
|
|
|
## Running headscale
|
|
|
|
**Please note that we do not support nor encourage the use of reverse proxies
|
|
and container to run Headscale.**
|
|
|
|
Please have a look at the [`documentation`](https://headscale.net/).
|
|
|
|
## Talks
|
|
|
|
- Fosdem 2023 (video): [Headscale: How we are using integration testing to reimplement Tailscale](https://fosdem.org/2023/schedule/event/goheadscale/)
|
|
- presented by Juan Font Alonso and Kristoffer Dalby
|
|
|
|
## Disclaimer
|
|
|
|
This project is not associated with Tailscale Inc.
|
|
|
|
However, one of the active maintainers for Headscale [is employed by Tailscale](https://tailscale.com/blog/opensource) and he is allowed to spend work hours contributing to the project. Contributions from this maintainer are reviewed by other maintainers.
|
|
|
|
The maintainers work together on setting the direction for the project. The underlying principle is to serve the community of self-hosters, enthusiasts and hobbyists - while having a sustainable project.
|
|
|
|
## Contributing
|
|
|
|
Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
|
|
|
|
### Requirements
|
|
|
|
To contribute to headscale you would need the latest version of [Go](https://golang.org)
|
|
and [Buf](https://buf.build) (Protobuf generator).
|
|
|
|
We recommend using [Nix](https://nixos.org/) to setup a development environment. This can
|
|
be done with `nix develop`, which will install the tools and give you a shell.
|
|
This guarantees that you will have the same dev env as `headscale` maintainers.
|
|
|
|
### Code style
|
|
|
|
To ensure we have some consistency with a growing number of contributions,
|
|
this project has adopted linting and style/formatting rules:
|
|
|
|
The **Go** code is linted with [`golangci-lint`](https://golangci-lint.run) and
|
|
formatted with [`golines`](https://github.com/segmentio/golines) (width 88) and
|
|
[`gofumpt`](https://github.com/mvdan/gofumpt).
|
|
Please configure your editor to run the tools while developing and make sure to
|
|
run `make lint` and `make fmt` before committing any code.
|
|
|
|
The **Proto** code is linted with [`buf`](https://docs.buf.build/lint/overview) and
|
|
formatted with [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html).
|
|
|
|
The **rest** (Markdown, YAML, etc) is formatted with [`prettier`](https://prettier.io).
|
|
|
|
Check out the `.golangci.yaml` and `Makefile` to see the specific configuration.
|
|
|
|
### Install development tools
|
|
|
|
- Go
|
|
- Buf
|
|
- Protobuf tools
|
|
|
|
Install and activate:
|
|
|
|
```shell
|
|
nix develop
|
|
```
|
|
|
|
### Testing and building
|
|
|
|
Some parts of the project require the generation of Go code from Protobuf
|
|
(if changes are made in `proto/`) and it must be (re-)generated with:
|
|
|
|
```shell
|
|
make generate
|
|
```
|
|
|
|
**Note**: Please check in changes from `gen/` in a separate commit to make it easier to review.
|
|
|
|
To run the tests:
|
|
|
|
```shell
|
|
make test
|
|
```
|
|
|
|
To build the program:
|
|
|
|
```shell
|
|
nix build
|
|
```
|
|
|
|
or
|
|
|
|
```shell
|
|
make build
|
|
```
|
|
|
|
## Contributors
|
|
|
|
<a href="https://github.com/juanfont/headscale/graphs/contributors">
|
|
<img src="https://contrib.rocks/image?repo=juanfont/headscale" />
|
|
</a>
|
|
|
|
Made with [contrib.rocks](https://contrib.rocks).
|