gsvd

My Prosody setup with Docker Compose

Sat, 21 Mar 2026 18:12:00 -0400

Introduction

After all these years spent secretly refusing to welcome Docker into my self-hosting journey, I finally switched to a Docker Compose Stack - way of managing most of my applications. Probably because I was bored, Debian is too stable.

Also, I love XMPP. I use this protocol every day to chat with my friends. This is why I have been hosting a Prosody server for a while now. And while we are making the presentations, let me not introduce, because you already know him: Gajim.

This article will guide you through the process of deploying a Prosody XMPP server using Docker Compose. Thanks to it, you will be able to chat securely with all of your friends using a mature communication protocol. I will not cover all the DNS configuration, but if you need guidance for it and you read French, I’d recommend Installer son serveur XMPP avec Prosody from a friend of mine. I am still covering the TLS part (using Let’s Encrypt) so bear with me, we are starting.

The Compose directory

We will be using the official Prosody Docker image and start from the docker-compose.yml example available in the official documentation.

Remember, you can also consult my Docker Stack at any time directly on my VCS vcs.gsvd.dev/gsvd/stacks (in case the example below may be outdated).

my-docker-stack/
├── some-application/
└── prosody/
    ├── hooks/
    │   └── deploy.sh
    ├── config/
    │   ├── conf.d/
    │   │   └── example.com.cfg.lua
    │   └── prosody.cfg.lua
    └── compose.yml

Compose file

We’ll need TLS certificates for our Virtual Host. You can either choose to manage them on your host machine or use the certbot Docker image. I’ll be covering the second option, but both are nearly identical: the most important thing is the deploy hook so you can just extract it.

compose.yml

You will need to accept incoming connections on port 80 (host machine) for certbot’s HTTP-01 challenge.

services:
  prosody:
    image: prosodyim/prosody:13.0
    pull_policy: always
    restart: unless-stopped
    ports:
      - 5222:5222 # C2S STARTTLS
      - 5269:5269 # S2S STARTTLS
      - 5281:5281 # HTTPS
      - 5000:5000 # File transfer proxy
    volumes:
      - ./config:/etc/prosody
      - certs:/etc/prosody/certs
      - data:/var/lib/prosody
    depends_on:
      certbot:
        condition: service_healthy

  certbot:
    image: certbot/certbot
    restart: unless-stopped
    volumes:
      - certs:/etc/letsencrypt
      - ./hooks/deploy.sh:/etc/letsencrypt/renewal-hooks/deploy/prosody.sh:ro
    ports:
      - "80:80"
    entrypoint:
      - /bin/sh
      - -c
      - |
        set -e
        certbot certonly --standalone \
          --agree-tos --non-interactive --keep-until-expiring \
          --email me@example.com \
          -d example.com \
          -d p.example.com \
          -d u.example.com \
          -d c.example.com
        echo '0 3 * * * certbot renew --quiet' | crontab -
        crond -f -d 8
    healthcheck:
      test: ["CMD", "test", "-f", "/etc/letsencrypt/live/example.com/fullchain.pem"]
      interval: 10s
      timeout: 5s
      retries: 30
      start_period: 5s

volumes:
  certs:
  data:

deploy.sh

You can see that we use a Docker volume named certs for both certbot and Prosody. But since they don’t follow the same path pattern (plus Let’s Encrypt symlinks), we have to make some copy-pasta to make it work.

As I was saying, this deploy hook is also valid on your host machine (you can maybe just adapt the paths a little).

#!/bin/sh

mkdir -p /etc/letsencrypt/example.com
cp /etc/letsencrypt/live/example.com/fullchain.pem /etc/letsencrypt/example.com/
cp /etc/letsencrypt/live/example.com/privkey.pem /etc/letsencrypt/example.com/
chmod 644 /etc/letsencrypt/example.com/fullchain.pem
chmod 640 /etc/letsencrypt/example.com/privkey.pem
chown 100:102 /etc/letsencrypt/example.com/fullchain.pem
chown 100:102 /etc/letsencrypt/example.com/privkey.pem

