Getting Started Installation

Installation

There are three ways to run ForgeChat — pick one:

#	Install on	Best for
1	🪟 Windows	Trying it on your own PC
2	🍎 macOS	Trying it on your own Mac
3	🖥️ Server	Real 24/7 use with your own domain

Windows and Mac run on your own computer with Docker Desktop + a free Cloudflare Tunnel — great for testing and demos. The Server option is for real production use, online 24/7. You won't write any code — you mostly copy and paste, and it takes about 15–20 minutes.

⚡ Prefer one command? After you've installed Docker and downloaded ForgeChat (the "Install the tools" + "Download" steps for your platform below), run the installer instead of the manual setup — it generates secrets, builds everything, applies all migrations, and starts the app:

🍎 macOS / 🐧 Linux server: bash install.sh

🪟 Windows (PowerShell): .\install.ps1

It's safe to re-run — it never overwrites an existing backend/.env.

🐳 Don't want to build at all? Pull the pre-built images instead — see Run from pre-built images below (great for small servers where the build can run out of memory).

After it's running, connect your number in WhatsApp Business API / Meta Setup. For every setting explained, see Configuration & Environment Variables.

🪟 Install on Windows

1. Install the tools

Git for Windows — https://git-scm.com/download/win (click Next through the installer).
Docker Desktop — https://www.docker.com/products/docker-desktop/ (keep WSL 2 ticked, restart your PC, then open Docker Desktop and wait for "Engine running").

2. Download ForgeChat — open PowerShell and run:

cd $env:USERPROFILE\Desktop
git clone https://github.com/Forgemind-git/ForgeChat.git forgechat
cd forgechat

3. Run the installer — it generates secrets, builds everything, applies all migrations, and starts the app:

.\install.ps1

When it finishes, open http://localhost and log in with the email/password it asked for (defaults: admin@forgechat.local / Admin@123456). Save the webhook verify token it prints — you'll need it below.

4. Make it reachable by WhatsApp (Cloudflare Tunnel) — Meta needs a public URL to deliver messages. Cloudflare Tunnel gives you a free temporary HTTPS URL with no sign-up:

# one-time: install cloudflared
winget install --id Cloudflare.cloudflared

# open a NEW PowerShell window and start the tunnel — keep this window open
& "C:\Program Files (x86)\cloudflared\cloudflared.exe" tunnel --url http://localhost:80

It prints a public address like https://some-random-words.trycloudflare.com. Then, in another PowerShell window:

Point ForgeChat at that address (use your real URL) and restart the backend:

(Get-Content backend\.env) -replace 'CORS_ORIGIN=.*', 'CORS_ORIGIN=https://some-random-words.trycloudflare.com' | Set-Content backend\.env
docker compose restart forgecrm-backend

