Getting Started with ChatAPI#

Welcome to ChatAPI! This guide will help you get up and running with your own chat service instance.

Prerequisites#

Before you begin, ensure you have the following installed:

  • Go 1.21 or later - Download from golang.org
  • Git - For cloning the repository
  • SQLite3 (optional) - For CGO builds with native SQLite driver

Installation#

1. Clone the Repository#

git clone https://github.com/Byabasaija/chatapi.git
cd chatapi

2. Install Dependencies#

go mod download

3. Build the Application#

# Build with modernc SQLite driver (recommended)
go build -o bin/chatapi ./cmd/chatapi

# Or build with CGO SQLite driver (if you have SQLite3 installed)
CGO_ENABLED=1 go build -o bin/chatapi ./cmd/chatapi

Configuration#

ChatAPI uses environment variables for configuration. Create a .env file or set them directly:

# Server configuration
export LISTEN_ADDR=":8080"
export DATABASE_DSN="file:chatapi.db?_journal_mode=WAL&_busy_timeout=5000"

# Optional: Database directory
export DATA_DIR="./data"

# Optional: Logging level
export LOG_LEVEL="info"

Configuration Options#

VariableDefaultDescription
LISTEN_ADDR:8080Server listen address
DATABASE_DSNfile:chatapi.dbSQLite database connection string
DATA_DIR./Directory for data files
LOG_LEVELinfoLogging level (debug, info, warn, error)
WAL_AUTOCHECKPOINT1000WAL checkpoint frequency
RETRY_MAX_ATTEMPTS5Max delivery retry attempts
RETRY_INTERVAL30sRetry interval
WORKER_INTERVAL30sBackground worker interval
SHUTDOWN_DRAIN_TIMEOUT10sGraceful shutdown timeout

Running ChatAPI#

Start the Server#

./bin/chatapi

You should see output similar to:

2025/12/13 12:00:00 Starting ChatAPI server addr=:8080
2025/12/13 12:00:00 Starting delivery worker interval=30s
2025/12/13 12:00:00 Starting WAL checkpoint worker interval=5m0s
2025/12/13 12:00:00 Starting HTTP server addr=:8080

Health Check#

Verify the server is running:

curl http://localhost:8080/health

Expected response:

{
  "status": "ok",
  "uptime": "1m30s",
  "db_writable": true
}

Next Steps#

Now that you have ChatAPI running, you can:

  1. Create a Tenant - Set up your first tenant with API keys
  2. Create Rooms - Start creating chat rooms
  3. Send Messages - Begin messaging
  4. Integrate WebSockets - Add real-time functionality

Development Mode#

For development with live reloading:

# Run with debug logging
export LOG_LEVEL="debug"
./bin/chatapi

# Or use air for hot reloading (if installed)
air

Troubleshooting#

Common Issues#

Port already in use:

# Change the port
export LISTEN_ADDR=":3000"

Database permission errors:

# Ensure write permissions to data directory
mkdir -p ./data
chmod 755 ./data

Build errors:

# Clean and rebuild
go clean
go mod tidy
go build ./cmd/chatapi

Logs#

Check the structured JSON logs for debugging:

./bin/chatapi 2>&1 | jq .

For more help, check the troubleshooting guide or open an issue.

API Reference Forward