HomeChat is a small self-hosted messenger for a household or other trusted private network. It provides direct and group messaging, contacts, presence, attachments, voice snippets, Saved Messages, background notifications, and an installable PWA for desktop and mobile.

Current version: 0.14.0

HomeChat is intended for LAN/VPN use. It is not designed to be exposed directly to the public Internet without additional hardening.

• Direct messages and group chats
• Permanent HID identity, for example 7A3F-19C2-B84D
• Unique display-name sign-in
• Saved Messages
• Contacts and contact requests
• Searchable user directory by display name or HID
• Presence and typing indicators
• Delivered/read receipts and unread counts
• Distinct unread mention indicators
• Message history pagination
• Reactions, replies, edit, and soft-delete
• Image paste and drag/drop uploads
• Inline image, video, and audio playback
• Browser-recorded voice snippets
• Group and user avatars
• Per-conversation Media / Files / Links views
• Link previews
• Styled fenced code and log blocks
• Dark and light color-scheme support
• Privacy controls and block list
• Administration screen
• Installable PWA for Windows, Android, and iOS
• Web Push notifications for installed/backgrounded clients
• SQLite persistence
• Socket.IO realtime updates
• Docker deployment

The default deployment exposes:

http://SERVER:8092
https://SERVER:8093

Provides:

• certificate-install page
• homechat-root-ca.crt
• link to secure HomeChat
• /health

It does not serve login, chat, API, or Socket.IO traffic.

Provides the application, REST API, Socket.IO, attachments, service worker, Web Push registration, and PWA functionality.

git clone https://github.com/davidkeeton/homechat.git
cd homechat

cp .env.example .env

Edit .env and set the address clients will use:

HOMECHAT_HOST=192.168.1.50
HOMECHAT_HTTP_PORT=8092
HOMECHAT_HTTPS_PORT=8093
HOMECHAT_ADMIN_NAME=Admin
HOMECHAT_ADMIN_PASSWORD=choose-a-strong-password

HOMECHAT_HOST is used when generating the HTTPS certificate, so it should match the IP address or hostname users enter in their browser.

docker compose up -d --build

Check startup:

docker compose ps
docker logs homechat --tail 100

On first start, HomeChat creates its local CA and server certificate automatically inside the persistent data volume.

Open:

http://SERVER:8092

Download and trust the HomeChat root certificate, then continue to:

https://SERVER:8093

Only the public CA certificate is exposed by the bootstrap server. Private keys are never served.

The default Compose configuration uses the Docker-managed volume:

homechat-data

It is mounted inside the container at:

/app/data

This contains the SQLite database, uploads, TLS material, and VAPID keys used for Web Push.

Docker manages the host-side storage location, so HomeChat does not require a specific user's home directory.

If you prefer a specific host path, set HOMECHAT_DATA_PATH in .env:

HOMECHAT_DATA_PATH=/srv/homechat

Use the same path consistently so HomeChat continues using the same database, uploads, certificates, and push identity.

By default:

HOMECHAT_AUTO_TLS=true

If certificates do not exist, HomeChat generates:

/app/data/tls/homechat-root-ca.crt
/app/data/tls/homechat-root-ca.key
/app/data/tls/homechat.crt
/app/data/tls/homechat.key

The server certificate includes HOMECHAT_HOST, plus localhost/127.0.0.1, in its Subject Alternative Names.

Existing certificates are reused.

To manage certificates yourself:

HOMECHAT_AUTO_TLS=false

Then provide the expected certificate/key files in the data directory or override their paths with the corresponding environment variables.

tools/create-test-tls.sh is also available for manual certificate creation.

On an empty database, HomeChat can create the first administrator from:

HOMECHAT_ADMIN_NAME=Admin
HOMECHAT_ADMIN_PASSWORD=choose-a-strong-password

These settings are bootstrap-only. Once any user exists, they are ignored and cannot rename an account or reset its password.

For secret-file based deployments:

HOMECHAT_ADMIN_NAME=Admin
HOMECHAT_ADMIN_PASSWORD_FILE=/run/secrets/homechat_admin_password

The password file takes precedence over HOMECHAT_ADMIN_PASSWORD.

If no bootstrap administrator is configured, /api/setup remains available only while the user table is empty.

A HomeChat account has:

