Self-hosting WATeamInbox means running the web application, data services, and WhatsApp connection workers on infrastructure your team controls.
This article covers the decisions and checks around a deployment. For current commands and configuration, follow the self-hosting documentation and the files in the GitHub repository.
Decide whether your team should operate it
Self-hosting is a reasonable choice if someone on your team is comfortable with Linux, Docker, databases, TLS, backups, and routine updates. It can keep the application and customer conversation data inside an environment you manage.
It is a poor fit if nobody can respond when a service stops, a disk fills, or a migration fails. In that case, WATeamInbox Cloud may be simpler because we operate the application stack.
Know the services involved
The current production baseline includes:
- the web inbox
- the API behind the internal readiness-aware HAProxy router (with optional homogeneous API replicas)
- PostgreSQL for application data
- NATS for commands and events
- Centrifugo for live inbox updates
- Meilisearch for search
- WhatsApp worker and orchestrator processes
- private Cloudflare R2 through its account S3 API endpoint for media
- Caddy for HTTPS and edge routing
You do not need to become an expert in every service before running the development stack. You do need to know where each service stores data, which ports should be private, and how you will notice a failure.
Read the WhatsApp warning first
WATeamInbox uses an unofficial WhatsApp client library. WhatsApp can change its protocol or policies, pairing can stop working, and account restrictions are possible. WATeamInbox cannot guarantee account safety and is not affiliated with WhatsApp or Meta.
Use a non-critical number for the first deployment where possible. Do not move an important customer number until your team has tested connection recovery and agreed on a fallback process.
Write down where the data will live
Before creating the server, decide:
- where PostgreSQL data is stored
- which object store holds images, documents, and voice messages
- where backups are copied
- who can administer the host
- how secrets are created, stored, and rotated
- how long logs and customer data are retained
Keep database, NATS, search, and object-storage administration ports off the public internet. The web entry point should use HTTPS.
Use a staged rollout
1. Run it locally
Start with the development setup in the repository. Create a workspace, invite another user, and follow a message from WhatsApp into the web inbox.
The local Compose configuration uses development credentials and exposed ports. Do not treat it as a production configuration.
2. Build a staging server
Use the documented single-host production baseline on a small, non-critical server. Configure real secret files, TLS, persistent volumes, and backup destinations.
Before inviting a team, confirm that you can:
- run database migrations
- pair and reconnect a WhatsApp number
- send and receive a test message
- open supported media
- assign a conversation between two users
- restrict actions with roles and permissions
- restore the database and media references on a clean system
3. Pilot with two or three teammates
Run one small queue through the inbox. Agree on who watches unassigned messages, when an agent assigns a conversation, and what information belongs in an internal note.
Watch the services during the pilot. Check disk growth, backup size, worker restarts, and search behaviour instead of waiting for a customer to report a problem.
4. Prepare the main number
If you decide to move an important number, schedule the change and write down how to return to the previous process. Keep recent backups and make sure the team knows whom to contact if the WhatsApp connection drops.
Back up both messages and media
A database backup is not enough if customer documents and voice messages are stored separately. Back up PostgreSQL and object storage on a schedule that matches the amount of data your team can afford to lose.
Restore them together on another machine. Confirm that users, conversations, assignments, and media still load. A restore test is the only reliable proof that the backup is useful.
Review access before launch
Give every teammate their own account. Reserve owner and administrator roles for people who need to manage connections, members, settings, and exports.
Also review host access. Product permissions do not protect the data from someone with broad database, object-storage, or server credentials.
Minimum launch checklist
Before relying on the deployment, verify:
- HTTPS works on the production domain
- only intended ports are public
- each teammate signs in with an individual account
- the WhatsApp connection recovers after a worker restart
- assignments and notes survive a handoff
- supported media can be viewed
- backups run away from the main host
- a restore has succeeded on a clean system
- someone receives alerts for service or storage failures
- the team has a fallback when WhatsApp connectivity is unavailable
The public deployment guide is a single-host baseline. It can use multiple API processes for process and release resilience, but it is not a high-availability or multi-region design, so set expectations accordingly. The orchestrator remains a singleton.
When those checks are routine, continue with the commands and configuration in the self-hosting docs. If operating the stack becomes more work than your team wants, compare the current Cloud plans.