whatshooked/DOCKER.md

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:

   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:

   mkdir -p sessions data/media
   

4. Build and start the server:

   docker-compose up -d
   

5. View logs to scan QR code (first run):

   docker-compose logs -f whatshooked
   

   Scan the QR code with WhatsApp on your phone to authenticate.

6. Check server health:

   curl http://localhost:8080/health
   

Docker Commands

Build the image

docker-compose build

Start the service

docker-compose up -d

Stop the service

docker-compose down

View logs

docker-compose logs -f

Restart the service

docker-compose restart

Access the container shell

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

{
  "server": {
    "port": 9090
  }
}

Then update docker-compose.yml:

ports:
  - "9090:9090"

Option 2: Map to different host port

ports:
  - "3000:8080"  # Access via localhost:3000, server still runs on 8080 internally

Authentication

Set authentication in config.json:

Option 1: API Key

{
  "server": {
    "auth_key": "your-secure-api-key-here"
  }
}

Option 2: Username/Password

{
  "server": {
    "username": "admin",
    "password": "secure-password"
  }
}

Resource Limits

Uncomment the deploy section in docker-compose.yml to set resource limits:

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

docker-compose logs -f whatshooked

The QR code will be displayed in ASCII art in the terminal along with a browser link. You have two options:

Option 1: Scan from Terminal

1. Open WhatsApp
2. Go to Settings > Linked Devices
3. Tap "Link a Device"
4. Scan the QR code from the terminal

Option 2: View in Browser

1. Look for the line: Or open in browser: http://localhost:8080/api/qr/{account_id}
2. Open that URL in your web browser to see a larger PNG image
3. Scan the QR code from your browser

Alternative: Use CLI Tool

You can also use the CLI tool outside Docker to link accounts, then mount the session:

./bin/whatshook-cli accounts add

Using the CLI Inside Docker

The Docker image includes both the server and CLI binaries in the /app/bin directory. You can use the CLI to manage hooks and accounts while the server is running.

Available CLI Commands

List all hooks:

docker exec whatshooked-server /app/bin/whatshook-cli --server http://localhost:8080 hooks list

Add a new hook:

docker exec -it whatshooked-server /app/bin/whatshook-cli --server http://localhost:8080 hooks add

Remove a hook:

docker exec whatshooked-server /app/bin/whatshook-cli --server http://localhost:8080 hooks remove <hook_id>

List WhatsApp accounts:

docker exec whatshooked-server /app/bin/whatshook-cli --server http://localhost:8080 accounts list

Send a message:

docker exec -it whatshooked-server /app/bin/whatshook-cli --server http://localhost:8080 send

Check server health:

docker exec whatshooked-server /app/bin/whatshook-cli --server http://localhost:8080 health

Authentication with CLI

If your server has authentication enabled, you need to configure it in the CLI:

Option 1: Using command-line flags

docker exec whatshooked-server /app/bin/whatshook-cli \
  --server http://localhost:8080 \
  --api-key your-api-key \
  hooks list

Option 2: Create a CLI config file

1. Access the container:

   docker exec -it whatshooked-server sh
   

2. Create the CLI config:

   cat > /app/.whatshooked-cli.json <<EOF
   {
     "server_url": "http://localhost:8080",
     "api_key": "your-api-key"
   }
   EOF
   

3. Exit and use CLI without flags:

   docker exec whatshooked-server /app/bin/whatshook-cli hooks list
   

Shell Alias for Convenience

Create an alias on your host machine for easier CLI access:

alias whatshook-cli='docker exec -it whatshooked-server /app/bin/whatshook-cli --server http://localhost:8080'

Then use it like:

whatshook-cli hooks list
whatshook-cli send

Add this to your ~/.bashrc or ~/.zshrc to make it permanent.

Troubleshooting

Container won't start

Check logs for errors:

docker-compose logs

Config file not found

Ensure config.json exists in the project root:

ls -la config.json

Permission issues with volumes

Fix ownership of mounted directories:

sudo chown -R $(id -u):$(id -g) sessions data

QR code not displaying

Ensure show_qr: true is set in config.json:

{
  "whatsapp": [
    {
      "show_qr": true
    }
  ]
}

Cannot connect to server

Check if the container is running:

docker-compose ps

Check health status:

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:

docker network create whatshooked-net

Update docker-compose.yml:

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:

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:

docker inspect --format='{{.State.Health.Status}}' whatshooked-server

Log Management

Limit log size to prevent disk space issues:

services:
  whatshooked:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Updates

To update to the latest version:

1. Pull latest code:

   git pull
   

2. Rebuild the image:

   docker-compose build --no-cache
   

3. Restart the service:

   docker-compose down
   docker-compose up -d
   

Multi-Platform Builds

To build for different architectures (e.g., ARM for Raspberry Pi):

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t whatshooked:latest .