Skip to content
This repository was archived by the owner on Dec 30, 2025. It is now read-only.

Commit c94d100

Browse files
kzndotshkzndotsh
committed
enhance(README, Makefile, SSL.md): improve SSL management documentation and add new commands
This commit updates the README.md and SSL.md files to enhance the clarity and usability of SSL management instructions. It introduces new commands in the Makefile for stopping and cleaning SSL monitoring, along with safety prompts for critical operations. The documentation now includes advanced usage, debugging options, and a comprehensive command reference, ensuring users have clear guidance on managing SSL certificates effectively within the IRC infrastructure.
1 parent 74ddd8c commit c94d100

File tree

3 files changed

+336
-85
lines changed

3 files changed

+336
-85
lines changed

‎Makefile‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,10 @@ help:
3131
@echo "SSL MANAGEMENT:"
3232
@echo " make ssl-setup - One-command SSL setup"
3333
@echo " make ssl-status - Check SSL status"
34+
@echo " make ssl-renew - Force certificate renewal"
3435
@echo " make ssl-logs - View SSL logs"
36+
@echo " make ssl-stop - Stop SSL monitoring"
37+
@echo " make ssl-clean - Remove SSL certificates (CAUTION!)"
3538
@echo ""
3639
@echo "MAINTENANCE:"
3740
@echo " make clean - Clean containers and images"
@@ -229,7 +232,7 @@ info: ## Show system information
229232
ssl-setup: ## One-command SSL setup - sets up everything automatically
230233
@echo -e "$(PURPLE)=== SSL Setup - One Command to Rule Them All ===$(NC)"
231234
@echo -e "$(BLUE)[INFO]$(NC) This will:"
232-
@echo -e "$(BLUE)[INFO]$(NC) 1. Issue SSL certificates for $(IRC_ROOT_DOMAIN)"
235+
@echo -e "$(BLUE)[INFO]$(NC) 1. Issue SSL certificates for your domain"
233236
@echo -e "$(BLUE)[INFO]$(NC) 2. Start automatic Docker monitoring"
234237
@echo -e "$(BLUE)[INFO]$(NC) 3. Configure daily renewal at 2 AM"
235238
@echo ""
@@ -252,12 +255,35 @@ ssl-status: ## Check SSL certificate status
252255

253256
ssl-renew: ## Force certificate renewal
254257
@echo -e "$(PURPLE)=== Forcing SSL Certificate Renewal ===$(NC)"
255-
@./scripts/ssl-manager.sh renew
258+
@if [[ -f "unrealircd/conf/tls/server.cert.pem" ]]; then \
259+
./scripts/ssl-manager.sh renew; \
260+
else \
261+
echo -e "$(YELLOW)[WARNING]$(NC) No SSL certificates found. Run 'make ssl-setup' first."; \
262+
fi
256263

257264
ssl-logs: ## View SSL monitoring logs
258265
@echo -e "$(PURPLE)=== SSL Monitoring Logs ===$(NC)"
259266
@docker compose logs -f ssl-monitor --tail=50
260267

268+
ssl-stop: ## Stop SSL monitoring
269+
@echo -e "$(PURPLE)=== Stopping SSL Monitoring ===$(NC)"
270+
@docker compose down ssl-monitor
271+
@echo -e "$(GREEN)[SUCCESS]$(NC) SSL monitoring stopped"
272+
273+
ssl-clean: ## Remove SSL certificates and monitoring (CAUTION: destroys certificates!)
274+
@echo -e "$(RED)=== WARNING: This will DELETE your SSL certificates! ===$(NC)"
275+
@echo -e "$(YELLOW)This action cannot be undone.$(NC)"
276+
@echo ""
277+
@read -p "Are you sure you want to continue? (type 'yes' to confirm): " confirm && \
278+
if [[ "$$confirm" == "yes" ]]; then \
279+
echo -e "$(BLUE)[INFO]$(NC) Removing SSL certificates..."; \
280+
rm -rf data/letsencrypt unrealircd/conf/tls; \
281+
docker compose down ssl-monitor; \
282+
echo -e "$(GREEN)[SUCCESS]$(NC) SSL certificates and monitoring removed."; \
283+
else \
284+
echo -e "$(YELLOW)[CANCELLED]$(NC) SSL cleanup cancelled."; \
285+
fi
286+
261287
# ============================================================================
262288
# UTILITIES
263289
# ============================================================================

