2016-10-18 20:20:59 +00:00
# Prosody XMPP server for Raspberry Pi
2020-05-30 15:23:46 +00:00
This docker image provides you with a configured [Prosody ](https://prosody.im/ ) XMPP server. The image is intended to run on a Raspberry Pi (as it is based on _balenalib/rpi-raspbian_ ).
2016-10-18 20:20:59 +00:00
The server was tested using the Android App [Conversations ](https://conversations.im/ ) and the Desktop client [Gajim ](https://gajim.org ).
While Conversations got everything set-up out-of-the-box, Gajim was used with the following extensions:
2020-05-30 15:16:48 +00:00
2016-10-18 20:20:59 +00:00
* HttpUpload
* Off-The-Record Encryption
* OMEMO (requires _python-axolotl_ to be installed)
* Url Image preview
2020-05-30 15:23:46 +00:00
## Table of Contents
2020-05-30 15:16:48 +00:00
- [Prosody XMPP server for Raspberry Pi ](#prosody-xmpp-server-for-raspberry-pi )
2020-05-30 15:23:46 +00:00
- [Table of Contents ](#table-of-contents )
2020-05-30 15:16:48 +00:00
- [Features ](#features )
- [Requirements ](#requirements )
- [Image Details ](#image-details )
- [Ports ](#ports )
- [Directories ](#directories )
- [Run ](#run )
2020-05-31 13:22:26 +00:00
- [Configuration ](#configuration )
2020-06-01 05:25:31 +00:00
- [Environment variables ](#environment-variables )
2020-05-31 15:53:28 +00:00
- [DNS ](#dns )
2020-05-31 13:22:26 +00:00
- [server_contact_info ](#server_contact_info )
2020-05-30 15:16:48 +00:00
- [Debugging ](#debugging )
2020-05-31 15:53:28 +00:00
- [Extend ](#extend )
2020-05-30 15:16:48 +00:00
- [Upgrade ](#upgrade )
- [Test your server ](#test-your-server )
2016-10-18 20:20:59 +00:00
## Features
* Secure by default
* SSL certificate required
* End-to-end encryption required (using [OMEMO ](https://conversations.im/omemo/ ) or [OTR ](https://en.wikipedia.org/wiki/Off-the-Record_Messaging ))
* Data storage
2020-05-30 15:16:48 +00:00
* SQLite message store
2016-10-18 20:20:59 +00:00
* Configured file upload and image sharing
* Allows registration
2018-01-14 00:11:38 +00:00
* Multi-user chats
2016-10-18 20:20:59 +00:00
## Requirements
* You need a SSL certificate. I recommend [LetsEncrypt ](https://letsencrypt.org/ ) for that.
* Your Raspberry Pi should have docker set-up and running. You could use the Raspberry image for [Hypriot OS ](http://blog.hypriot.com/downloads/ ) to get started quickly.
## Image Details
### Ports
The following ports are exposed:
* 5000: proxy65 port used for file sharing
* 5222: c2s port (client to server)
* 5269: s2s port (server to server)
* 5347: XMPP component port
* 5280: BOSH / websocket port
* 5281: Secure BOSH / websocket port
### Directories
* Data: ```/usr/local/var/lib/prosody/```
* used for SQLite file
* used for HTTP uploads
* this is exposed as docker volume
* Bundled modules: ```/usr/local/lib/prosody/modules/```
* Additionally installed prosody modules: ```/usr/local/lib/prosody/custom-modules/```
* Config: ```/usr/local/etc/prosody/```
* containing the main config file called ```prosody.cfg.lua```
* containing additional config files within ```conf.d/```
* SSL certificates: ```/usr/local/etc/prosody/certs/```
* expects private key to be named ```prosody.key``` and certificate (fullchain) to be ```prosody.crt```
### Run
I recommend using a ```docker-compose.yml``` file:
```yaml
version: '2'
services:
server:
2018-01-14 00:11:38 +00:00
image: shaula/rpi-prosody:0.10
2016-10-18 20:20:59 +00:00
ports:
- "5000:5000"
- "5222:5222"
- "5269:5269"
- "5281:5281"
environment:
2020-05-31 15:53:28 +00:00
DOMAIN: domain.tld
2016-10-18 20:20:59 +00:00
volumes:
- ./privkey.pem:/usr/local/etc/prosody/certs/prosody.key
- ./fullchain.pem:/usr/local/etc/prosody/certs/prosody.crt
- ./data:/usr/local/var/lib/prosody
restart: unless-stopped
```
Boot it via: ```docker-compose up -d```
Inspect logs: ```docker-compose logs -f```
2020-05-31 15:53:28 +00:00
### Configuration
2016-10-18 20:20:59 +00:00
2020-06-01 05:25:31 +00:00
### Environment variables
| Variable | Description | Type | Default value |
| -------- | ----------- | ---- | ------------- |
| **DOMAIN** | domain | **required** | null
| **DOMAIN_HTTP_UPLOAD** | Domain which lets clients upload files over HTTP | *optional* | upload.**DOMAIN**
| **DOMAIN_MUC** | Domain for Multi-user chat (MUC) for allowing you to create hosted chatrooms/conferences for XMPP users | *optional* | conference.**DOMAIN**
| **DOMAIN_PROXY** | Domain for SOCKS5 bytestream proxy for server-proxied file transfers | *optional* | proxy.**DOMAIN**
2020-05-31 15:53:28 +00:00
#### DNS
2016-10-18 20:20:59 +00:00
2020-05-31 16:21:42 +00:00
You need these DNS record pointing to your server:
2020-05-31 09:24:31 +00:00
2020-05-31 15:53:28 +00:00
* domain.tld
* conference.domain.tld
* proxy.domain.tld
2020-05-31 16:21:42 +00:00
* upload.domain.tld
2016-10-18 20:20:59 +00:00
2020-05-31 15:53:28 +00:00
where domain.tld is the environment variable DOMAIN.
2020-05-31 13:22:26 +00:00
#### server_contact_info
This module lets you advertise various contact addresses for your XMPP service via XEP-0157.
It is configured for the following contacts:
* abuse
* admin
* feedback
* sales
* security
* support
2020-06-01 05:25:31 +00:00
You can change them in [05-server_contact_info.cfg.lua ](./conf.d/04-server_contact_info.cfg.lua ).
2020-05-31 13:22:26 +00:00
2016-10-18 20:20:59 +00:00
### Debugging
Change to verbose logging by replacing the following config lines within ```prosody.cfg.lua```:
```lua
log = {
{levels = {min = "info"}, to = "console"};
};
```
2020-05-30 15:16:48 +00:00
2016-10-18 20:20:59 +00:00
with:
```lua
log = {
{levels = {min = "debug"}, to = "console"};
};
```
2020-05-30 15:16:48 +00:00
2020-05-31 15:53:28 +00:00
### Extend
There is a helper script that eases installing additional prosody modules: ```docker-prosody-module-install```
It downloads the current [prosody-modules ](https://hg.prosody.im/prosody-modules/ ) repository. The specified modules are copied and its name is added to the ```modules_enabled``` variable within ```conf.d/01-modules.cfg.lua```.
There is also ```docker-prosody-module-copy``` which copies the specified modules but does not add them to the ```modules_enabled``` variable within ```conf.d/01-modules.cfg.lua```.
If you need additional configuration just overwrite the respective _cfg.lua_ file or add new ones.
2018-11-27 19:33:37 +00:00
### Upgrade
When migrating from 0.10, you need to update the database once:
```bash
docker-compose exec server bash
prosodyctl mod_storage_sql upgrade
```
2016-10-18 20:20:59 +00:00
2020-05-30 15:16:48 +00:00
## Test your server
You can test your server with these websites:
* [IM Observatory ](https://www.xmpp.net/ )
* [XMPP Compliance Tester ](https://compliance.conversations.im/ )