docs: Add initial documentation
This commit is contained in:
Matthew Wild
parent
57f4310b2d
commit
73b709ff14
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: Advanced DNS setup
|
||||
---
|
||||
|
||||
The quick start guide helps you set up the essential DNS records for your Snikket
|
||||
service. There are a few additional records you can add to unlock some features
|
||||
of your Snikket service.
|
||||
|
||||
## Hosting on alternative XMPP ports
|
||||
|
||||
The default XMPP ports are:
|
||||
|
||||
- 5222 (for connections from the app and other XMPP clients)
|
||||
- 5269 (for connections from other Snikket/XMPP servers, i.e. federation)
|
||||
|
||||
If you want to change these, you can add a type of DNS record called SRV records.
|
||||
|
||||
Unfortunately SRV records setup varies widely between different DNS providers, so
|
||||
you'll need to figure out which info to put where yourself, based on the example
|
||||
records shown here.
|
||||
|
||||
An SRV record to override the client port looks like this:
|
||||
|
||||
```
|
||||
_xmpp-client._tcp.chat.example.com. 18000 IN SRV 0 0 5222 chat.example.com.
|
||||
```
|
||||
|
||||
While an SRV record to override the server-to-server port looks like this:
|
||||
|
||||
```
|
||||
_xmpp-server._tcp.chat.example.com. 18000 IN SRV 0 0 5269 chat.example.com.
|
||||
```
|
||||
|
||||
## Client connections through HTTPS port
|
||||
|
||||
It's possible to enable the client to connect through port 443 (the HTTPS port), which
|
||||
can allow bypassing some very restrictive firewalls.
|
||||
|
||||
Firstly, you need to set up sslh, as described in the [reverse proxy](reverse_proxy.md#sslh)
|
||||
documentation. Then you need to add the following SRV record:
|
||||
|
||||
```
|
||||
_xmpps-client._tcp.chat.example.com. 86400 IN SRV 5 0 443 chat.example.com.
|
||||
```
|
||||
|
||||
Note the 's' in `_xmpps-client`! The other differences in this record are that we set the port
|
||||
to 443 (the HTTPS port), and the priority to '5', so that clients supporting this connection
|
||||
method will prefer it over other connection methods (we specified priority '0' in the `_xmpp-client`
|
||||
example above).
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
# Firewall
|
||||
|
||||
## Ports
|
||||
|
||||
Snikket currently requires the following ports to be open/forwarded:
|
||||
|
||||
- **TCP only:** 80, 443, 5222, 5269
|
||||
- **TCP and UDP:** 3478, 3479, 5349, 5350
|
||||
- **UDP only:** 49152-65535
|
||||
|
|
@ -0,0 +1,111 @@
|
|||
---
|
||||
title: Reverse proxies
|
||||
---
|
||||
|
||||
# Running Snikket behind a reverse proxy
|
||||
|
||||
The default Snikket setup assumes that there is no other HTTP/HTTPS server
|
||||
running. If you already have another web server running for example, you will
|
||||
need to instruct it to forward Snikket traffic to Snikket.
|
||||
|
||||
!!! note
|
||||
|
||||
A quick note about non-HTTP services. Snikket includes a number of non-HTTP
|
||||
services which cannot be routed through a HTTP reverse proxy. This includes
|
||||
XMPP, STUN and TURN. The documentation here applies to redirecting the HTTP
|
||||
and HTTPS ports (80 and 443) through a reverse proxy only.
|
||||
|
||||
# Certificates
|
||||
|
||||
It is important to get certificates correct when deploying Snikket behind a reverse
|
||||
proxy. Snikket needs to obtain certificates from Let's Encrypt in order to secure
|
||||
the non-HTTP services it provides. Be careful that your reverse proxy does not
|
||||
requests from Let's Encrypt that are intended for the Snikket service.
|
||||
|
||||
# Configuration
|
||||
|
||||
## Snikket
|
||||
|
||||
First we need to tell Snikket to use alternative ports, so that it doesn't conflict
|
||||
with the primary web server/proxy that will be forwarding the traffic. This can be
|
||||
done by adding the following lines to /etc/snikket/snikket.conf:
|
||||
|
||||
```
|
||||
SNIKKET_TWEAK_HTTP_PORT=5080
|
||||
SNIKKET_TWEAK_HTTPS_PORT=5443
|
||||
```
|
||||
|
||||
You can choose any alternative ports that you would prefer, but the rest of this
|
||||
documentation will assume you use the ports given in this example.
|
||||
|
||||
In the next step, you need to configure the web server to forward traffic to
|
||||
Snikket on these ports. Follow the section below according to which web server
|
||||
you are using.
|
||||
|
||||
## Web servers
|
||||
|
||||
Each web server is different, so here we provide some example configuration snippets
|
||||
for the most common servers. Feel free to contribute any that you would like to see
|
||||
included!
|
||||
|
||||
### Nginx
|
||||
|
||||
```
|
||||
server {
|
||||
# Accept HTTP connections
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
|
||||
# Accept HTTPS connections
|
||||
listen [::]:443 ssl ipv6only=on;
|
||||
listen 443 ssl;
|
||||
ssl_certificate /path/to/certificate.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
server_name chat.example.com;
|
||||
server_name groups.example.com;
|
||||
server_name share.example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:5080/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### sslh
|
||||
|
||||
sslh is a little different to the other servers listed here, as it is not a web server. However it is able
|
||||
to route encrypted traffic (such as HTTPS and even some kinds of XMPP traffic) to different places.
|
||||
|
||||
The snippet below lists the rules required to forward all of Snikket's traffic to Snikket. Don't forget that
|
||||
Snikket will also need port 80 forwarded to 5080 somehow (otherwise it won't be able to obtain certificates).
|
||||
|
||||
Unlike the other solutions here, this approach also allows you to run encrypted XMPP through the HTTPS port.
|
||||
To take full advantage of this feature, you will need to add additional DNS records. See [advanced DNS](dns.md)
|
||||
for more information.
|
||||
|
||||
This configuration requires sslh 1.18 or higher.
|
||||
|
||||
```
|
||||
listen:
|
||||
(
|
||||
{ host: "0.0.0.0"; port: "443"; },
|
||||
);
|
||||
|
||||
protocols:
|
||||
(
|
||||
## Snikket rules
|
||||
# Send encrypted XMPP traffic directly to Snikket (this must be above the HTTPS rules)
|
||||
{ name: "tls"; host: "127.0.0.1"; port: "5223"; alpn_protocols: [ "xmpp-client" ]; },
|
||||
# Send HTTPS traffic to Snikket's HTTPS port
|
||||
{ name: "tls"; host: "127.0.0.1"; port: "5443"; sni_hostnames: [ "chat.example.com", "groups.chat.example.com", "share.chat.example.com" ] },
|
||||
# Send unencrypted XMPP traffic to Snikket (will use STARTTLS)
|
||||
{ name: "xmpp"; host: "127.0.0.1"; port: "5222"; },
|
||||
|
||||
## Other rules
|
||||
# Add rules here to forward any other hosts/protocols to non-Snikket destinations
|
||||
);
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: Snikket service documentation
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
The Snikket Service is the core part of running your own messaging service. It provides
|
||||
everything required for the Snikket app on users' devices to connect and exchange messages,
|
||||
media and calls.
|
||||
|
||||
If you are looking to set up Snikket for the first time, start with the [quick start guide](setup/quickstart.md).
|
||||
|
||||
After setup, if you want to explore further, check out the advanced topics.
|
||||
|
||||
# Feedback
|
||||
|
||||
We're always looking to improve Snikket further. Feel free to reach out at <feedback@snikket.org>.
|
||||
Let us know if you encountered any difficulty setting up, or even if it was a breeze!
|
||||
|
|
@ -0,0 +1,177 @@
|
|||
---
|
||||
title: "Quick-start guide"
|
||||
date: 2020-01-14T16:32:02Z
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
Hi, welcome! This is a guide to help you set up your own [Snikket service](/service/). Once it is set up,
|
||||
you will be able to invite others to join you using the [Snikket app](/app/) and chat over your own
|
||||
private messaging server!
|
||||
|
||||
Right, let's get started...
|
||||
|
||||
!!! warning
|
||||
|
||||
Heads up! Snikket is currently in its early stages (we launched at FOSDEM 2020!). Although you can
|
||||
use Snikket today, there are many features that are still to come, and we're working on improving the setup
|
||||
experience.
|
||||
|
||||
If you have any questions, feedback, or words of encouragement, we'd love to hear from you! Email us at
|
||||
feedback@snikket.org.
|
||||
|
||||
## Requirements
|
||||
|
||||
To follow this guide you will need:
|
||||
|
||||
- A server running Linux that you have SSH or terminal access to
|
||||
- A domain name that you can create subdomains on
|
||||
|
||||
For the server, you can use a VPS from a provider such as [DigitalOcean](https://digitalocean.com/) (you can use this [referral link for $100 credit](https://m.do.co/c/3ade5a32d0e0)),
|
||||
or you can use a physical device such as a Raspberry Pi. Note that if you run your server at home (which is _really_ cool!) you may need to forward some ports on your
|
||||
router.
|
||||
|
||||
{{< infobox warning >}}
|
||||
**Important:** Snikket provides a built-in web server that must be accessible on port 80. Therefore this guide assumes you are _not_ running any existing
|
||||
websites on the same server. We are working to remove this requirement in a future version.
|
||||
{{< /infobox >}}
|
||||
|
||||
## Get Started
|
||||
|
||||
### Step 1: DNS
|
||||
|
||||
First you need to find your server's public ("external") IP address. If you are using a hosted server, this may be shown in your management dashboard.
|
||||
At a pinch you can use an online service, e.g. by running `curl -4 ifconfig.co` in your terminal.
|
||||
|
||||
Now, add an A record for your IP address on the domain you want to run Snikket on. In the examples I'm going to use 'chat.example.com' as the domain,
|
||||
and '10.0.0.2' as the IP address. This will be the primary domain for your Snikket service.
|
||||
|
||||
```
|
||||
# Domain TTL Class Type Target
|
||||
chat.example.com. 300 IN A 10.0.0.2
|
||||
```
|
||||
|
||||
How to add records depends on where your DNS is hosted. Here are links to guides for a few common providers:
|
||||
|
||||
- [GoDaddy](https://uk.godaddy.com/help/add-an-a-record-19238)
|
||||
- [Gandi](https://docs.gandi.net/en/domain_names/faq/record_types/a_record.html)
|
||||
- [Namecheap](https://www.namecheap.com/support/knowledgebase/article.aspx/319/2237/how-can-i-set-up-an-a-address-record-for-my-domain)
|
||||
|
||||
**Tip:** If you have an IPv6 address too, this is where you can add it - simply make another record for `chat.example.com.` with the record
|
||||
type `AAAA` and put your IPv6 address as the target.
|
||||
|
||||
Now that you have an A record, you also need a couple more records. To avoid repeating the IP address everywhere, we'll use CNAME records,
|
||||
which are just like aliases of the main domain:
|
||||
|
||||
```
|
||||
# Domain TTL Class Type Target
|
||||
groups.chat.example.com 300 IN CNAME chat.example.com.
|
||||
share.chat.example.com 300 IN CNAME chat.example.com.
|
||||
```
|
||||
|
||||
These subdomains provide group chat functionality and file-sharing respectively.
|
||||
|
||||
### Step 2: Docker
|
||||
|
||||
Docker is a handy tool for running self-contained services known as "containers". We use Docker to provide Snikket
|
||||
in a clean way that works reliably across all different systems.
|
||||
|
||||
If you have the `docker` and `docker-compose` commands already available on your system, great! You can skip to Step 3 below. If not, continue reading.
|
||||
|
||||
#### docker
|
||||
|
||||
Getting docker up and running can vary depending on what OS you're running. Luckily Docker provides an installation guide
|
||||
for a range of operating systems. Follow the guide for your system:
|
||||
|
||||
- [CentOS](https://docs.docker.com/install/linux/docker-ce/centos/)
|
||||
- [Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
|
||||
- [Fedora](https://docs.docker.com/install/linux/docker-ce/fedora/)
|
||||
- [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/)
|
||||
|
||||
#### docker-compose
|
||||
|
||||
The Docker folks also provide a handy tool called `docker-compose` which is not installed by default. We're going to use it
|
||||
as an easy way to launch and configure Snikket.
|
||||
|
||||
As per the [installation instructions](https://docs.docker.com/compose/install/) (see the 'Linux' tab there), install
|
||||
`docker-compose` with the following commands:
|
||||
|
||||
```
|
||||
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
|
||||
sudo chmod a+x /usr/local/bin/docker-compose
|
||||
```
|
||||
|
||||
### Step 3: Prepare for Snikket!
|
||||
|
||||
This is exciting, we're so close!
|
||||
|
||||
Create a configuration directory and switch to it:
|
||||
|
||||
```
|
||||
mkdir /etc/snikket
|
||||
cd /etc/snikket
|
||||
```
|
||||
|
||||
And then create a new file there called `docker-compose.yml` using a text editor (such as nano, or vim).
|
||||
|
||||
```
|
||||
nano docker-compose.yml
|
||||
```
|
||||
|
||||
And here is what you should put in the file:
|
||||
|
||||
```
|
||||
version: "3.3"
|
||||
|
||||
services:
|
||||
snikket:
|
||||
container_name: snikket
|
||||
image: snikket/snikket:alpha
|
||||
env_file: snikket.conf
|
||||
restart: unless-stopped
|
||||
network_mode: host
|
||||
volumes:
|
||||
- snikket_data:/snikket
|
||||
|
||||
volumes:
|
||||
snikket_data:
|
||||
```
|
||||
|
||||
Now create another file in the same directory, `snikket.conf` with the following contents:
|
||||
|
||||
```
|
||||
# The primary domain of your Snikket instance
|
||||
SNIKKET_DOMAIN=chat.example.com
|
||||
|
||||
# An email address where the admin can be contacted
|
||||
# (also used to register your Let's Encrypt account to obtain certificates)
|
||||
SNIKKET_ADMIN_EMAIL=you@example.com
|
||||
```
|
||||
|
||||
Change the values to match your setup.
|
||||
|
||||
### Step 4: Launch
|
||||
|
||||
Here we go! Run:
|
||||
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
The first time you run this command docker will download Snikket. In a moment it should complete,
|
||||
and Snikket should be running.
|
||||
|
||||
Now to set up your first account. To create yourself an admin account, run the following command:
|
||||
|
||||
```
|
||||
docker exec snikket create-invite --admin
|
||||
```
|
||||
|
||||
Follow the link to open the invitation, and follow the instructions get signed in.
|
||||
|
||||
You can create as many links as you want and share them with people. Each link can
|
||||
only be used once. Don't forget to drop the `--admin` part to create normal user accounts!
|
||||
|
||||
{{< infobox primary >}}
|
||||
That's it! How did it go? Let us know at feedback@snikket.org
|
||||
{{< /infobox >}}
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
|
||||
site_name: Snikket Server Documentation
|
||||
docs_dir: docs
|
||||
theme: readthedocs
|
||||
|
||||
nav:
|
||||
- index.md
|
||||
- Setup:
|
||||
- setup/quickstart.md
|
||||
- Advanced:
|
||||
- advanced/dns.md
|
||||
- advanced/firewall.md
|
||||
- advanced/reverse_proxy.md
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- def_list
|
||||
- footnotes
|
||||
- toc:
|
||||
permalink: true
|
||||
Loading…
Reference in New Issue