‎README.md‎

Lines changed: 93 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# IRC.atl.chat - Complete IRC Infrastructure
22

3-
A **production-ready IRC server ecosystem** featuring UnrealIRCd with Atheme Services, automated SSL/TLS, and modern containerization.
3+
A **production-ready IRC server ecosystem** with UnrealIRCd, Atheme Services, automated SSL certificates, and containerized deployment.
44

5-
## 🏗️ **Core Components**
5+
## Core Components
66

77
| Component | Technology | Purpose |
88
|-----------|------------|---------|
@@ -12,15 +12,15 @@ A **production-ready IRC server ecosystem** featuring UnrealIRCd with Atheme Ser
1212
| **SSL/TLS** | Let's Encrypt + Cloudflare | Automated certificate management |
1313
| **Container** | Docker + Compose | Deployment and orchestration |
1414

15-
### 🔄 **Services Integration**
15+
### Services Integration
1616

17-
The setup includes **full IRC services integration**:
17+
The setup includes **complete IRC services integration**:
1818
- **NickServ**: Nickname registration and authentication
1919
- **ChanServ**: Channel management and protection
2020
- **OperServ**: Administrative services
2121
- **Server linking**: Seamless integration between IRCd and Services
2222

23-
## 🚀 **Quick Start**
23+
## Quick Start
2424

2525
### **4-Step Setup**
2626
```bash
@@ -39,15 +39,15 @@ vim .env
3939
make build && make up
4040
```
4141

42-
### **What's Included**
43-
✅ **UnrealIRCd IRC Server** - Modern IRC daemon
44-
✅ **Atheme Services** - NickServ, ChanServ, OperServ
45-
✅ **WebPanel Admin Interface** - Browser-based management
46-
✅ **Automated SSL/TLS** - Let's Encrypt with Docker monitoring
47-
✅ **Health Monitoring** - Automated service checks
48-
✅ **Persistent Storage** - Data survives container restarts
42+
### What's Included
43+
- **UnrealIRCd IRC Server** - Modern IRC daemon
44+
- **Atheme Services** - NickServ, ChanServ, OperServ
45+
- **WebPanel Admin Interface** - Browser-based management
46+
- **Automated SSL certificates** - Let's Encrypt with monitoring
47+
- **Health monitoring** - Automated service checks
48+
- **Persistent storage** - Data survives container restarts
4949

50-
## ⚙️ **Configuration**
50+
## Configuration
5151

5252
### **Environment Variables**
5353

@@ -113,7 +113,7 @@ ATHEME_SEND_PASSWORD=your-services-password
113113
ATHEME_RECEIVE_PASSWORD=your-services-password
114114
```
115115

116-
## 🔧 **Management Commands**
116+
## Management Commands
117117

118118
### **Core Commands**
119119
```bash
@@ -136,9 +136,12 @@ make logs-atheme # Services logs
136136
make logs-webpanel # WebPanel logs
137137

138138
# SSL management
139-
make ssl-setup # Setup SSL certificates
140-
make ssl-status # Check SSL status
139+
make ssl-setup # Complete SSL setup with monitoring
140+
make ssl-status # Check SSL certificate status
141+
make ssl-renew # Force certificate renewal (with safety checks)
141142
make ssl-logs # View SSL monitoring logs
143+
make ssl-stop # Stop SSL monitoring container
144+
make ssl-clean # Remove certificates and monitoring (CAUTION!)
142145

