🔧 Install & Update
If you wish to follow a Step-By-Step guide which shows you how to send your first message via HTTP API, please go to ⚡ Quick Start.
You probably already have run the docker run command during ⚡ Quick Start guide:
docker run -it --rm -p 3000:3000 --name waha devlikeapro/waha
☝️ The above command is good for development purposes, but not for production.
To make it production-ready, you need to configure a few more parameters to make it secure, reliable, and easy to manage.
Requirements
System Requirements
You can use any operating system for host system (Linux, Windows or macOS) as long as you have Docker installed, and it can run Linux containers.
💡 We recommend using Linux with Debian or Ubuntu based distributions.
We strongly recommend using VPS or servers with minimum 2CPU and 2GB RAM configuration for the project even for a single session. If you want to host more sessions - please check the numbers in FAQ.
Linux
👉 We suggest using Debian or Ubuntu based distributions.Windows
👉 For Windows we kindly suggest using Hyper-V backend for Docker Desktop!
It might not work with WSL2 backend properly.
Pre-requisites
Before proceeding, make sure you have the latest version of docker
and docker compose
installed.
We recommend using Docker version equal to or higher than the following:
$ docker --version
Docker version 26.1.3, build b72abbb
$ docker compose version
Docker Compose version v2.27.0
Why Docker?
Docker makes it easy to ship all-in-one solution with the runtime and dependencies. You don’t have to worry about language-specific libraries or chrome installation.
Also, Docker makes installation and update processes so simple, just one command!
Why Docker Compose?
Docker Compose is a tool for defining and running Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.Get docker image
Follow the instructions below:
Install
Docker
- Install Docker on your VM
# example in ubuntu
apt-get update
apt-get upgrade
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
apt install docker-compose-plugin
WAHA
- Download the required files
# Download the env file template
wget -O .env https://raw.githubusercontent.com/devlikeapro/waha/refs/heads/core/.env.example
# Download the Docker compose template
wget -O docker-compose.yaml https://raw.githubusercontent.com/devlikeapro/waha/refs/heads/core/docker-compose.yaml
- Tweak the
.env
anddocker-compose.yaml
according to your preferences. Refer to the available environment variables in ⚙️ Configuration.
Some important values you MUST change before publishing it to the internet:
Set API Key
WAHA_API_KEY=sha512:{SHA512_HEX_OF_YOUR_API_KEY_HERE}
- Default Api Key is
admin
- Read more about 🔒 Security
👉 How to Generate and Hash Api-Key
- Generate Api Key using uuid4 and remove
-
from it (or find a tool online)
uuidgen | tr -d '-'
> 00000000000000000000000000000000
- Hash it using sha512 (or find a tool online)
echo -n "00000000000000000000000000000000" | shasum -a 512
> 98b6d128682e280b74b324ca82a6bae6e8a3f7174e0605bfd52eb9948fad8984854ec08f7652f32055c4a9f12b69add4850481d9503a7f2225501671d6124648 -
0000...0000
- Api Key that you need to send inX-Api-Key
header, keep it in secret.98b6...24648
- SHA512 hash in hex format. You can set it inWAHA_API_KEY=sha512:{HASH}
📊 Dashboard and 📚 Swagger:
WAHA_DASHBOARD_USERNAME=admin
WAHA_DASHBOARD_PASSWORD=admin
WHATSAPP_SWAGGER_USERNAME=admin
- you can set the same asWAHA_DASHBOARD_USERNAME
WHATSAPP_SWAGGER_PASSWORD=admin
- you can set the same asWAHA_DASHBOARD_PASSWORD
# update .env file with your values
nano .env
# update docker-compose.yaml - like image
# Remove "mongodb" and "minio" services if you don't need them
# Leave "waha" service as it is
nano docker-compose.yaml
- Get the service up and running.
docker compose up -d
- Your WAHA installation is complete. Please note that the containers are not exposed to the internet, and they only bind to the localhost. Set up something like Nginx or any other proxy server to proxy the requests to the container.
How to export port from remote server?
If you’re using a remote server (like VPS or Virtual Machine on your laptop) you need to allow access for your browser. Use one of the options available.
- Use SSH tunneling
If you’re connecting to ssh, you can forward port 3000 on your laptop like
ssh -L 3000:localhost:3000 user@you.address.here
- Bind port to all ips
For temporary external access, you can change the port binding from 127.0.0.1:3000:3000
to 3000:3000
in the docker-compose.yaml
file.
services:
waha:
image: devlikeapro/waha-plus
ports:
- "3000:3000"
docker compose up -d
This makes your instance accessible at http://<your-external-ip>:3000
.
- Now, open http://localhost:3000/dashboard and login with the credentials you’ve set
By default you can use:
- Dashboard -
admin/admin
- Swagger -
admin/admin
- Api Key -
admin
Use Nginx to handle HTTPS
We recommend handling HTTPS termination with a reverse proxy like Nginx.
Follow 🔧 Install & Update - Nginx to set up Nginx with Let’s Encrypt.
Nginx
👉 Replace <YOUR_DOMAIN_OR_IP> with your domain name in the following steps (use lowercase).
- Configure Nginx to serve as a frontend proxy.
sudo apt-get install nginx
cd /etc/nginx/sites-enabled
nano <YOUR_DOMAIN_OR_IP>.conf
- Use the following Nginx config and replace the
<YOUR_DOMAIN_OR_IP>
inserver_name
.
server {
server_name <YOUR_DOMAIN_OR_IP>;
# Point upstream to WAHA Server
set $upstream 127.0.0.1:3000;
location /.well-known {
alias /var/www/ssl-proof/waha/.well-known;
}
location / {
proxy_pass_header Authorization;
proxy_pass http://$upstream;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Ssl on; # Optional
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_buffering off;
client_max_body_size 0;
proxy_read_timeout 36000s;
proxy_redirect off;
}
listen 80;
}
- Verify and reload your Nginx config by running the following command.
nginx -t
systemctl reload nginx
Here are two scenarios for setting up HTTPS:
HTTPS - Let’s Encrypt
If you have a domain name (e.g., yourdomain.com) that points to your server’s IP address, you can use Let’s Encrypt to get free, trusted SSL certificates:
- Run Let’s Encrypt to configure SSL certificate. (replace <YOURDOMAIN.COM>!)
apt install certbot
apt-get install python3-certbot-nginx
mkdir -p /var/www/ssl-proof/waha/.well-known
certbot --webroot -w /var/www/ssl-proof/waha/ -d <YOURDOMAIN.COM> -i nginx
- Your WAHA installation should be accessible from the https://yourdomain.com now.
- Change
WAHA_BASE_URL=https://<YOURDOMAIN.COM>
in the.env
file and restart the WAHA service
# Change the WAHA_BASE_URL in .env
nano .env
# Restart the WAHA service
docker compose up -d
docker compose restart
HTTPS - Self-Signed Certificate for IP-Based Access
If you don’t have a domain name or are using a private IP address, you can create a self-signed certificate for IP-based access:
- Create a directory for your SSL certificates:
mkdir -p /etc/nginx/ssl
cd /etc/nginx/ssl
- Create a configuration file for the self-signed certificate:
cat > ip-cert.cnf << 'EOL'
[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
x509_extensions = v3_ca
[dn]
C=US
ST=State
L=City
O=Organization
OU=Department
CN=<YOUR_IP_ADDRESS>
[v3_ca]
subjectAltName = @alt_names
[alt_names]
IP.1 = <YOUR_IP_ADDRESS>
EOL
- Generate a self-signed certificate valid for 10 years (3650 days):
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout ip-cert.key -out ip-cert.crt -config ip-cert.cnf
- Update your Nginx configuration to use the self-signed certificate:
cd /etc/nginx/sites-enabled
nano <YOUR_DOMAIN_OR_IP>.conf
- Modify your Nginx configuration to include SSL settings:
server {
listen 80;
server_name <YOUR_IP_ADDRESS>;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name <YOUR_IP_ADDRESS>;
ssl_certificate /etc/nginx/ssl/ip-cert.crt;
ssl_certificate_key /etc/nginx/ssl/ip-cert.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
# Point upstream to WAHA Server
set $upstream 127.0.0.1:3000;
location / {
proxy_pass_header Authorization;
proxy_pass http://$upstream;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Ssl on; # Optional
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_buffering off;
client_max_body_size 0;
proxy_read_timeout 36000s;
proxy_redirect off;
}
}
- Verify and reload your Nginx config:
nginx -t
systemctl reload nginx
- Update your WAHA configuration to use HTTPS:
# Change the WAHA_BASE_URL in .env to use https
nano .env
# Add or modify: WAHA_BASE_URL=https://<YOUR_IP_ADDRESS>
# Restart the WAHA service
docker compose up -d
docker compose restart
- When accessing your WAHA instance, you’ll need to accept the self-signed certificate warning in your browser.
Update
When there’s a new version of WAHA, you can update it with these simple commands:
➕ WAHA Plus image:
# Login if you're using WAHA Plus
docker login -u devlikeapro -p {KEY}
docker compose pull
docker logout
docker compose up -d
👉 If you specified exact version in docker-compose.yml
, like
image: devlikeapro/waha-plus:latest-2024.7.8
remember to change it to latest-{YEAR}.{MONTH}.{BUILD}
to get the latest version.
WAHA Core image:
docker compose pull
docker compose up -d
Get logs, restart, stop
# Stop all containers
docker compose down
# Start all containers, apply new configuration
docker compose up -d
# Restart all containers
docker compose restart
# Show logs in real time
docker compose logs -f
# Show logs - since interval
docker compose logs --since 1h