Configure Timeful: Environment Variables and config.js

Timeful has two configuration surfaces: a .env file consumed by the Go backend (and forwarded into Docker Compose), and a config.js file loaded at runtime by the Vue.js frontend. Copy .env.example to .env and config.example.js to config.js, then fill in only the values your deployment needs.

cp .env.example .env
cp config.example.js config.js

Backend — `.env` Reference

Required

ENCRYPTION_KEY

string

required

Used to encrypt sensitive data (OAuth tokens, calendar credentials) stored in MongoDB. Generate a secure value with:

openssl rand -base64 32

Without this key, the backend will not start. Store it securely — rotating this key requires re-encrypting all stored tokens.

Google OAuth

CLIENT_ID

string

Google OAuth 2.0 Client ID. Required to enable user accounts and Google Calendar integration. If left empty, users can still create and join events anonymously.Obtain from Google Cloud Console → APIs & Services → Credentials.Required scopes:

https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/contacts.readonly

CLIENT_SECRET

string

Google OAuth 2.0 Client Secret. Must be set whenever CLIENT_ID is set.

Microsoft / Outlook OAuth

MICROSOFT_CLIENT_ID

string

Microsoft Entra ID (formerly Azure AD) Application (client) ID. Required for Outlook calendar integration. Register your app at portal.azure.com → Azure Active Directory → App registrations.Required Graph API permissions: offline_access, User.Read, Calendars.Read.

MICROSOFT_CLIENT_SECRET

string

Microsoft Entra ID client secret value. Must be set whenever MICROSOFT_CLIENT_ID is set. Client secrets expire — create a reminder before the expiry date.

Email Notifications

GMAIL_APP_PASSWORD

string

Gmail App Password for sending transactional email notifications. Requires 2-factor authentication enabled on the sending account.Create one at myaccount.google.com/apppasswords.

SCHEJ_EMAIL_ADDRESS

string

Gmail address that matches the GMAIL_APP_PASSWORD. Both variables must be set for email sending to work.

Listmonk (Email Campaigns)

LISTMONK_URL

string

Base URL of your self-hosted Listmonk instance, e.g. http://listmonk:9000.

LISTMONK_USERNAME

string

Listmonk admin username.

LISTMONK_PASSWORD

string

Listmonk admin password.

LISTMONK_LIST_ID

string

Numeric ID of the mailing list to subscribe new users to.

LISTMONK_INITIAL_EMAIL_REMINDER_ID

string

Listmonk transactional template ID for the initial event reminder email.

This variable is defined in .env.example but is not forwarded to the backend container in the default docker-compose.yml or docker-compose.ghcr.yml. To use it, add - LISTMONK_INITIAL_EMAIL_REMINDER_ID=${LISTMONK_INITIAL_EMAIL_REMINDER_ID:-} to the backend service’s environment block in your Compose file.

LISTMONK_SECOND_EMAIL_REMINDER_ID

string

Listmonk transactional template ID for the second event reminder email.

This variable is defined in .env.example but is not forwarded in the default Compose files. Add it to the backend environment block as needed.

LISTMONK_FINAL_EMAIL_REMINDER_ID

string

Listmonk transactional template ID for the final event reminder email.

This variable is defined in .env.example but is not forwarded in the default Compose files. Add it to the backend environment block as needed.

Slack

SLACK_DEV_WEBHOOK_URL

string

Incoming webhook URL for development/staging alerts.

SLACK_PROD_WEBHOOK_URL

string

Incoming webhook URL for production monitoring and alerts.

Payments

STRIPE_API_KEY

string

Stripe secret key (e.g. sk_live_…). Only needed when you want to sell premium features via Stripe. Has no effect when SELF_HOSTED_PREMIUM=true.

SELF_HOSTED_PREMIUM

string

default:"true"

When set to true, all users on this instance automatically receive premium features with no payment required. Ideal for organisations hosting Timeful for their own team. Defaults to true in both docker-compose.yml and docker-compose.ghcr.yml.Set to false and configure STRIPE_API_KEY if you intend to sell subscriptions.

Google Cloud

SERVICE_ACCOUNT_KEY_PATH

string

Filesystem path inside the backend container to a Google Cloud service account key JSON file. Required only for advanced features such as Cloud Tasks.

Analytics

VUE_APP_POSTHOG_API_KEY

string

PostHog project API key for backend analytics. Leave empty to disable. See also posthogApiKey in config.js for the frontend-side key.

This variable is present in .env.example but is not forwarded to the backend container in the default Compose files. Add - VUE_APP_POSTHOG_API_KEY=${VUE_APP_POSTHOG_API_KEY:-} to the backend environment block if you need it.

Docker Networking

BACKEND_HOST

string

default:"backend"

Hostname the Nginx frontend container uses to proxy /api and /sockets/ requests to the backend. In the default Compose setup this is the backend service name. Change it if you run the backend outside the Compose network or rename the service.

BACKEND_PORT

string

default:"3002"

Port the backend listens on inside the container. Matches the expose directive in docker-compose.yml.

