Environment variables

Hayon reads its configuration from environment variables at startup. The backend validates all required variables immediately — if any are missing, the process throws an error and exits. This page documents every variable, grouped by category.

Frontend variables use the NEXT_PUBLIC_ prefix and are the only variables that are sent to the browser. All other variables are backend-only and must never be exposed to the client.

Backend environment variables

Create a .env file at backend/.env. All variables in this section are required unless marked as optional.

Application

Core settings that control the server’s runtime behaviour.

Variable	Description	Required	Example
`NODE_ENV`	Runtime environment. Controls HTTPS setup and trust proxy settings.	Required	`development` or `production`
`PORT`	Port the Express server listens on. Defaults to `5000` if not set.	Optional	`5000`
`FRONTEND_URL`	Full URL of the frontend application. Used for CORS and Socket.IO origin validation.	Required	`http://localhost:3000`
`BACKEND_URL`	Full URL of the backend itself. Used to construct callback URLs in development.	Required	`https://dev.hayon.site:5000`

NODE_ENV detail

When NODE_ENV=production, the server:

Enables Express trust proxy
Creates a plain HTTP server (HTTPS is terminated at Nginx)

When NODE_ENV=development, the server creates an HTTPS server directly using local SSL certificates (dev.hayon.site+2-key.pem and dev.hayon.site+2.pem).

FRONTEND_URL detail

This value is used in two places:

The CORS middleware — only requests from this origin are allowed.
The Socket.IO server — only connections from this origin are accepted.

