Skip to content

Commit f41990e

Browse files
mbolognambologna
committed
docs: update README
1 parent 73fd8cc commit f41990e

1 file changed

Lines changed: 229 additions & 45 deletions

File tree

‎README.md‎

100755100644
Lines changed: 229 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,265 @@
1-
# BitlBee with additional plugins in a container
1+
# BitlBee Docker Container
22

3-
![Docker](https://img.shields.io/docker/pulls/mbologna/docker-bitlbee)
4-
![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mbologna/docker-bitlbee/build-scan-push.yml?branch=master)
3+
[![Docker Pulls](https://img.shields.io/docker/pulls/mbologna/docker-bitlbee)](https://hub.docker.com/r/mbologna/docker-bitlbee)
4+
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mbologna/docker-bitlbee/build-scan-push.yml?branch=master)](https://github.com/mbologna/docker-bitlbee/actions)
5+
[![Docker Image Size](https://img.shields.io/docker/image-size/mbologna/docker-bitlbee/latest)](https://hub.docker.com/r/mbologna/docker-bitlbee)
6+
[![License](https://img.shields.io/github/license/mbologna/docker-bitlbee)](LICENSE)
57

6-
This repository provides a Docker-based setup for running [Bitlbee](https://www.bitlbee.org/) with additional plugins for extended functionality and an optional [Stunnel](https://www.stunnel.org/) service to enable secure IRC communications over TLS.
8+
A Docker container for [BitlBee](https://www.bitlbee.org/) - the IRC gateway to instant messaging networks. This container includes extensive plugin support and optional TLS encryption via Stunnel.
79

8-
## Features
10+
## ✨ Features
911

10-
- **[Bitlbee](https://www.bitlbee.org)**: A popular gateway that connects instant messaging services with IRC. In addition to the [Bitlbee's out of the box supported protocols](https://wiki.bitlbee.org/), these are the pre-installed plugins:
11-
- Discord via [purple-discord](https://github.com/EionRobb/purple-discord)
12-
- Matrix via [purple-matrix](https://github.com/matrix-org/purple-matrix)
13-
- Microsoft Teams via [teams](https://github.com/EionRobb/purple-teams)
14-
- Slack via [slack-libpurple](https://github.com/dylex/slack-libpurple)
15-
- Facebook (MQTT) via [bitlbee-facebook](https://github.com/bitlbee/bitlbee-facebook)
16-
- Telegram via [tdlib-purple](https://github.com/BenWiederhake/)
17-
- WhatsApp via [purple-gowhatsapp](https://github.com/hoehermann/purple-gowhatsapp)
18-
- **[Stunnel](https://www.stunnel.org/)**: Adds TLS encryption for secure IRC connections.
19-
- Multi-architecture support: builds for `linux/amd64` and `linux/arm64`.
20-
- Kubernetes resources included for deployment in containerized environments.
21-
- Linting and security scans integrated into CI/CD workflows.
12+
### Core Components
2213

23-
## Quick Start
14+
- **[BitlBee](https://www.bitlbee.org)** - IRC gateway for instant messaging
15+
- **[Stunnel](https://www.stunnel.org/)** - TLS/SSL encryption wrapper (optional)
2416

25-
### Requirements
17+
### Supported Protocols
2618

27-
* `/var/lib/bitlbee` must be writable by UID `<bitlbee_uid>`
19+
In addition to BitlBee's [built-in protocols](https://wiki.bitlbee.org/) (Jabber/XMPP, Oscar/AIM, MSN, Twitter, etc.), this container includes:
2820

29-
### Docker
21+
| Protocol | Plugin | Repository |
22+
|----------|--------|------------|
23+
| Discord | purple-discord | [EionRobb/purple-discord](https://github.com/EionRobb/purple-discord) |
24+
| Matrix | purple-matrix | [matrix-org/purple-matrix](https://github.com/matrix-org/purple-matrix) |
25+
| Microsoft Teams | purple-teams | [EionRobb/purple-teams](https://github.com/EionRobb/purple-teams) |
26+
| Slack | slack-libpurple | [dylex/slack-libpurple](https://github.com/dylex/slack-libpurple) |
27+
| Facebook (MQTT) | bitlbee-facebook | [bitlbee/bitlbee-facebook](https://github.com/bitlbee/bitlbee-facebook) |
28+
| Telegram | tdlib-purple | [BenWiederhake/tdlib-purple](https://github.com/BenWiederhake/tdlib-purple) |
29+
| WhatsApp | purple-whatsmeow | [hoehermann/purple-gowhatsapp](https://github.com/hoehermann/purple-gowhatsapp) |
3030

31-
```
31+
### Technical Features
32+
33+
- 🏗️ Multi-architecture support: `linux/amd64`, `linux/arm64`
34+
- 🔒 Security-hardened with minimal capabilities
35+
- 📊 Health checks and monitoring ready
36+
- 🚀 Optimized build with layer caching
37+
- 📦 SBOM and provenance attestations
38+
- 🔍 Automated vulnerability scanning
39+
- ☸️ Kubernetes manifests included
40+
41+
## 🚀 Quick Start
42+
43+
### Prerequisites
44+
45+
- Docker 20.10+ or Podman 3.0+
46+
- docker-compose or podman-compose (optional, for orchestration)
47+
48+
### Option 1: Docker Run
49+
50+
```bash
51+
# Create a volume for persistent data
3252
docker volume create bitlbee-data
33-
docker run \
53+
54+
# Run BitlBee
55+
docker run -d \
56+
--name bitlbee \
3457
--user $(id -u):$(id -g) \
58+
-p 6667:6667 \
3559
-v bitlbee-data:/var/lib/bitlbee \
36-
docker-bitlbee
60+
mbologna/docker-bitlbee:latest
3761
```
3862

39-
### Running Locally with Podman or Docker Compose
63+
### Option 2: Docker Compose (Recommended)
4064

41-
1. Clone this repository:
65+
1. **Clone the repository:**
4266
```bash
4367
git clone https://github.com/mbologna/docker-bitlbee.git
4468
cd docker-bitlbee
69+
```
70+
71+
2. **Create environment file:**
72+
```bash
73+
cp .env.example .env
74+
# Edit .env with your preferred settings
75+
```
76+
77+
3. **Start the services:**
78+
```bash
79+
docker-compose up -d
80+
```
81+
82+
4. **Access BitlBee:**
83+
- Plain IRC: `localhost:6667`
84+
- TLS/SSL (via Stunnel): `localhost:16697`
85+
86+
### Option 3: Podman
87+
88+
```bash
89+
# Using podman-compose
90+
podman-compose up -d
4591

46-
2. Build and run the containers:
92+
# Or with podman directly
93+
podman run -d \
94+
--name bitlbee \
95+
--user $(id -u):$(id -g) \
96+
-p 6667:6667 \
97+
-v bitlbee-data:/var/lib/bitlbee \
98+
docker.io/mbologna/docker-bitlbee:latest
99+
```
100+
101+
## ⚙️ Configuration
47102

48-
```
49-
podman-compose up --build
50-
```
103+
### Environment Variables
51104

52-
If you're using Docker:
53-
```
54-
docker-compose up --build
55-
```
105+
Configure the container using a `.env` file or environment variables:
56106

57-
3. Access the Bitlbee service on port 6667 and the Stunnel service on port 16697.
107+
| Variable | Default | Description |
108+
|----------|---------|-------------|
109+
| `UID` | `1000` | User ID for file permissions |
110+
| `GID` | `1000` | Group ID for file permissions |
111+
| `BITLBEE_PORT` | `6667` | BitlBee IRC port |
112+
| `STUNNEL_PORT` | `16697` | Stunnel TLS port |
113+
| `TZ` | `UTC` | Timezone |
58114

59-
#### Environment Variables
115+
**Example `.env` file:**
116+
```env
117+
UID=1000
118+
GID=1000
119+
BITLBEE_PORT=6667
120+
STUNNEL_PORT=16697
121+
TZ=Europe/Rome
122+
```
60123

61-
`UID` and `GID`: Set these to match your local user for proper volume permissions.
124+
### Volume Mounts
62125

63-
#### Persistent Data
126+
The container uses `/var/lib/bitlbee` for persistent data:
127+
- User accounts
128+
- Configuration files
129+
- Plugin settings
64130

65-
The `data/` directory is mounted as a volume to store Bitlbee configurations and data. Ensure it is backed up for persistent setups.
131+
**Important:** Ensure the volume is writable by the user specified in `UID:GID`.
66132

67-
### Kubernetes Deployment
133+
### Custom Configuration
68134

69-
Kubernetes manifests for deploying Bitlbee and Stunnel are located in the `k8s/` directory.
135+
To use a custom BitlBee configuration:
70136

71-
1. Apply the manifests:
137+
```bash
138+
# Create your config
139+
mkdir -p ./data
140+
# Place your bitlbee.conf in ./data
72141

142+
# Mount it
143+
docker run -d \
144+
--name bitlbee \
145+
-v $(pwd)/data:/var/lib/bitlbee \
146+
mbologna/docker-bitlbee:latest
73147
```
74-
kubectl apply -f k8s/
148+
149+
## 🔐 Security
150+
151+
### TLS/SSL Encryption
152+
153+
The included Stunnel service provides encrypted IRC connections:
154+
155+
```bash
156+
# Connect with SSL-enabled IRC client
157+
/server localhost 16697 -ssl
75158
```
76159

77-
Verify deployment:
160+
### Security Features
161+
162+
- ✅ Runs as non-root user
163+
- ✅ Minimal Linux capabilities
164+
- ✅ `no-new-privileges` security option
165+
- ✅ Regular vulnerability scanning
166+
- ✅ SBOM generation for supply chain security
167+
168+
### Health Checks
169+
170+
Built-in health checks monitor service availability:
171+
172+
```bash
173+
# Check container health
174+
docker inspect bitlbee --format='{{.State.Health.Status}}'
175+
176+
# View health check logs
177+
docker inspect bitlbee --format='{{json .State.Health}}' | jq
78178
```
179+
180+
## 📊 Monitoring
181+
182+
### Logs
183+
184+
```bash
185+
# View logs
186+
docker-compose logs -f bitlbee
187+
188+
# Follow specific service
189+
docker-compose logs -f stunnel
190+
```
191+
192+
### Resource Usage
193+
194+
```bash
195+
# Check resource consumption
196+
docker stats bitlbee bitlbee-stunnel
197+
```
198+
199+
## 🎮 Using BitlBee
200+
201+
### First-Time Setup
202+
203+
1. **Connect to BitlBee:**
204+
```
205+
/server localhost 6667
206+
```
207+
208+
2. **Register your account:**
209+
```
210+
register <password>
211+
```
212+
213+
3. **Add an account (example: Discord):**
214+
```
215+
account add discord <email> <password>
216+
account discord on
217+
```
218+
219+
4. **Save configuration:**
220+
```
221+
save
222+
```
223+
224+
### Useful Commands
225+
226+
```irc
227+
# List available protocols
228+
account list
229+
230+
# Add account
231+
account add <protocol> <username> <password>
232+
233+
# Enable account
234+
account <id> on
235+
236+
# Join channels
237+
chat add <account> <channel>
238+
239+
# Get help
240+
help
241+
help account
242+
```
243+
244+
### Protocol-Specific Setup
245+
246+
Refer to the individual plugin documentation:
247+
- [Discord setup](https://github.com/EionRobb/purple-discord/wiki)
248+
- [Matrix setup](https://github.com/matrix-org/purple-matrix/blob/master/README.md)
249+
- [Teams setup](https://github.com/EionRobb/purple-teams#usage)
250+
- [WhatsApp setup](https://github.com/hoehermann/purple-gowhatsapp/wiki)
251+
252+
## ☸️ Kubernetes Deployment
253+
254+
Kubernetes manifests are available in the `k8s/` directory:
255+
256+
```bash
257+
# Deploy to Kubernetes
258+
kubectl apply -f k8s/
259+
260+
# Check deployment
79261
kubectl get pods -n bitlbee
262+
263+
# Access logs
264+
kubectl logs -n bitlbee -l app=bitlbee -f
80265
```
81-
Expose the service as needed (e.g., via `NodePort` or `Ingress`).

0 commit comments

Comments
 (0)