Custom Domains & CORS

BASE_URL

string

The public URL where your Timeful instance is reachable, e.g. https://timeful.example.com. Used to build:

Google OAuth redirect URI: {BASE_URL}/api/auth/google/callback
Email links and event share URLs
Stripe payment redirect URLs

Required if you serve Timeful from anything other than http://localhost:3002.

CORS_ALLOWED_ORIGINS

string

Comma-separated list of allowed CORS origins, e.g. https://timeful.example.com,https://www.example.com. Localhost origins (:3002, :8080) are always permitted.When this variable is not set, the backend allows the default Timeful production domains plus localhost. When set, those default domains are replaced by your custom list, so include every origin you need.

MongoDB

MONGO_URI

string

default:"mongodb://mongodb:27017"

Full MongoDB connection string. The default resolves to the mongodb service within the Compose network. Override this to point at an external Atlas cluster or a separately managed MongoDB instance.

MONGO_DB_NAME

string

default:"schej-it"

MongoDB database name. Defaults to schej-it and is pre-configured in both Compose files.

Frontend — `config.js` Reference

The frontend reads window.__TIMEFUL_CONFIG__ from config.js, which is bind-mounted into the Nginx container at startup. No rebuild is needed after changing this file — just restart the frontend container.

window.__TIMEFUL_CONFIG__ = {
  googleClientId: '',
  microsoftClientId: '',
  posthogApiKey: '',
  disableAnalytics: false,
  mapboxApiKey: '',
}

Key	Type	Description
`googleClientId`	`string`	Google OAuth Client ID. Must match `CLIENT_ID` in `.env`. Required for Google sign-in and calendar integration.
`microsoftClientId`	`string`	Microsoft Entra ID Application (client) ID. Must match `MICROSOFT_CLIENT_ID` in `.env`. Leave empty to hide the Outlook integration button.
`posthogApiKey`	`string`	PostHog frontend project API key. Leave empty to disable frontend analytics.
`disableAnalytics`	`boolean`	Set to `true` to completely disable Google Tag Manager, PostHog, and all other analytics. Recommended for privacy-focused or internal deployments.
`mapboxApiKey`	`string`	Mapbox public API key. Enables address autocomplete for in-person event locations. Free tier includes 100,000 requests/month. Leave empty to disable.

Setup Examples

Minimal — Anonymous Use Only

No user accounts, no calendar integration. Users can still create and fill in availability polls anonymously.

# .env
ENCRYPTION_KEY=<output of: openssl rand -base64 32>

docker compose -f docker-compose.ghcr.yml up -d

Full — User Accounts + Calendar Integration

# .env
ENCRYPTION_KEY=<output of: openssl rand -base64 32>
CLIENT_ID=123456789-abc.apps.googleusercontent.com
CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx
MICROSOFT_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
MICROSOFT_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SELF_HOSTED_PREMIUM=true

// config.js
window.__TIMEFUL_CONFIG__ = {
  googleClientId: '123456789-abc.apps.googleusercontent.com',
  microsoftClientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  posthogApiKey: '',
  disableAnalytics: true,
  mapboxApiKey: '',
}

config.js contains your OAuth Client IDs, which are visible to the browser. Never put Client Secrets in config.js — those must stay in .env only, and .env should never be committed to version control.

Docker Deployment

Start the stack and understand the container architecture

Production Setup

Reverse proxy, custom domain, and HTTPS configuration

Getting Started

Self-Hosting

Features

Deployment Guides

Operations

Configure Timeful: Environment Variables and config.js

Backend — `.env` Reference

Required

Google OAuth

Microsoft / Outlook OAuth

Email Notifications

Listmonk (Email Campaigns)

Slack

Payments

Google Cloud

Analytics

Docker Networking

Custom Domains & CORS

MongoDB

Frontend — `config.js` Reference

Setup Examples

Minimal — Anonymous Use Only

Full — User Accounts + Calendar Integration

Docker Deployment

Production Setup

Build docs developers (and LLMs) love

Getting Started

Self-Hosting

Features

Deployment Guides

Operations

Documentation Index

​Backend — .env Reference

​Required

​Google OAuth

​Microsoft / Outlook OAuth

​Email Notifications

​Listmonk (Email Campaigns)

​Slack

​Payments

​Google Cloud

​Analytics

​Docker Networking

​Custom Domains & CORS

​MongoDB

​Frontend — config.js Reference

​Setup Examples

​Minimal — Anonymous Use Only

​Full — User Accounts + Calendar Integration

Docker Deployment

Production Setup

Build docs developers (and LLMs) love

Backend — `.env` Reference

Required

Google OAuth

Microsoft / Outlook OAuth

Email Notifications

Listmonk (Email Campaigns)

Slack

Payments

Google Cloud

Analytics

Docker Networking

Custom Domains & CORS

MongoDB

Frontend — `config.js` Reference

Setup Examples

Minimal — Anonymous Use Only

Full — User Accounts + Calendar Integration