Environment Variables

Every ChurchApps project uses a .env file for local configuration. Each project includes a sample file that you copy and customize. This page covers the environment variables for APIs, web apps, and mobile apps, including how to choose between staging and local API targets.

Before You Begin

• Install the prerequisites for your project
• Clone the project repository you want to work on
• Review the Project Overview to understand which API modules your project needs

General Pattern

1. Look for dotenv.sample.txt or .env.sample in the project root.
2. Copy it to .env.
3. Edit the values as needed.

# Example for a project with .env.sample
cp .env.sample .env

# Example for a project with dotenv.sample.txt
cp dotenv.sample.txt .env

peringatan

Never commit .env files to version control. They contain secrets such as database credentials, API keys, and JWT secrets. All ChurchApps projects include .env in .gitignore, but always double-check before committing.

Choosing an API Target

The most important decision is where your frontend points for API calls. There are two options:

Option 1: Staging APIs (Recommended for Frontend Development)

Use the shared staging environment. No local API or database setup needed.

# Base URL pattern
https://api.staging.churchapps.org/{module}

# Example module URLs
https://api.staging.churchapps.org/membership
https://api.staging.churchapps.org/attendance
https://api.staging.churchapps.org/content
https://api.staging.churchapps.org/giving
https://api.staging.churchapps.org/messaging
https://api.staging.churchapps.org/doing

Option 2: Local API

Run the Api project on your machine. Requires MySQL 8.0+ with databases created for each module. See the API local setup guide.

# Base URL pattern
http://localhost:8084/{module}

# Example module URLs
http://localhost:8084/membership
http://localhost:8084/attendance
http://localhost:8084/content
http://localhost:8084/giving
http://localhost:8084/messaging
http://localhost:8084/doing

---

API Environment Variables

The core Api project (.env.sample) has the most configuration. Here are the key variables:

Shared Settings

Variable	Description	Example
ENVIRONMENT	Runtime environment	dev
SERVER_PORT	HTTP port for the local dev server	8084
ENCRYPTION_KEY	192-bit encryption key for sensitive data	aSecretKeyOfExactly192BitsLength
JWT_SECRET	Secret for signing JSON Web Tokens	jwt-secret-dev
FILE_STORE	Where to store uploaded files (disk or s3)	disk
CORS_ORIGIN	Allowed CORS origins (* for local dev)	*

Database Connection

A single base URL points the API at MySQL. The API derives one database per module (/membership, /attendance, /content, /giving, /messaging, /doing, /reporting) from this base.

Variable	Example
API_DATABASE_URL	mysql://root:password@localhost:3306

tip

Update root:password with your actual MySQL credentials. Each per-module database must exist before running the API. Use npm run initdb to create the schema for all modules, or npm run initdb:membership for a single module.

WebSocket Settings

Variable	Description	Example
SOCKET_PORT	Port for the WebSocket server	8087
SOCKET_URL	WebSocket URL for clients to connect	ws://localhost:8087

---

Web App Environment Variables

B1Admin (React + Vite)

Sample file: .env.sample

Variable	Description	Example (Staging)
REACT_APP_STAGE	Environment name	demo
PORT	Dev server port	3101
REACT_APP_API_BASE	Single base URL for all ChurchApps APIs (/membership, /attendance, /content, /giving, /messaging, /doing, /reporting are appended automatically)	https://api.staging.churchapps.org
REACT_APP_CONTENT_ROOT	Content delivery URL	https://content.staging.churchapps.org
REACT_APP_GOOGLE_ANALYTICS	Google Analytics ID (optional)	UA-123456789-1

For local API development, point the base URL at your local stack:

REACT_APP_API_BASE=http://localhost:8084

B1App (Next.js)

Sample file: .env.sample

Variable	Description	Example (Staging)
NEXT_PUBLIC_API_BASE	Single base URL for all ChurchApps APIs (/membership, /attendance, /content, /giving, /messaging, /doing, /reporting are appended automatically)	https://api.staging.churchapps.org
NEXT_PUBLIC_CONTENT_ROOT	Content delivery URL	https://staging.churchapps.org/content
NEXT_PUBLIC_CHURCH_APPS_URL	ChurchApps base URL	https://staging.churchapps.org
NEXT_PUBLIC_GOOGLE_ANALYTICS	Google Analytics ID (optional)	UA-123456789-1

info

Next.js requires the NEXT_PUBLIC_ prefix for any environment variable that needs to be available in the browser. Server-only variables do not need this prefix.

LessonsApp (Next.js)

Sample file: dotenv.sample.txt

Variable	Description	Example (Staging)
STAGE	Environment stage	staging
NEXT_PUBLIC_LESSONS_API	Lessons API URL	https://api.staging.lessons.church
NEXT_PUBLIC_CONTENT_ROOT	Content delivery URL	https://api.staging.lessons.church/content
NEXT_PUBLIC_CHURCH_APPS_URL	ChurchApps base URL	https://staging.churchapps.org

---

Mobile App Environment Variables

B1Mobile (React Native / Expo)

Sample file: dotenv.sample.txt

Variable	Description	Example (Staging)
STAGE	Environment name	dev
API_BASE	Single base URL for all ChurchApps APIs (/membership, /attendance, /content, /giving, /messaging, /doing are appended automatically)	https://api.staging.churchapps.org
LESSONS_API	Lessons API (separate host)	https://api.staging.lessons.church
CONTENT_ROOT	Content delivery URL	https://content.staging.churchapps.org
LESSONS_ROOT	Lessons site URL	https://staging.lessons.church

info

Mobile apps do not use the REACT_APP_ or NEXT_PUBLIC_ prefix. Environment variable access is handled by the Expo configuration.

---

Quick Reference: Sample File Locations

Project	Sample File
Api	.env.sample
B1Admin	.env.sample
B1App	.env.sample
B1Mobile	dotenv.sample.txt
B1Checkin	dotenv.sample.txt
LessonsApp	dotenv.sample.txt
AskApi	dotenv.sample.txt