143146
# Maintenance
144147
make clean # Clean containers and images
@@ -154,36 +157,64 @@ make generate-password
154157
./scripts/prepare-config.sh
155158
```
156159

157-
## 🔐 **SSL/TLS Setup**
160+
## SSL/TLS Setup
158161

159162
### **Automated SSL with Let's Encrypt**
160163

161-
The setup includes **completely automated SSL certificate management**:
164+
The setup includes **robust SSL certificate management** with comprehensive features:
162165

163166
```bash
164167
# One-command SSL setup
165168
make ssl-setup
169+
170+
# Advanced troubleshooting and debugging
171+
./scripts/ssl-manager.sh --verbose check # Detailed status
172+
./scripts/ssl-manager.sh --debug issue # Maximum debugging
173+
./scripts/ssl-manager.sh --help # Complete help
166174
```
167175

168-
### **What Happens Automatically**
169-
✅ **Certificate Issuance**: Let's Encrypt with Cloudflare DNS challenges
170-
✅ **Automatic Renewal**: Every day at 2 AM (no manual intervention)
171-
✅ **Docker Monitoring**: 24/7 certificate health monitoring
172-
✅ **Service Restart**: Automatic restart after certificate renewal
176+
### What Happens Automatically
177+
- **Certificate Issuance**: Let's Encrypt with Cloudflare DNS challenges
178+
- **Automatic Renewal**: Every day at 2 AM (no manual intervention)
179+
- **Docker Monitoring**: 24/7 certificate health monitoring
180+
- **Comprehensive Logging**: 5-level logging (INFO/WARN/ERROR/DEBUG/VERBOSE)
181+
- **Safety Features**: Confirmation prompts for dangerous operations
182+
- **Input Validation**: Domain and email format checking
183+
- **Service Restart**: Automatic restart after certificate renewal
173184

174185
### **Prerequisites**
175186
1. **Cloudflare Account** with DNS hosting for your domain
176187
2. **API Token** from https://dash.cloudflare.com/profile/api-tokens
177188
- Create token with **Zone:DNS:Edit** permissions for your domain
178189
3. **Domain Configuration** pointing to your server
179190

180-
### **SSL Status & Monitoring**
191+
### SSL Status & Monitoring
181192
```bash
182193
# Check SSL certificate status
183194
make ssl-status
184195

185196
# View SSL monitoring logs
186197
make ssl-logs
198+
199+
# Advanced SSL operations
200+
make ssl-renew # Force renewal (with safety checks)
201+
make ssl-stop # Stop monitoring container
202+
make ssl-clean # Remove certificates (CAUTION!)
203+
```
204+
205+
### SSL Debugging & Troubleshooting
206+
```bash
207+
# Get comprehensive help
208+
./scripts/ssl-manager.sh --help
209+
210+
# Verbose output for detailed information
211+
./scripts/ssl-manager.sh --verbose check
212+
213+
# Maximum debugging for troubleshooting
214+
./scripts/ssl-manager.sh --debug issue
215+
216+
# Manual certificate verification
217+
openssl x509 -in unrealircd/conf/tls/server.cert.pem -noout -enddate
187218
```
188219

189220
### **Security Features**
@@ -195,7 +226,7 @@ make ssl-logs
195226
- **Secrets management** via environment variables
196227
- **Production-optimized Atheme build** following official documentation recommendations
197228

198-
## 📊 **Ports and Services**
229+
## Ports and Services
199230

200231
| Port | Protocol | Service | Purpose |
201232
|------|----------|---------|---------|
@@ -204,28 +235,28 @@ make ssl-logs
204235
| **6900** | IRC+TLS | UnrealIRCd | Server-to-server links |
205236
| **8080** | HTTP | WebPanel | Admin interface |
206237

207-
## 📁 **Project Structure**
238+
## Project Structure
208239

209240
```
210241
irc.atl.chat/
211-
├── 📄 compose.yaml # Docker Compose configuration
212-
├── 🐳 Containerfile # Docker build instructions
213-
├── ⚙️ .env # Environment variables (gitignored)
214-
├── 🔐 cloudflare-credentials.ini # Cloudflare API credentials
215-
├── 📜 scripts/ # Management scripts
216-
│ ├── ssl-manager.sh # SSL certificate management
217-
│ ├── prepare-config.sh # Configuration preparation
218-
│ └── health-check.sh # Health monitoring
219-
├── 📁 unrealircd/ # IRC server configuration
220-
│ └── conf/ # Configuration files
221-
├── 🎭 services/atheme/ # Services configuration
222-
├── 🌐 web/webpanel/ # WebPanel container
223-
├── 📊 logs/ # Service logs
224-
├── 📁 data/ # Persistent data
225-
└── 📝 Makefile # Management commands
242+
├── compose.yaml # Docker Compose configuration
243+
├── Containerfile # Docker build instructions
244+
├── .env # Environment variables (gitignored)
245+
├── cloudflare-credentials.ini # Cloudflare API credentials
246+
├── scripts/ # Management scripts
247+
│ ├── ssl-manager.sh # SSL management (--help, --debug, --verbose)
248+
│ ├── prepare-config.sh # Configuration preparation
249+
│ └── health-check.sh # Health monitoring
250+
├── unrealircd/ # IRC server configuration
251+
│ └── conf/ # Configuration files
252+
├── services/atheme/ # Services configuration
253+
├── web/webpanel/ # WebPanel container
254+
├── logs/ # Service logs
255+
├── data/ # Persistent data
256+
└── Makefile # Management commands
226257
```
227258

228-
## 🎯 **Using Your IRC Server**
259+
## Using Your IRC Server
229260

230261
### **Connect to IRC**
231262
```bash
@@ -247,7 +278,7 @@ Once connected, you have access to:
247278
- **ChanServ**: `/msg ChanServ REGISTER #channel`
248279
- **OperServ**: Administrative services (for IRC operators)
249280

