Documentation

Self-Host Chitthi

Run Chitthi on your own infrastructure. Full control over data, keys, and email delivery. MIT licensed.

Open Source

MIT License

Docker Ready

BYOK

Why Self-Host?

🔐 Full data ownership- emails never leave your servers

🔑 BYOK- bring your own provider API keys

💰 No per-email fees- only pay your provider

🛠️ Customize and extend- source is yours

🌍 Deploy anywhere- cloud, VPS, or on-prem

📜 MIT licensed- use in commercial products

Prerequisites

Docker & Docker Compose

Go 1.24+ (building from source)

PostgreSQL for logs & user data

Redis for caching & rate limiting

1. Clone the Repository

bash

git clone https://github.com/imsks/chitthi.git
cd chitthi

2. Configure Environment

Create a .env file in the project root

env

# App
APP_ENV=production
PORT=8080

# Database
DATABASE_URL=postgres://postgres:postgres@db:5432/chitthi?sslmode=disable

# Redis
REDIS_URL=redis://redis:6379

# Auth / Encryption
JWT_SECRET=change-me-to-a-long-random-string
ENCRYPTION_KEY=change-me-32-byte-key

# Message Queue (optional)
RABBITMQ_URL=amqp://guest:guest@localhost:5672/

3. Start with Docker Compose

The fastest way to get Chitthi running

bash

# Build and start all services (API, web dashboard, postgres, redis)
docker compose up --build -d

# Follow logs
docker compose logs -f

# Stop services
docker compose down

API: http://localhost:8080 · Dashboard: http://localhost:3000

4. Run Migrations

bash

# Install golang-migrate: https://github.com/golang-migrate/migrate
migrate -path migrations \
  -database "postgres://postgres:postgres@localhost:5432/chitthi?sslmode=disable" up

5. Send an Email

Pass your provider API key directly in the header

bash

curl -X POST http://localhost:8080/send-email \
  -H "Content-Type: application/json" \
  -H "X-SendGrid-API-Key: your-sendgrid-key" \
  -d '{
    "from_email": "verified@yourdomain.com",
    "to_email": "recipient@example.com",
    "subject": "Hello from Chitthi!",
    "html_content": "<h1>It works!</h1>"
  }'

Alternative: Build From Source

Run the Go API and Next.js web app directly (without Docker)

Run the API

bash

go mod download
go run cmd/main.go

Run the Web Dashboard

bash

cd web
npm install
npm run build
npm run start

Hardening for Production

Terminate TLS at a reverse proxy (nginx, Caddy, Traefik)

Rotate JWT_SECRET and ENCRYPTION_KEY regularly

Use managed Postgres/Redis or enable persistent volumes

Restrict CORS origins to your domains

Enable rate limiting at the proxy layer

Back up the Postgres volume regularly

Pin Docker image tags instead of latest

Monitor logs and set up alerting

Dashboard works here too

When self-hosting, you also get the web dashboard at localhost:3000. You can manage providers and create unified API keys just like Cloud users — useful if you want a single Chitthi key instead of passing provider headers every time.