Follow WhatsApp Business API / Meta Setup, using the Cloudflare address as the Callback URL (https://some-random-words.trycloudflare.com/api/webhook/whatsapp) with the verify token from step 3.

ℹ️ The quick-tunnel URL changes each time you restart cloudflared — update CORS_ORIGIN and the Meta webhook URL whenever it does, and don't close the cloudflared window while testing.

🍎 Install on Mac

1. Install the tools

Docker Desktop — https://www.docker.com/products/docker-desktop/ (pick the Apple Silicon or Intel build to match your Mac, open it, and wait for "Engine running").
Git — already ships with macOS. The first git command may prompt you to install the developer tools — click Install, or run xcode-select --install.

2. Download ForgeChat — open Terminal and run:

cd ~/Desktop
git clone https://github.com/Forgemind-git/ForgeChat.git forgechat
cd forgechat

3. Run the installer — choose local when it asks; it generates secrets, builds everything, applies all migrations, and starts the app:

bash install.sh

When it finishes, open http://localhost and log in with the email/password it asked for (defaults: admin@forgechat.local / Admin@123456). Save the webhook verify token it prints — you'll need it below.

4. Make it reachable by WhatsApp (Cloudflare Tunnel) — Meta needs a public URL to deliver messages. Cloudflare Tunnel gives you a free temporary HTTPS URL with no sign-up:

# install cloudflared (needs Homebrew — https://brew.sh)
brew install cloudflared

# start the tunnel — keep this Terminal window open
cloudflared tunnel --url http://localhost:80

It prints a public address like https://some-random-words.trycloudflare.com. Then, in another Terminal tab:

Point ForgeChat at that address (use your real URL) and restart the backend:

sed -i '' 's|CORS_ORIGIN=.*|CORS_ORIGIN=https://some-random-words.trycloudflare.com|' backend/.env
docker compose restart forgecrm-backend

Follow WhatsApp Business API / Meta Setup, using the Cloudflare address as the Callback URL (https://some-random-words.trycloudflare.com/api/webhook/whatsapp) with the verify token from step 3.

ℹ️ The quick-tunnel URL changes each time you restart cloudflared — update CORS_ORIGIN and the Meta webhook URL whenever it does, and keep the cloudflared window open while testing.

🖥️ Run on a server (production, 24/7)

🌐 The production path — your own server and domain, online 24/7, with automatic HTTPS.

💡 Prefer a click-by-click version with pictures? Follow DEPLOY-DIGITALOCEAN.md instead — it's the same process with more detail. The steps below are the short version.

✅ What you'll need first

You need	Roughly	What it's for
A server (a small cloud computer you rent)	~$12 / month	Where ForgeChat runs, 24/7
A domain name (like `chat.yourbusiness.com`)	~$10 / year	The web address you'll open in the browser
A Meta WhatsApp Business account	Free	To send/receive real WhatsApp messages
About 15–20 minutes	—	To follow these steps

Step 1 — Rent a server

Create a server (also called a "VPS" or "droplet") at a provider like DigitalOcean, Hetzner, or any cloud host.

Operating system: Ubuntu 24.04 (LTS)
Size: 4 GB of RAM recommended (2 GB works, but building the frontend is memory-hungry and can run out)

When it's ready, copy the server's public IP address (it looks like 203.0.113.10).

Step 2 — Point your domain at the server

In your domain provider's DNS settings, add an "A record":

Type	Name	Value
A	`chat` (or whatever subdomain you want)	your server's IP address

This makes chat.yourbusiness.com lead to your server. (DNS can take a few minutes to update.)

Step 3 — Connect to your server and install Docker

Connect to your server (replace with your IP):

ssh root@YOUR_SERVER_IP

Open the firewall (SSH, HTTP, HTTPS), then install Docker:

ufw allow OpenSSH && ufw allow 80/tcp && ufw allow 443/tcp && ufw --force enable

curl -fsSL https://get.docker.com | sh
# (optional) run Docker without typing "sudo" every time
usermod -aG docker $USER && newgrp docker

Step 4 — Download ForgeChat

git clone https://github.com/Forgemind-git/ForgeChat.git forgechat
cd forgechat

Step 5 — Run the installer

The installer sets everything up for you — choose Server when it asks, and give it your domain. It writes your settings, points Caddy at your domain, builds the app, applies all migrations, and starts everything (including automatic HTTPS):

bash install.sh

Save the verify token it prints — you'll need it when connecting WhatsApp — and remember the admin email/password you set; that's your login.

Prefer to do it manually instead of the installer?

# point Caddy at your domain (replace with your real domain)
cp docker-compose.sample.yml docker-compose.yml
sed -i 's/forgechat.example.com/chat.yourbusiness.com/' Caddyfile

# create your secret settings (replace chat.yourbusiness.com with your real domain)
PGPASS=$(openssl rand -hex 24)
JWT=$(openssl rand -hex 32)
ENCKEY=$(openssl rand -hex 32)
VERIFY=$(openssl rand -hex 16)

cat > backend/.env <<EOF
NODE_ENV=production
PORT=3011
POSTGRES_PASSWORD=${PGPASS}
DATABASE_URL=postgresql://postgres:${PGPASS}@forgecrm-db:5432/postgres
POSTGRES_SSL=false
REDIS_URL=redis://redis:6379
JWT_SECRET=${JWT}
FORGECRM_ENCRYPTION_KEY=${ENCKEY}
CORS_ORIGIN=https://chat.yourbusiness.com
META_API_VERSION=v21.0
META_WEBHOOK_VERIFY_TOKEN=${VERIFY}
MEDIA_DIR=/app/media
ADMIN_EMAIL=you@yourbusiness.com
ADMIN_PASSWORD=choose-a-strong-password
EOF
echo "SAVE THIS — your WhatsApp verify token: ${VERIFY}"

# build, start the DB, create tables + run migrations, then start the app
docker compose build
docker compose up -d forgecrm-db redis
until [ "$(docker inspect -f '{{.State.Health.Status}}' forgecrm-db)" = healthy ]; do
  echo "waiting for database..."; sleep 2; done
docker compose exec -T forgecrm-db psql -U postgres -d postgres <<'SQL'
CREATE SCHEMA IF NOT EXISTS coexistence;
CREATE TABLE IF NOT EXISTS coexistence.forgecrm_users (
  id BIGSERIAL PRIMARY KEY,
  username TEXT NOT NULL UNIQUE,
  email TEXT NOT NULL UNIQUE,
  password TEXT NOT NULL,
  display_name TEXT,
  role TEXT NOT NULL DEFAULT 'viewer',
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
SQL
for f in $(ls db/migrations/*.sql | sort); do
  docker compose exec -T forgecrm-db psql -U postgres -d postgres -v ON_ERROR_STOP=1 < "$f";
done
docker compose up -d forgecrm-backend forgecrm-frontend caddy

Step 6 — Open it! 🎉

In your browser, go to https://chat.yourbusiness.com and log in with the email and password you set.

The first time you visit, the secure padlock (HTTPS) is set up automatically. If you see a certificate warning, wait a minute and refresh — your domain's DNS may still be updating.

🐳 Run from pre-built images (skip the build)

Every release publishes images to the GitHub Container Registry (GHCR), so you can pull them instead of building from source. This skips docker compose build entirely — handy on small servers where the frontend build can run out of memory.

You still clone the repo (for the compose file, Caddyfile, database migrations, and backend/.env) and create your settings as in the steps above — you just don't build. After the Download + settings steps for your platform:

1. Point Compose at the published images. Create a docker-compose.override.yml next to your docker-compose.yml:

services:
  forgecrm-backend:
    image: ghcr.io/forgemind-git/forgechat-backend:latest
  forgecrm-frontend:
    image: ghcr.io/forgemind-git/forgechat-frontend:latest

Pin a version instead of latest for reproducible deploys, e.g. :1.0.0.

2. Pull everything and start — no build step:

docker compose pull

# start the database + cache, wait for health, then run the migrations
# exactly as in your platform's steps above (the CREATE SCHEMA + migration loop)
docker compose up -d forgecrm-db redis

# start the app from the pulled images (add 'caddy' on a server)
docker compose up -d --no-build forgecrm-backend forgecrm-frontend

To update later — pull the new images and recreate, no rebuild:

docker compose pull
docker compose up -d --no-build

Keeping it running

Update to the latest version (run inside the forgechat folder):

git pull
docker compose build forgecrm-backend forgecrm-frontend
docker compose up -d forgecrm-backend forgecrm-frontend

Back up your data (recommended — a daily automatic backup):

mkdir -p ~/backups
crontab -e
# add this line to back up every day at 3 AM and keep 7 days:
0 3 * * * docker exec forgecrm-db pg_dump -U postgres postgres | gzip > ~/backups/forgechat-$(date +\%Y\%m\%d).sql.gz && find ~/backups -name '*.sql.gz' -mtime +7 -delete

See also: Configuration & Environment Variables • WhatsApp Business API / Meta Setup • Troubleshooting

ForgeChat Wiki

🏠 Home

Setup

Using ForgeChat

Help

Project

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started Installation

Installation

🪟 Install on Windows

🍎 Install on Mac

🖥️ Run on a server (production, 24/7)

✅ What you'll need first

Step 1 — Rent a server

Step 2 — Point your domain at the server

Step 3 — Connect to your server and install Docker

Step 4 — Download ForgeChat

Step 5 — Run the installer

Step 6 — Open it! 🎉

🐳 Run from pre-built images (skip the build)

Keeping it running

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ForgeChat Wiki

Clone this wiki locally