Skip to content

SETUP.md

Latest commit

 

History

History
160 lines (121 loc) · 4.46 KB

SETUP.md

File metadata and controls

160 lines (121 loc) · 4.46 KB

CB Lite Chat - Setup Guide

A global chat application using Couchbase Lite with Sync Gateway for multi-device synchronization.

Features

  • 📱 Global chat visible to all users
  • 🔄 Real-time sync across devices via Sync Gateway
  • 💾 Offline-first with local Couchbase Lite database
  • 🎨 Modern dark theme UI

Prerequisites

  1. Android Studio (Arctic Fox or later)
  2. Couchbase Server (7.0 or later)
  3. Sync Gateway (3.0 or later)

Quick Start (Without Sync Gateway)

The app works offline without Sync Gateway. Messages are stored locally in Couchbase Lite.

  1. Open the project in Android Studio
  2. Sync Gradle files
  3. Run on emulator or device
  4. Start chatting!

Setting Up Sync Gateway

1. Install Couchbase Server

  1. Download Couchbase Server from https://www.couchbase.com/downloads
  2. Install and start the server
  3. Create a bucket named chat
  4. Create a user with access to the bucket

2. Install Sync Gateway

  1. Download Sync Gateway from https://www.couchbase.com/downloads
  2. Use the provided sync-gateway-config.json configuration
  3. Update the configuration with your Couchbase Server credentials

3. Configure Sync Gateway

Edit sync-gateway-config.json:

{
  "databases": {
    "chat": {
      "server": "couchbase://localhost",
      "bucket": "chat",
      "username": "your_couchbase_admin",
      "password": "your_password",
      "users": {
        "user": {
          "password": "password",
          "admin_channels": ["*"]
        }
      }
    }
  }
}

4. Start Sync Gateway

./sync_gateway sync-gateway-config.json

Sync Gateway will start on:

  • WebSocket: ws://localhost:4984/chat
  • Admin API: http://localhost:4985

5. Connect from App

  1. Open the app
  2. Tap "Connect" button
  3. Configure the Sync Gateway URI:
    • Android Emulator: ws://10.0.2.2:4984/chat
    • Physical Device: ws://YOUR_MACHINE_IP:4984/chat
  4. Enter username: user
  5. Enter password: password
  6. Tap Connect

Network Configuration

Android Emulator

Use 10.0.2.2 instead of localhost to reach the host machine.

Physical Device

  1. Ensure device and server are on the same network
  2. Find your machine's IP address:
    • macOS/Linux: ifconfig or ip addr
    • Windows: ipconfig
  3. Use that IP in the Sync Gateway URI

Firewall

Ensure port 4984 is open for WebSocket connections.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Android App   │     │  Sync Gateway   │     │ Couchbase Server│
│                 │     │                 │     │                 │
│ ┌─────────────┐ │     │                 │     │ ┌─────────────┐ │
│ │ Couchbase   │ │◄───►│                 │◄───►│ │    chat     │ │
│ │   Lite DB   │ │ WS  │                 │     │ │   bucket    │ │
│ └─────────────┘ │     │                 │     │ └─────────────┘ │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Data Model

Chat Message Document

{
  "_id": "auto-generated",
  "type": "chat_message",
  "senderName": "User_abc123",
  "senderId": "abc123",
  "message": "Hello, world!",
  "timestamp": 1705590000000
}

Troubleshooting

"Connection refused" error

  • Check Sync Gateway is running
  • Verify the URI (use 10.0.2.2 for emulator)
  • Check firewall settings

Messages not syncing

  • Verify Sync Gateway logs for errors
  • Check user credentials
  • Ensure continuous replication is enabled

App crashes on startup

  • Clean and rebuild the project
  • Check Couchbase Lite initialization in logcat

Files Structure

app/src/main/java/com/couchbase/android/getstarted/kotlin/
├── ChatAdapter.kt       # RecyclerView adapter for messages
├── ChatMessage.kt       # Data class for messages
├── DBManager.kt         # Couchbase Lite database manager
├── GettingStartedApplication.kt  # Application class with Koin DI
├── MainActivity.kt      # Main chat activity
└── MainViewModel.kt     # ViewModel with chat logic

License

Apache License 2.0