Docker added
This commit is contained in:
326
DOCKER.md
Normal file
326
DOCKER.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# Docker Deployment Guide
|
||||
|
||||
This guide explains how to run WhatsHooked using Docker and Docker Compose.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker installed (version 20.10 or later)
|
||||
- Docker Compose installed (version 1.29 or later)
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Copy the example configuration file:**
|
||||
```bash
|
||||
cp config.example.json config.json
|
||||
```
|
||||
|
||||
2. **Edit the configuration file:**
|
||||
Open `config.json` and update:
|
||||
- WhatsApp phone numbers
|
||||
- Webhook URLs and authentication
|
||||
- Server settings (port, authentication)
|
||||
|
||||
3. **Create required directories:**
|
||||
```bash
|
||||
mkdir -p sessions data/media
|
||||
```
|
||||
|
||||
4. **Build and start the server:**
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
5. **View logs to scan QR code (first run):**
|
||||
```bash
|
||||
docker-compose logs -f whatshooked
|
||||
```
|
||||
Scan the QR code with WhatsApp on your phone to authenticate.
|
||||
|
||||
6. **Check server health:**
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
## Docker Commands
|
||||
|
||||
### Build the image
|
||||
```bash
|
||||
docker-compose build
|
||||
```
|
||||
|
||||
### Start the service
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Stop the service
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### View logs
|
||||
```bash
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### Restart the service
|
||||
```bash
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
### Access the container shell
|
||||
```bash
|
||||
docker-compose exec whatshooked sh
|
||||
```
|
||||
|
||||
## Volume Mounts
|
||||
|
||||
The docker-compose.yml file mounts three important volumes:
|
||||
|
||||
1. **config.json** - Server configuration (read-only)
|
||||
2. **sessions/** - WhatsApp session data (persistent authentication)
|
||||
3. **data/media/** - Downloaded media files
|
||||
|
||||
These volumes ensure your data persists across container restarts.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Port Mapping
|
||||
|
||||
By default, the server runs on port 8080. To change the port:
|
||||
|
||||
**Option 1: Update config.json**
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"port": 9090
|
||||
}
|
||||
}
|
||||
```
|
||||
Then update docker-compose.yml:
|
||||
```yaml
|
||||
ports:
|
||||
- "9090:9090"
|
||||
```
|
||||
|
||||
**Option 2: Map to different host port**
|
||||
```yaml
|
||||
ports:
|
||||
- "3000:8080" # Access via localhost:3000, server still runs on 8080 internally
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
Set authentication in config.json:
|
||||
|
||||
**Option 1: API Key**
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"auth_key": "your-secure-api-key-here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Option 2: Username/Password**
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"username": "admin",
|
||||
"password": "secure-password"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resource Limits
|
||||
|
||||
Uncomment the deploy section in docker-compose.yml to set resource limits:
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1.0'
|
||||
memory: 512M
|
||||
reservations:
|
||||
cpus: '0.25'
|
||||
memory: 128M
|
||||
```
|
||||
|
||||
## QR Code Scanning
|
||||
|
||||
When you first start the server, you'll need to scan a QR code to authenticate with WhatsApp.
|
||||
|
||||
### View QR Code in Logs
|
||||
```bash
|
||||
docker-compose logs -f whatshooked
|
||||
```
|
||||
|
||||
The QR code will be displayed in ASCII art in the terminal. Scan it with WhatsApp on your phone:
|
||||
1. Open WhatsApp
|
||||
2. Go to Settings > Linked Devices
|
||||
3. Tap "Link a Device"
|
||||
4. Scan the QR code from the terminal
|
||||
|
||||
### Alternative: Use CLI Tool
|
||||
|
||||
You can also use the CLI tool outside Docker to link accounts, then mount the session:
|
||||
```bash
|
||||
./bin/whatshook-cli accounts add
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container won't start
|
||||
Check logs for errors:
|
||||
```bash
|
||||
docker-compose logs
|
||||
```
|
||||
|
||||
### Config file not found
|
||||
Ensure config.json exists in the project root:
|
||||
```bash
|
||||
ls -la config.json
|
||||
```
|
||||
|
||||
### Permission issues with volumes
|
||||
Fix ownership of mounted directories:
|
||||
```bash
|
||||
sudo chown -R $(id -u):$(id -g) sessions data
|
||||
```
|
||||
|
||||
### QR code not displaying
|
||||
Ensure `show_qr: true` is set in config.json:
|
||||
```json
|
||||
{
|
||||
"whatsapp": [
|
||||
{
|
||||
"show_qr": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Cannot connect to server
|
||||
Check if the container is running:
|
||||
```bash
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
Check health status:
|
||||
```bash
|
||||
docker inspect whatshooked-server | grep -A 10 Health
|
||||
```
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
1. **Use secrets for sensitive data:**
|
||||
- Don't commit config.json with real credentials
|
||||
- Use Docker secrets or environment variables
|
||||
- Enable authentication (auth_key or username/password)
|
||||
|
||||
2. **Use HTTPS:**
|
||||
- Put the server behind a reverse proxy (nginx, Traefik, Caddy)
|
||||
- Enable SSL/TLS certificates
|
||||
- Update webhook base_url to use https://
|
||||
|
||||
3. **Network isolation:**
|
||||
- Use Docker networks to isolate the service
|
||||
- Only expose necessary ports
|
||||
- Consider using a VPN for webhook endpoints
|
||||
|
||||
4. **Regular backups:**
|
||||
- Backup the sessions/ directory regularly
|
||||
- Backup config.json (securely)
|
||||
- Backup media files if needed
|
||||
|
||||
### Example with Reverse Proxy (nginx)
|
||||
|
||||
Create a network:
|
||||
```bash
|
||||
docker network create whatshooked-net
|
||||
```
|
||||
|
||||
Update docker-compose.yml:
|
||||
```yaml
|
||||
services:
|
||||
whatshooked:
|
||||
networks:
|
||||
- whatshooked-net
|
||||
# Don't expose ports to host, only to network
|
||||
# ports:
|
||||
# - "8080:8080"
|
||||
|
||||
networks:
|
||||
whatshooked-net:
|
||||
external: true
|
||||
```
|
||||
|
||||
Configure nginx to proxy to the container:
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name whatshooked.yourdomain.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://whatshooked:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health Checks
|
||||
|
||||
The compose file includes a health check that runs every 30 seconds:
|
||||
```bash
|
||||
docker inspect --format='{{.State.Health.Status}}' whatshooked-server
|
||||
```
|
||||
|
||||
### Log Management
|
||||
|
||||
Limit log size to prevent disk space issues:
|
||||
```yaml
|
||||
services:
|
||||
whatshooked:
|
||||
logging:
|
||||
driver: "json-file"
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
```
|
||||
|
||||
## Updates
|
||||
|
||||
To update to the latest version:
|
||||
|
||||
1. Pull latest code:
|
||||
```bash
|
||||
git pull
|
||||
```
|
||||
|
||||
2. Rebuild the image:
|
||||
```bash
|
||||
docker-compose build --no-cache
|
||||
```
|
||||
|
||||
3. Restart the service:
|
||||
```bash
|
||||
docker-compose down
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Multi-Platform Builds
|
||||
|
||||
To build for different architectures (e.g., ARM for Raspberry Pi):
|
||||
|
||||
```bash
|
||||
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t whatshooked:latest .
|
||||
```
|
||||
Reference in New Issue
Block a user