250-
## 🐛 **Troubleshooting**
281+
## Troubleshooting
251282

252283
### **Services Not Starting**
253284
```bash
@@ -265,6 +296,16 @@ make ssl-status
265296

266297
# View SSL monitoring logs
267298
make ssl-logs
299+
300+
# Advanced SSL debugging
301+
./scripts/ssl-manager.sh --verbose check # Detailed status
302+
./scripts/ssl-manager.sh --debug issue # Maximum debugging
303+
304+
# Manual certificate verification
305+
openssl x509 -in unrealircd/conf/tls/server.cert.pem -noout -enddate
306+
307+
# Check SSL monitoring container
308+
docker compose ps ssl-monitor
268309
```
269310

270311
### **Configuration Issues**
@@ -276,23 +317,25 @@ make ssl-logs
276317
make restart
277318
```
278319

279-
## 📚 **Additional Resources**
320+
## Additional Resources
280321

322+
- [SSL Setup Documentation](./docs/SSL.md) - Complete SSL management guide
281323
- [UnrealIRCd Documentation](https://www.unrealircd.org/docs/)
282324
- [Atheme Services Documentation](https://atheme.dev/docs/)
283325
- [Docker Compose Documentation](https://docs.docker.com/compose/)
284326

285327
---
286328

287-
## 🚀 **Ready to Get Started?**
329+
## Ready to Get Started?
288330

289331
Your **production-ready IRC infrastructure** is now fully configured with:
290332

291-
✅ **Complete IRC ecosystem** - Server + Services + Web interface
292-
✅ **Automated SSL/TLS** - Let's Encrypt with Docker monitoring
293-
✅ **Simple management** - One-command operations
294-
✅ **Production security** - Argon2id password hashing
295-
✅ **Containerized deployment** - Easy scaling and updates
333+
- **Complete IRC ecosystem** - Server + Services + Web interface
334+
- **SSL/TLS certificates** - Let's Encrypt with monitoring & debugging
335+
- **Full management** - Complete set of make targets for control
336+
- **Production security** - Argon2id password hashing, secure secrets management
337+
- **Containerized deployment** - Easy scaling and updates
338+
- **Troubleshooting tools** - Debug/verbose modes, comprehensive logging
296339

297340
**Start your IRC network:**
298341
```bash
@@ -303,7 +346,3 @@ make build && make up
303346
- **IRC Server**: `irc.atl.chat:6667` (standard) or `:6697` (SSL)
304347
- **WebPanel**: `http://your-server:8080`
305348
- **Services**: Available once connected to IRC
306-
307-
---
308-
309-
*Happy IRCing! 🎉*

0 commit comments

Comments
 (0)