Let’s take some perspective on this hook:

You are probably wondering why we are doing a chown 100:102, because it’s the UID and GID used by the Prosody image. You can double check at any time using docker run --rm --entrypoint id prosodyim/prosody:13.0 prosody.
The script will be mounted into /etc/letsencrypt/renewal-hooks/deploy and will automatically be picked up by certbot after each generation and renewal.
Because it’s always better to visualize things, here is a quick diagram to explain how and why this hook exists: click to open

Common troubleshooting

If you already have a web server listening on port 80 you can change the one used by certbot to something else, for example 61248:80, and redirect using a reverse proxy. This Nginx example will redirect the HTTP-01 challenge to the right port used by certbot in Docker.

server {
    listen 80;
    server_name example.com p.example.com u.example.com c.example.com;

    location /.well-known/acme-challenge/ {
        proxy_pass http://127.0.0.1:61248;
    }

    # You can still serve anything you want here.
    # For example, I host my own OMEMO public keys here.
    # It's useful if you have paranoid friends, for this example 404 will be enough.
    location / {
        return 404;
    }
}

Prosody configuration

prosody.cfg.lua

modules_enabled = {
    "adhoc", "admin_adhoc", "admin_shell", "announce",
    "blocklist", "bookmarks", "bosh", "carbons",
    "cloud_notify", "csi_simple", "dialback", "disco",
    "mam", "mimicking", "offline", "pep",
    "ping", "private", "register", "roster",
    "s2s_bidi", "saslauth", "smacks", "time",
    "tls", "tombstones", "uptime", "vcard_legacy",
    "version", "watchregistrations", "websocket", "welcome",
}

allow_registration = false
authentication = "internal_hashed"

c2s_require_encryption = true
s2s_require_encryption = true
s2s_secure_auth = true

pep_max_items = 12800
archive_expires_after = "3w"

log = {
    "*console";
}

Include "conf.d/*.cfg.lua"

example.com.cfg.lua

You may want to take a few minutes to check the security options I provide, I highly recommend ssl-config.mozilla.org. We are using sqlite, but you can change it to postgres if you need. It’ll require some adjustments both to the Prosody configuration and compose file (not covering it here).

VirtualHost "example.com"
ssl = {
    key = "/etc/prosody/certs/example.com/privkey.pem",
    certificate = "/etc/prosody/certs/example.com/fullchain.pem",
    ciphers = "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305",
    protocol = "tlsv1_2+",
    curve = "X25519:prime256v1:secp384r1",
    options = {
        "cipher_server_preference",
        "no_compression",
        "no_ticket",
        "single_ecdh_use"
    }
}

authentication = "internal_hashed"
storage = "sql"
sql = { driver = "SQLite3", database = "prosody" }

Component "c.example.com" "muc"
    name = "Rooms"
    restrict_room_creation = "local"
    muc_max_rooms = 64
    muc_room_default_public = false

Component "u.example.com" "http_file_share"
    name = "Files"
    http_file_share_size_limit = 512 * 1024 * 1024       -- 512 MB per file
    http_file_share_daily_quota = 4096 * 1024 * 1024     -- 4 GB per user per day
    http_file_share_expire_after = 60 * 60 * 24 * 14     -- 14 days expire

Component "p.example.com" "proxy65"
    name = "Proxy"
    proxy65_address = "p.example.com"
    proxy65_acl = { "example.com" }

Conclusion

If you’ve done everything right, from DNS to TLS: you can just docker compose up -d. This will generate TLS certificates for your domain and boot your Prosody server.

To start chatting with your friends, create a user docker compose exec prosody prosodyctl adduser my-user@example.com and you’re good to go. You can contact me on XMPP gsvd@gameover.sh, send me a message and tell me if this quick guide helped you!

Also, keep in mind that this article has been written without any help from AI. This is based on my own research and findings, and it describes my own approach to Compose files.

Takeaways

Of course this is not a “production-ready” tutorial. Keep in mind a few things before that:

Backup: everything that needs to be backed up lives in the data volume. Don’t forget to include it in your existing backup flow.
DNS configuration, we didn’t cover it here but this step is straightforward (don’t forget this link or the official documentation).
Tweak the http_file_share_* settings, I have a lot of storage so I’m quite generous.
Once your server is live, join the Prosody IM Chatroom prosody@conference.prosody.im to say hello!
{p,u,c}.example.com subdomains are just my personal naming scheme, I’m pretty sure the convention is {proxy,upload,conference}.example.com.

Host your own password manager with Vaultwarden and Nginx

Thu, 30 Jan 2025 22:47:00 -0500

Introduction

A few years ago, I used Nextcloud a lot, combined with its Passwords app. I can’t say it was a bad user experience, but it wasn’t a good one either. Later, I dropped Nextcloud because I realized that I didn’t need it that much, so I no longer had a password manager (yes, I know, it’s bad, but who cares?).

Now that I’m in a new phase of trying and hosting things, I wanted to give Vaultwarden a try. And you know what? I loved it so much that I started writing this little blog post about it, because it deserves it, and I really want you to give it a chance.

I must admit that I’m not a big fan of containers. While I can’t say I like Podman, I don’t dislike it as much as Docker. So when I read Vaultwarden’s installation documentation and saw “You can replace Docker with Podman if you prefer to use Podman.” it really appealed to me.

Well, enough talking! Let’s get into what we like…

Requirements

Oh yes, big announcement: I’m no longer into Raspberry Pi since my last post. So here’s the setup I have and will assume you have for the technical parts. The versions don’t have to be exactly the same, we don’t really care, and anyway, if it causes an issue, you’ll find out soon enough.

Note that at the time of writing, the current version of Vaultwarden is 1.33.0.

Debian 12
Nginx 1.22.1 (we’ll be using a reverse proxy)
Certbot 2.1.0 (because in HTTPS we trust — though you probably shouldn’t). While I won’t explain this step, I still recommend setting it up on your own.
Podman 4.3.1 (don’t forget that you can easily replace it by Docker)

Run Vaultwarden using Podman

We will be using the /vw-data directory, so make sure to create it first and ensure you have the proper user permissions on it (root or whatever works for you). Feel free to adapt the command below.

podman run --detach \
    --name vaultwarden \
    --env DOMAIN="https://example.com" \
    --env ADMIN_TOKEN="SOME_RANDOM_STRING" \
    --volume /vw-data/:/data/ \
    --restart unless-stopped \
    --publish 127.0.0.1:8080:80 \
    docker.io/vaultwarden/server:latest

Don’t worry, thanks to the --restart unless-stopped parameter, it will always be up, even after a reboot.
The ADMIN_TOKEN will allow you to access the admin backend at https://example.com/admin.

Nginx reverse proxy

This is an HTTP configuration. If you plan to expose it to the web, you should really add an HTTPS configuration.

