Guide - Environment Setup

This guide walks through every service that booki-api depends on and explains how to obtain the required credentials.

Quick Start

cp .env.example .env
# Then fill in the sections below

Variables already covered by the current backend defaults or existing .env.example entries (override them only if you need custom values):

1. Redis

Redis is used for caching and session management.

REDIS_HOST=your-redis-host.redis.cloud
REDIS_PORT=12345
REDIS_PASSWORD=your-redis-password
REDIS_TLS=true

Set REDIS_TLS=true for Redis Cloud and production. Set to false for local Redis.

Option A — Redis Cloud (recommended for beginners):

1. Sign up at redis.com/try-free — free 30 MB tier.
2. Create a database and copy host, port, and password into .env.

Option B — Local Redis:

# macOS
brew install redis && brew services start redis

# Linux
sudo apt-get install redis-server && sudo systemctl start redis

# Windows — download from https://github.com/microsoftarchive/redis/releases

Local .env values:

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_TLS=false

For detailed Redis commands and cache patterns, see Redis Guide.

2. Maya

Maya is the payment gateway used for booking payments and subscription billing.

MAYA_PUBLIC_KEY=pk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MAYA_SECRET_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MAYA_API_URL=https://pg-sandbox.paymaya.com
MAYA_PAYMENT_EXPIRY=1440

1. Obtain Maya sandbox credentials from the project supervisor or the Maya developer portal.
2. Set MAYA_API_URL=https://pg-sandbox.paymaya.com for development.
3. Switch to https://pg.paymaya.com for production.
4. MAYA_PAYMENT_EXPIRY is in minutes (default 1440 = 24 hours).

Use sandbox keys (pk-Z0OS... / sk-aXQd... pattern) for development. Switch to live keys only in production.

3. Google OAuth

Required for Google Sign-In.

GOOGLE_CLIENT_ID=1084594124395-xxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxxx

1. Open console.cloud.google.com.
2. Create or select a project.
3. Go to APIs & Services → Library, search Google+ API, and enable it.
4. Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID.
5. Application type: Web application.
6. Authorized redirect URIs:
   • http://localhost:3000/auth/google/callback (development)
   • https://your-domain.com/auth/google/callback (production)
7. Copy the Client ID and Client Secret.

4. Gmail SMTP

Used for transactional emails — booking confirmations, password resets, and notifications.

GMAIL_USER=your-email@gmail.com
GMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx
GMAIL_HOST=smtp.gmail.com
GMAIL_PORT=587
GMAIL_SECURE=false
ADMIN_EMAIL=admin@yourdomain.com

You need a Gmail App Password (not your regular Google password). App Passwords require 2-Step Verification to be enabled on the account.

For step-by-step instructions, see Gmail Setup Guide.

5. MongoDB

MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/
MONGO_DB=codiDev

1. Create a free cluster at mongodb.com/cloud/atlas.
2. Create a database user and whitelist your IP.
3. Click Connect → Drivers and copy the connection string.
4. Replace username, password, and cluster in MONGO_URI.
5. Set MONGO_DB to your database name.

6. Stripe and other runtime settings

The API also reads these optional settings when you enable payments or tighten defaults:

STRIPE_SECRET_KEY=sk_live_or_test_key
STRIPE_PUBLISHABLE_KEY=pk_live_or_test_key
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx
TIMEZONE=Asia/Manila
MAX_SLOTS_PER_TIME=3
CACHE_SHORT_TTL=300
CACHE_LONG_TTL=3600
BRANCH_INVITE_TOKEN_EXPIRY_DAYS=3

Use the defaults shown above unless your deployment needs different values.

Full .env Reference

The canonical variable reference lives in the Installation doc. The sections above explain how to obtain credentials for each service.