In production, set this to your Vercel deployment URL (e.g., https://app.yourdomain.com).

Database (MongoDB)

Variable	Description	Required	Example	Where to get it
`MONGODB_URI`	MongoDB connection string. Supports both local and Atlas connections.	Required	`mongodb://localhost:27017/hayon`	Your local MongoDB instance or the Connect dialog in MongoDB Atlas

For MongoDB Atlas, your connection string will look like: mongodb+srv://username:[email protected]/hayonInclude the database name (/hayon) at the end of the URI to ensure Mongoose connects to the correct database.

Authentication (JWT)

Hayon uses separate access and refresh token secrets for enhanced security.

Variable	Description	Required	Example	Where to get it
`ACCESS_TOKEN_SECRET`	Secret used to sign short-lived access JWTs.	Required	`a-long-random-string`	Generate with `openssl rand -hex 64`
`REFRESH_TOKEN_SECRET`	Secret used to sign long-lived refresh JWTs. Must differ from `ACCESS_TOKEN_SECRET`.	Required	`another-long-random-string`	Generate with `openssl rand -hex 64`
`JWT_EXPIRES_IN`	Access token expiry duration. Accepts any value accepted by the `jsonwebtoken` library.	Optional	`7d`	Set to your preference (e.g., `15m`, `1h`, `7d`)

Use a different secret for ACCESS_TOKEN_SECRET and REFRESH_TOKEN_SECRET. Both must be long, random strings. Never use the same value for both.

Google OAuth

Used for Google Sign-In (Passport.js strategy) and the Gemini AI integration.

Variable	Description	Required	Example	Where to get it
`GOOGLE_CLIENT_ID`	OAuth 2.0 client ID from Google Cloud.	Required	`123456789-xxxx.apps.googleusercontent.com`	APIs & Services > Credentials in the Google Cloud Console
`GOOGLE_CLIENT_SECRET`	OAuth 2.0 client secret.	Required	`GOCSPX-xxxx`	Same location as the client ID
`GOOGLE_CALLBACK_URL`	Redirect URI registered in the Google Cloud Console. Must match exactly.	Required	`http://localhost:5000/api/auth/google/callback`	Set in Authorised redirect URIs when creating the OAuth client

Cache (Redis)

Hayon uses Redis for caching and session data. The client is configured using host and port separately.

Variable	Description	Required	Example	Where to get it
`REDIS_HOST`	Hostname or IP address of the Redis server.	Required	`localhost`	Your local Redis instance or hosted Redis provider
`REDIS_PORT`	Port the Redis server is listening on.	Required	`6379`	Default Redis port is `6379`
`REDIS_PASSWORD`	Password for Redis authentication. Leave empty for unauthenticated local instances.	Optional	`your-redis-password`	Set in `redis.conf` or your hosted Redis provider dashboard

Message queue (RabbitMQ)

RabbitMQ is used as the message broker for scheduling and processing posts in background workers.

Variable	Description	Required	Example	Where to get it
`RABBITMQ_URL`	AMQP connection URL for RabbitMQ.	Required	`amqp://localhost:5672`	Your local RabbitMQ instance. For hosted services (e.g., CloudAMQP), copy the connection URL from the dashboard.

If RABBITMQ_URL points to an unavailable broker, the backend will fail to start and post publishing will not work. Ensure RabbitMQ is running before starting the backend.

Storage (AWS S3)

All media uploads (post images, profile photos) are stored in an S3 bucket.

Variable	Description	Required	Example	Where to get it
`AWS_ACCESS_KEY_ID`	AWS IAM access key ID with S3 permissions.	Required	`AKIAIOSFODNN7EXAMPLE`	IAM > Users > Security credentials in the AWS Console
`AWS_SECRET_ACCESS_KEY`	AWS IAM secret access key.	Required	`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`	Shown once when you create the access key in IAM
`AWS_REGION`	AWS region where your S3 bucket is located.	Required	`us-east-1`	The region shown in the S3 bucket details
`AWS_S3_BUCKET_NAME`	Name of the S3 bucket where media files are stored.	Required	`hayon-media-prod`	The bucket name in S3 > Buckets

For production, use an IAM policy scoped to only the specific S3 bucket rather than AmazonS3FullAccess. This limits the blast radius if the credentials are ever compromised.

Payments (Stripe)

Hayon uses Stripe for subscription management. The platform supports free and pro plans.

Variable	Description	Required	Example	Where to get it
`STRIPE_SECRET_KEY`	Stripe API secret key. Use `sk_test_...` in development and `sk_live_...` in production.	Required	`sk_test_51xxx`	Developers > API keys in the Stripe Dashboard
`STRIPE_PUBLISHABLE_KEY`	Stripe publishable key. Sent to the frontend for client-side Stripe.js initialisation.	Required	`pk_test_51xxx`	Same location as the secret key
`STRIPE_WEBHOOK_SECRET`	Signing secret for validating incoming Stripe webhook events.	Required	`whsec_xxx`	Developers > Webhooks — shown when you create or view a webhook endpoint
`STRIPE_PRO_PRICE_ID`	Stripe Price ID for the Pro subscription plan.	Required	`price_1xxx`	Products > [Your product] > Pricing in the Stripe Dashboard

Setting up the Stripe webhook

In the Stripe Dashboard, go to Developers > Webhooks.
Click Add endpoint.
Set the endpoint URL to https://your-backend-domain/api/payments/webhook.
Select the events you want to receive: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed.
Click Add endpoint and copy the signing secret.
Set STRIPE_WEBHOOK_SECRET to this value.

For local testing, use the Stripe CLI to forward webhook events:

stripe listen --forward-to localhost:5000/api/payments/webhook

AI (Gemini)

Hayon uses Google Gemini to generate platform-specific captions for posts.

Variable	Description	Required	Example	Where to get it
`GEMINI_API_KEY`	API key for the Google Gemini Generative Language API.	Required	`AIzaSyXxxx`	APIs & Services > Credentials in the Google Cloud Console — create an API key with the Generative Language API enabled

Email

Hayon sends transactional emails (e.g., OTP codes) via Gmail using Nodemailer.

Variable	Description	Required	Example	Where to get it
`EMAIL_USER`	Gmail address used to send transactional emails.	Required	`[email protected]`	Your Gmail account
`EMAIL_PASS`	Gmail App Password (not your Google account password). Required when 2FA is enabled.	Required	`abcd efgh ijkl mnop`	Google Account > Security > App passwords

You must enable 2-Step Verification on your Google account before you can create an App Password. Standard Gmail passwords will not work with Nodemailer.

Hayon supports connecting multiple social platforms. Each requires its own OAuth credentials.

Meta (Facebook & Instagram)

Variable	Description	Required	Example
`META_APP_ID`	Meta developer app ID	Required	`1234567890`
`META_APP_SECRET`	Meta developer app secret	Required	`abc123def456`
`META_REDIRECT_URI`	OAuth callback URL registered in the Meta app	Required	`http://localhost:5000/api/platform/meta/callback`

Obtain credentials from the Meta for Developers portal.

Threads

Variable	Description	Required	Example
`THREADS_APP_ID`	Threads app ID from Meta’s developer portal	Required	`1234567890`
`THREADS_APP_SECRET`	Threads app secret	Required	`abc123def456`
`THREADS_REDIRECT_URI`	OAuth callback URL	Required	`http://localhost:5000/api/platform/threads/callback`

Threads uses Meta’s developer platform. Configure in the Meta for Developers portal.

Tumblr

Variable	Description	Required	Example
`TUMBLR_CONSUMER_KEY`	Tumblr OAuth 1.0a consumer key	Required	`abcdefghijklmnopqrstuvwxyz`
`TUMBLR_CONSUMER_SECRET`	Tumblr OAuth 1.0a consumer secret	Required	`abcdefghijklmnopqrstuvwxyz`

Obtain from the Tumblr Developer Apps page.

Mastodon

Variable	Description	Required	Example
`MASTODON_CLIENT_KEY`	Mastodon OAuth client key	Required	`abc123...`
`MASTODON_CLIENT_SECRET`	Mastodon OAuth client secret	Required	`xyz789...`
`MASTODON_CALLBACK_URL`	OAuth callback URL	Required	`http://localhost:5000/api/platform/mastodon/callback`
`MASTODON_INSTANCE_URL`	The Mastodon instance to connect to	Required	`https://mastodon.social`

Monitoring

Variable	Description	Required	Example	Where to get it
`BETTER_STACK_TOKEN`	Better Stack (Logtail) ingestion token for structured log shipping.	Required	`your-logtail-token`	Sources in the Better Stack Dashboard

Frontend environment variables

Create a .env.local file at frontend/.env.local. Next.js reads this file automatically.

Variable	Description	Required	Example	Where to get it
`NEXT_PUBLIC_API_BASE_URL`	Base URL of the running Hayon backend API. All HTTP and WebSocket requests are sent to this URL.	Required	`http://localhost:5000`	The host and port where your backend is running
`NEXT_PUBLIC_GOOGLE_CLIENT_ID`	Google OAuth 2.0 client ID used to initialise the Google Sign-In button in the browser. Must match the backend `GOOGLE_CLIENT_ID`.	Required	`123456789-xxxx.apps.googleusercontent.com`	APIs & Services > Credentials in the Google Cloud Console

NEXT_PUBLIC_ variables are embedded into the browser bundle at build time. Never prefix sensitive secrets (private keys, webhook secrets) with NEXT_PUBLIC_.

Quick reference: all variables

Full .env template (backend)

# Application
NODE_ENV=development
PORT=5000
FRONTEND_URL=http://localhost:3000
BACKEND_URL=https://dev.hayon.site:5000

# Database
MONGODB_URI=mongodb://localhost:27017/hayon

# Authentication
ACCESS_TOKEN_SECRET=
REFRESH_TOKEN_SECRET=
JWT_EXPIRES_IN=7d

# Google OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URL=http://localhost:5000/api/auth/google/callback

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# RabbitMQ
RABBITMQ_URL=amqp://localhost:5672

# AWS S3
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1
AWS_S3_BUCKET_NAME=

# Stripe
STRIPE_SECRET_KEY=sk_test_
STRIPE_PUBLISHABLE_KEY=pk_test_
STRIPE_WEBHOOK_SECRET=whsec_
STRIPE_PRO_PRICE_ID=price_

# Email
EMAIL_USER=
EMAIL_PASS=

# AI
GEMINI_API_KEY=

# Meta
META_APP_ID=
META_APP_SECRET=
META_REDIRECT_URI=http://localhost:5000/api/platform/meta/callback

# Threads
THREADS_APP_ID=
THREADS_APP_SECRET=
THREADS_REDIRECT_URI=http://localhost:5000/api/platform/threads/callback

# Tumblr
TUMBLR_CONSUMER_KEY=
TUMBLR_CONSUMER_SECRET=

# Mastodon
MASTODON_CLIENT_KEY=
MASTODON_CLIENT_SECRET=
MASTODON_CALLBACK_URL=http://localhost:5000/api/platform/mastodon/callback
MASTODON_INSTANCE_URL=https://mastodon.social

# Monitoring
BETTER_STACK_TOKEN=

Full .env.local template (frontend)

NEXT_PUBLIC_API_BASE_URL=http://localhost:5000
NEXT_PUBLIC_GOOGLE_CLIENT_ID=

Get Started

Core Features

Platform Integrations

Subscriptions & Billing

Administration

Self-Hosting

Environment variables

Backend environment variables

Application

Database (MongoDB)

Authentication (JWT)

Google OAuth

Cache (Redis)

Message queue (RabbitMQ)

Storage (AWS S3)

Payments (Stripe)

AI (Gemini)

Email

Monitoring

Frontend environment variables

Quick reference: all variables

Build docs developers (and LLMs) love

Get Started

Core Features

Platform Integrations

Subscriptions & Billing

Administration

Self-Hosting

​Backend environment variables

​Application

​Database (MongoDB)

​Authentication (JWT)

​Google OAuth

​Cache (Redis)

​Message queue (RabbitMQ)

​Storage (AWS S3)

​Payments (Stripe)

​AI (Gemini)

​Email

​Social platform integrations

​Monitoring

​Frontend environment variables

​Quick reference: all variables

Build docs developers (and LLMs) love

Backend environment variables

Application

Database (MongoDB)

Authentication (JWT)

Google OAuth

Cache (Redis)

Message queue (RabbitMQ)

Storage (AWS S3)

Payments (Stripe)

AI (Gemini)

Email

Social platform integrations

Monitoring

Frontend environment variables

Quick reference: all variables