server {
    listen 80;
    listen [::]:80;

    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

Add this configuration in your /etc/nginx/sites-available directory then enable it:

sudo nano /etc/nginx/sites-available/example.com
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled
sudo nginx -t
sudo systemctl reload nginx

From here you can try to access to http://example.com/ — it should work.

Don’t forget to check out http://example.com/admin as well, using your ADMIN_TOKEN from the previous step.

Create a seedbox on Raspberry Pi using the latest version of qbittorrent

Mon, 06 Nov 2023 21:34:00 -0500

Introduction

A seedbox is a dedicated, high-speed server for downloading and uploading files. Most commonly used in the context of torrenting, a seedbox provides many benefits over using a personal computer for the same tasks.

Throughout my experiences with various torrent clients, qBittorrent has consistently stood out for its comprehensive features. However, as of the time of writing, the only version of qbittorrent-nox available for Raspbian is somewhat outdated (4.1.5). Compiling from source can be a daunting task, so thankfully, qbittorrent-nox-static provides a convenient solution.

User creation

Let’s begin by creating a user specifically for running qBittorrent securely. This step is straightforward:

adduser qbittorrent

Download binaries

The following steps can be found in the qbittorrent-nox-static documentation. Ensure you execute these commands while logged in as the newly created user.

mkdir -p ~/bin && source ~/.profile
wget -qO ~/bin/qbittorrent-nox https://github.com/userdocs/qbittorrent-nox-static/releases/latest/download/armv7-qbittorrent-nox
chmod 700 ~/bin/qbittorrent-nox

Next, launch qBittorrent to initialize the configuration files, then terminate the process.

~/bin/qbittorrent-nox

qBittorrent port configuration

Edit the configuration file by running:

nano ~/.config/qBittorrent/qBittorrent.conf

You’ll find many settings here, but we’ll focus on the essential ones. Locate the following line and set your desired port:

Session\Port=65530

Service creation

Execute the next commands as the root user or with sudo privileges.

nano /etc/systemd/system/qbittorrent.service

Copy, paste, and modify the content below as needed:

[Unit]
Description=qBittorrent-nox service
Documentation=man:qbittorrent-nox(1)
Wants=network-online.target
After=network-online.target nss-lookup.target

[Service]
Type=exec
User=qbittorrent
ExecStart=/home/qbittorrent/bin/qbittorrent-nox

[Install]
WantedBy=multi-user.target

Then, remember to enable, start, and check the service’s status:

systemctl enable qbittorrent
systemctl start qbittorrent
systemctl status qbittorrent

Firewall (using UFW)

Allow the necessary ports through the firewall, when the Nginx reverse proxy is configured, you can remove port 8080 from your authorisations:

ufw allow 8080/tcp comment 'qBittorrent WebUI'
ufw allow 65530/tcp comment 'libTorrent'

Router port redirection

Here’s a brief reminder: ensure that your server is configured with a static IP and that port forwarding is functioning correctly.

Access to web interface

The web interface should now be accessible. Navigate to http://<your-ip>:8080 in your web browser. The default credentials are admin/adminadmin.

Immediately change the default login details:

Nginx configuration

We will briefly discuss setting up a virtual host (vhost). Detailed guides on installing Nginx, generating SSL certificates, and DNS configuration are available online, so we won’t cover those here.

However, ensure you’ve configured HTTPS before exposing your web interface to the internet.

nano /etc/nginx/sites-available/qbittorrent.conf

Copy, paste, and modify the content below as needed:

server {
  listen 80 http2;
  listen [::]:80 http2;

  server_name example.com;

  location / {
    proxy_pass              http://127.0.0.1:8080;
    proxy_set_header        X-Forwarded-Host        $server_name:$server_port;
    proxy_set_header        X-Forwarded-Host        $http_host;
    proxy_set_header        X-Forwarded-For         $remote_addr;
  }
}

Don’t forget to enable this Nginx configuration:

ln -s /etc/nginx/sites-available/qbittorrent.conf /etc/nginx/sites-enabled

Going further

Here are some additional considerations for future exploration:

Mounting external storage to save downloaded files. Configure qBittorrent to save to specific directories and move files upon completion.
Install Jellyfin to create a personal media center.
Setting up a VPN, like PiVPN, to access your seedbox from anywhere without using Nginx.
Securing your server with fail2ban.
Implementing an alternative WebUI.
Torrenting more safely by setting up proxy usage.

Conclusion

Setting up a seedbox on a Raspberry Pi with the latest version of qBittorrent can seem like a technical venture, but it offers a great way to enhance your torrenting experience with added control, efficiency, and privacy. This guide aimed to provide you with a clear path to getting your own seedbox up and running, from installing qBittorrent to configuring your system for remote access.

With your new setup, not only can you manage your downloads more effectively, but you also have a foundation to build upon. Whether you plan to expand your server’s capabilities, explore media streaming options or further secure your system, the steps provided here give you a solid start. Remember, the key to a successful seedbox is not just in its creation but also in its maintenance and security.

I hope this tutorial has been helpful, and I encourage you to share your experiences, ask questions, and provide feedback. The DIY spirit of the Raspberry Pi community thrives on shared knowledge and collaboration, so don’t hesitate to contribute your own findings.

Happy torrenting!