# TeamChat 💬

A modern, self-hosted team chat Progressive Web App (PWA) — similar to Google Messages / Facebook Messenger for teams.

---

## Features

- 🔐 **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, reset password, suspend, delete, bulk CSV import
- 📢 **Read-only channels** — Announcement-style public channels

---

## Quick Start

### Prerequisites
- Docker & Docker Compose

### 1. Build a versioned image

```bash
# 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

```bash
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

```bash
# 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:

```bash
# .env
TEAMCHAT_VERSION=1.2.0
```

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

### Rolling back

```bash
# .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`.

---

## First Login

1. Navigate to `http://localhost:3000`
2. Login with `ADMIN_EMAIL` / `ADMIN_PASS`
3. You'll be prompted to **change your password** immediately
4. 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

```csv
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

```bash
# 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`.