This project sets up a Mosquitto instance with Tailscale VPN integration using Docker Compose. It creates a secure, private network connection for your Mosquitto instance using Tailscale.

Prerequisites

Docker and Docker Compose installed on your system
A Tailscale account and auth key (get one from https://login.tailscale.com/admin/authkeys)
Basic understanding of Docker and networking concepts

Project Structure

ts-mosquitto/
├── docker-compose.yml
├── tailscale/
│   ├── tailscale-data/  # Persistent Tailscale state
│   └── config/         # Tailscale configuration files
└── mosquitto/
    └── config/         # mosquitto configuration files

Setup Instructions

Clone the Repository

git clone https://gitea.damconsulting.llc/DAM/ts-mosquitto
cd ts-mosquitto

Create Required Directories
```
mkdir -p tailscale/tailscale-data
```
Configure Tailscale
- Replace {{YOUR_TAILSCALE_AUTHKEY}} in the docker-compose.yml with your actual Tailscale auth key
- Optionally, update the file in tailscale/config/serve.json if you need specific Tailscale serve configurations
  - CAUTION: Changing "${TS_CERT_DOMAIN}:443": false to true will expose the service to the internet
Configure Mosquitto
- A minimal config is provided in /mosquitto/config/mosquitto.conf
- See official documentation for more configuration options (recomended for production)
Start the Services
```
docker compose up -d
```
Wait for Certificate to propagate [~2m]
Connect with your preferred client

Services

mosquitto-ts (Tailscale)

Runs Tailscale VPN client
Image: tailscale/tailscale:latest
Container name: mosquitto-ts
Hostname: mosquitto
Requires NET_ADMIN and SYS_MODULE capabilities
Persists state in ./tailscale/tailscale-data
Uses configuration from ./tailscale/config

mosquitto

Depends on mosquitto-ts service

Usage

After starting the services your service should be available via tailnet at https://mosquitto.{{YOUR_TAILNET_DOMAIN}}.ts.net ie https://mosquitto.tail12345.ts.net/
To manually get the Tailscale IP/hostname of your container:
```
docker logs mosquitto-ts
```
Look for the Tailscale IP address in the logs.

Optional Features

Uncomment and adjust the ports mapping if you need direct access (without Tailscale):
```
ports:
- 1883:1883
- 8883:8883
```
Stopping the Services
```
docker compose down
```

Troubleshooting

Check container logs:

docker logs mosquitto-ts
docker logs mosquitto

Ensure your Tailscale auth key is valid and not expired
Verify the configuration files have proper permissions
Make sure required directories exist before starting

Service Port details

1883 : MQTT, unencrypted, unauthenticated
1884 : MQTT, unencrypted, authenticated
8883 : MQTT, encrypted, unauthenticated
8884 : MQTT, encrypted, client certificate required
8885 : MQTT, encrypted, authenticated
8886 : MQTT, encrypted, unauthenticated
8887 : MQTT, encrypted, server certificate deliberately expired
8080 : MQTT over WebSockets, unencrypted, unauthenticated
8081 : MQTT over WebSockets, encrypted, unauthenticated
8090 : MQTT over WebSockets, unencrypted, authenticated
8091 : MQTT over WebSockets, encrypted, authenticated

Notes

The Mosquitto service uses the Tailscale service's network stack via network_mode: service:mosquitto-ts
Direct port mapping is disabled by default as Tailscale handles the networking
Services restart automatically unless explicitly stopped
For more information:
- Tailscale documentation
- Mosquitto documentation
- Mosquitto repository
- A helpful article