Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ptshen/timeful-plus/llms.txt

Use this file to discover all available pages before exploring further.

The fastest path to a running Timeful instance is to pull the pre-built images from GitHub Container Registry and supply a single required secret — your encryption key. The steps below have you up and reachable at http://localhost:3002 in about five minutes, including image pull time.

​
Prerequisites

Before you begin, confirm the following are available on your machine:
  • Docker 20.10+ — Install Docker
  • Docker Compose v2 — bundled with Docker Desktop; verify with docker compose version
  • openssl — available by default on macOS and most Linux distributions
  • Google Cloud account (optional) — required only for OAuth login and calendar integration; anonymous event scheduling works without it
  • At least 2 GB RAM and 10 GB free disk space for the MongoDB data volume

​
Setup Steps

1

Clone the repository

Clone the Timeful source — even when using pre-built images you need the Compose file and configuration templates:
git clone https://github.com/schej-it/timeful.app.git
cd timeful.app
Alternatively, if you only want the pre-built images without the full source, pull them directly:
docker pull ghcr.io/lillenne/timeful.app/backend:latest
docker pull ghcr.io/lillenne/timeful.app/frontend:latest
2

Create your .env file and set ENCRYPTION_KEY

Copy the example environment file and generate a cryptographically secure encryption key:
cp .env.example .env
echo "ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env
Open .env in your editor and confirm the key was written correctly. The ENCRYPTION_KEY value is used to encrypt sensitive data stored in MongoDB and is the only required variable for basic anonymous scheduling.
.env
# Minimum viable configuration
ENCRYPTION_KEY=<your-generated-base64-key>

# Premium features are enabled by default for self-hosted deployments
SELF_HOSTED_PREMIUM=true
Never commit .env to version control. The repository’s .gitignore already excludes it, but double-check before pushing.
3

(Optional) Add Google OAuth credentials

Skip this step if you only need anonymous event scheduling. To enable user accounts and Google Calendar / Outlook integration, add the following to your .env:
.env
# Google OAuth — create credentials at https://console.cloud.google.com/
# Enable: Google Calendar API + Google People API
# Authorized redirect URI: http://localhost:3002/api/auth/google/callback
CLIENT_ID=your-google-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-google-client-secret

# Microsoft OAuth — create an app registration at https://portal.azure.com/
# Authorized redirect URI: http://localhost:3002/auth
MICROSOFT_CLIENT_ID=your-azure-application-client-id
MICROSOFT_CLIENT_SECRET=your-azure-client-secret
Then update config.js (copy it from config.example.js) so the Vue frontend knows which OAuth client IDs to use:
config.js
window.__TIMEFUL_CONFIG__ = {
  googleClientId: "your-google-client-id.apps.googleusercontent.com",
  microsoftClientId: "",  // Add if using Outlook calendar integration
  disableAnalytics: false,
}
4

Start the application

Launch all three containers — MongoDB, backend API, and frontend — using the pre-built image Compose file:
docker compose -f docker-compose.ghcr.yml up -d
Or use the equivalent Makefile shortcut:
make up-ghcr
To build from source instead (useful for local development or custom patches):
docker compose up -d   # or: make up
Docker will start three containers on the timeful-network bridge network:
ContainerImageRole
timeful-mongodbmongo:6.0Persistent data store
timeful-backendghcr.io/lillenne/timeful.app/backend:latestGo/Gin REST API
timeful-frontendghcr.io/lillenne/timeful.app/frontend:latestNginx + Vue 2 SPA
5

Open the application

Once the containers are healthy, navigate to:
http://localhost:3002
The interactive API documentation is available at:
http://localhost:3002/swagger/index.html
All premium features — CSV export, response visibility controls, duplicate polls, email reminders, and sign-up form capacity limits — are automatically unlocked because SELF_HOSTED_PREMIUM=true is set by default in .env.example. No Stripe configuration is needed.

​
Verification

Confirm everything is running correctly with these two commands: 
# Check container health and status
docker compose ps

# Confirm the frontend is responding
curl -I http://localhost:3002
Expected output: 
NAME                  IMAGE                                            STATUS
timeful-mongodb       mongo:6.0                                        healthy
timeful-backend       ghcr.io/lillenne/timeful.app/backend:latest      running
timeful-frontend      ghcr.io/lillenne/timeful.app/frontend:latest     running

HTTP/1.1 200 OK
To inspect logs if something looks wrong: 
make logs          # All containers
make logs-backend  # Backend API only
make logs-db       # MongoDB only

​
Makefile Command Reference

All common lifecycle tasks are wrapped in the Makefile. Use make help to print the full list at any time.
CommandDescription
make setupInteractive setup wizard — creates .env from template
make upBuild images from source and start all services
make up-ghcrStart using pre-built GHCR images (recommended)
make downStop all running containers
make restartRestart all containers without rebuilding
make logsStream logs from all containers
make logs-backendStream backend API logs only
make logs-dbStream MongoDB logs only
make statusPrint container status table
make backupDump the schej-it database to ./backups/backup-YYYYMMDD-HHMMSS/
make restoreRestore the most recent backup (overwrites current data)
make pull-ghcrPull latest GHCR images and restart (recommended for updates)
make pullgit pull, rebuild from source, and restart
make shell-dbOpen a mongosh session inside the MongoDB container
make shell-backendOpen a shell inside the backend container
make shell-frontendOpen a shell inside the frontend container
make cleanRemove all containers and volumes — deletes all data ⚠️
make devStart with live log output attached to the terminal

​
Next Steps

Docker Self-Hosting

Production setup with Nginx reverse proxy, SSL termination, custom domains, and CORS configuration.

Configuration Reference

Complete reference for every environment variable in .env.example, including email, Stripe, and analytics options.

Troubleshooting

Solutions for common issues: OAuth redirect mismatches, port conflicts, and database connection failures.

Build docs developers (and LLMs) love

Get started for freeTalk to us