• Display name — used for sign-in and shown in the UI
• HID — permanent generated public identity

Display names are unique case-insensitively. The HID remains unchanged if a display name changes.

HomeChat supports standards-based Web Push in addition to realtime Socket.IO delivery.

When notifications are enabled, the browser creates a per-device push subscription and HomeChat stores it against the signed-in user and device.

• Messages remain stored in SQLite and delivered through the normal API/Socket.IO paths.
• Push is a notification channel, not the message transport.
• Active devices are excluded from redundant push notifications.
• Other subscribed devices can still be notified.
• Expired push subscriptions are removed automatically.
• Notification clicks open/focus HomeChat and select the relevant conversation.

VAPID keys are generated once and persisted at:

/app/data/push/vapid.json

Back this file up with the rest of HomeChat appdata. Replacing the VAPID key pair requires clients to establish new push subscriptions.

Optional VAPID contact identity:

HOMECHAT_VAPID_SUBJECT=mailto:homechat@example.invalid

The HomeChat server needs outbound HTTPS access to browser push services.

On iPhone and iPad, background Web Push requires HomeChat to be installed to the Home Screen and notification permission to be granted from the installed web app.

Administrators can:

• view user/message/file/storage statistics
• enable or disable self-registration
• require an optional invite code
• change the attachment-size limit
• create users and administrators
• enable or disable accounts
• reset passwords
• revoke sessions

1. Open the HTTPS HomeChat site in Safari.
2. Tap Share.
3. Choose Add to Home Screen.

After installing the CA certificate, iOS may also require:

Settings → General → About → Certificate Trust Settings → Full Trust

Open the HTTPS site in Chrome and use Install app or Add to Home screen.

Open the HTTPS site in Edge or Chrome and use the browser's Install app action.

The client build generates public/sw.js from sw.template.js using the version in client/package.json.

The cache name is generated automatically from the application version. Older homechat-* caches are removed when a new service worker activates.

Do not manually maintain the cache version string.

The cached PWA shell can load without a network connection, but authentication requires the server.

When HomeChat is offline, the sign-in screen reports that the server must be reachable before signing in.

Offline message queuing is not currently implemented.

Back up the persistent HomeChat data, including:

/app/data/homechat.db
/app/data/uploads/
/app/data/tls/
/app/data/push/

For the default Docker volume:

docker volume inspect homechat_homechat-data

The exact Docker volume name may include the Compose project prefix.

For a bind-mounted installation, back up the configured host data directory.

Stop HomeChat before taking a filesystem-level copy of the SQLite database if you want a simple consistent backup.

git pull --ff-only
docker compose down
docker compose up -d --build

Then verify:

docker compose ps
docker logs homechat --tail 100

Bootstrap:

curl http://SERVER:8092/health

Secure application after trusting the CA:

curl https://SERVER:8093/health

main is the active development branch.

Typical release workflow:

git status
git add .
git commit -m "HomeChat v0.14.0"
git push origin main

After testing:

git tag -a v0.14.0 -m "HomeChat v0.14.0"
git push origin v0.14.0

.env
secrets/
node_modules/
dist/
data/
*.db
*.sqlite
*.sqlite3
*.key
*.pem
*.p12
*.pfx

Private TLS keys, VAPID private keys, and administrator secrets must remain private.

HomeChat currently provides authenticated API access, server-side privacy/block enforcement, session revocation, upload limits, basic HTTP hardening, link-preview SSRF restrictions, HTTPS, and standards-based Web Push.

It does not currently provide:

• end-to-end encryption
• Internet-scale abuse protection
• native mobile push infrastructure
• voice/video calling

Do not expose HomeChat directly to the public Internet without additional review and hardening.

Check whether the deployment is using a different persistent volume or bind-mounted data path than before.

If using a bind mount, confirm .env contains the expected path:

HOMECHAT_DATA_PATH=/path/to/existing/appdata

Confirm HOMECHAT_HOST matches the address used in the browser.

If the host changes after certificates have already been generated, regenerate the server certificate deliberately. Avoid deleting the root CA unless you intend to reinstall trust on every client.

On an empty database, configure HOMECHAT_ADMIN_NAME plus either HOMECHAT_ADMIN_PASSWORD or HOMECHAT_ADMIN_PASSWORD_FILE, then restart.

/api/setup is also available until the first user is created.