🔐 Authentication — Login, remember me, forced password change on first login
💬 Real-time messaging — WebSocket (Socket.io) powered chat
👥 Public channels — Admin-created, all users auto-joined
🔒 Private groups — User-created, owner-managed
📷 Image uploads — Attach images to messages
💬 Message quoting — Reply to any message with preview
😎 Emoji reactions — Quick reactions + full emoji picker
@Mentions — @mention users with autocomplete, they get notified
🔗 Link previews — Auto-fetches OG metadata for URLs
📱 PWA — Install to home screen, works offline
👤 Profiles — Custom avatars, display names, about me
⚙️ Admin settings — Custom logo, app name
👨‍💼 User management — Create, suspend, delete, bulk CSV import
📢 Read-only channels — Announcement-style public channels

Quick Start

Prerequisites

Docker & Docker Compose

1. Build a versioned image

# Build and tag as v1.0.0 (also tags :latest)
./build.sh 1.0.0

# Build latest only
./build.sh

2. Deploy with Docker Compose

cp .env.example .env
# Edit .env — set TEAMCHAT_VERSION, admin credentials, JWT_SECRET
nano .env

docker compose up -d

# View logs
docker compose logs -f

App will be available at http://localhost:3000

Release Workflow

TeamChat uses a build-then-run pattern. You build the image once on your build machine (or CI), then the compose file just runs the pre-built image — no build step at deploy time.

┌─────────────────────┐      ┌──────────────────────────┐
│  Build machine / CI │      │  Server / Portainer      │
│                     │      │                          │
│  ./build.sh 1.2.0   │─────▶│  TEAMCHAT_VERSION=1.2.0  │
│  (or push to        │      │  docker compose up -d    │
│   registry first)   │      │                          │
└─────────────────────┘      └──────────────────────────┘

Build script usage

# Build locally (image stays on this machine)
./build.sh 1.0.0

# Build and push to Docker Hub
REGISTRY=yourdockerhubuser ./build.sh 1.0.0 push

# Build and push to GHCR
REGISTRY=ghcr.io/yourorg ./build.sh 1.0.0 push

Deploying a specific version

Set TEAMCHAT_VERSION in your .env before running compose:

# .env
TEAMCHAT_VERSION=1.2.0

docker compose pull   # if pulling from a registry
docker compose up -d

Rolling back

# .env
TEAMCHAT_VERSION=1.1.0

docker compose up -d  # instantly rolls back to previous image

Data volumes are unaffected by version changes.

Environment Variables

Variable	Default	Description
`ADMIN_NAME`	`Admin User`	Default admin display name
`ADMIN_EMAIL`	`admin@teamchat.local`	Default admin email (login)
`ADMIN_PASS`	`Admin@1234`	Default admin password (first run only)
`PW_RESET`	`false`	If `true`, resets admin password to `ADMIN_PASS` on every restart
`JWT_SECRET`	(insecure default)	Change this! Used to sign auth tokens
`PORT`	`3000`	HTTP port to listen on
`APP_NAME`	`TeamChat`	Initial app name (can be changed in Settings)

Important: ADMIN_EMAIL and ADMIN_PASS are only used on the very first run to create the admin account. After the admin changes their password, these variables are ignored — unless PW_RESET=true.

Navigate to http://localhost:3000
Login with ADMIN_EMAIL / ADMIN_PASS
You'll be prompted to change your password immediately
You're in! The default TeamChat public channel is ready

PW_RESET Warning

If you set PW_RESET=true:

The admin password resets to ADMIN_PASS on every container restart
A ⚠️ warning banner appears on the login page
This is intentional for emergency access recovery
Always set back to false after recovering access

User Management

Admins can access User Manager from the bottom menu:

Create single user — Name, email, temp password, role
Bulk import via CSV — Format: name,email,password,role
Reset password — User is forced to change on next login
Suspend / Activate — Suspended users cannot login
Delete — Soft delete; messages remain, sessions invalidated
Elevate / Demote — Change member ↔ admin role

Group Types

	Public Channels	Private Groups
Creator	Admin only	Any user
Members	All users (auto)	Invited by owner
Visible to admins	✅ Yes	❌ No (unless admin takes ownership)
Leave	❌ Not allowed	✅ Yes
Rename	Admin only	Owner only
Read-only mode	✅ Optional	❌ N/A
Default group	TeamChat (permanent)	—

CSV Import Format

name,email,password,role
John Doe,john@example.com,TempPass123,member
Jane Admin,jane@example.com,Admin@456,admin

role can be member or admin
password defaults to TempPass@123 if omitted
All imported users must change password on first login

Data Persistence

All data is stored in Docker volumes:

teamchat_db — SQLite database
teamchat_uploads — User avatars, logos, message images

Data survives container restarts and redeployments.

PWA Installation

On mobile: Share → Add to Home Screen
On desktop (Chrome): Click the install icon in the address bar

Portainer / Dockhand Deployment

Use the docker-compose.yaml directly in Portainer's Stack editor. Set environment variables in the .env section or directly in the compose file.

Development

# Backend
cd backend && npm install && npm run dev

# Frontend (in another terminal)
cd frontend && npm install && npm run dev

Frontend dev server proxies API calls to localhost:3000.

README.md

TeamChat 💬

Features