Configuration

Complete reference for TimeTiles environment variables and settings.

Environment Variables

Required Variables

These must be set for TimeTiles to function:


# Database Connection
DATABASE_URL=postgresql://user:password@localhost:5432/timetiles

# Security (generate with: openssl rand -base64 32)
PAYLOAD_SECRET=your-secret-key-minimum-32-characters

Application Settings


# Environment
NODE_ENV=development|production

# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_PAYLOAD_URL=http://localhost:3000

# Logging
LOG_LEVEL=info|debug|warn|error

Geocoding Configuration

TimeTiles supports multiple geocoding providers configured through the admin panel:

Geocoding Providers

Configure providers directly in the admin interface at /dashboard/collections/geocoding-providers:

Add multiple providers with different priorities
Enable/disable providers without restart
Set API keys securely in the admin UI
Configure rate limits per provider
Tag providers for environment-specific selection (production, development, testing)

Default Setup (Development Seeding):

Nominatim (OpenStreetMap): Enabled by default, free public instance, no API key required
Google Maps: Disabled by default, configure API key in admin panel to enable
OpenCage: Disabled by default, configure API key in admin panel to enable

Supported Providers:

Google Maps: Most accurate, requires API key
OpenCage: Good alternative, requires API key
Nominatim/OpenStreetMap: Free, no API key needed

Providers are tried in priority order (lower number = higher priority).

Geocoding Settings

Configure geocoding behavior at /dashboard/globals/settings:

Enable/Disable Geocoding: Toggle geocoding globally
Provider Fallback: Enable fallback to alternative providers on failure
Selection Strategy: Priority-based or tag-based provider selection
Caching: Enable/disable geocoding cache and set TTL (days)

File Upload Configuration

Control file size limits and upload directories:


# Maximum file sizes in bytes
MAX_FILE_SIZE_AUTHENTICATED=104857600    # 100MB for authenticated users
MAX_FILE_SIZE_UNAUTHENTICATED=10485760   # 10MB for unauthenticated users

# Upload Directory Configuration
# Base directory for all uploads (relative to apps/web or absolute path)
# Subfolders are created automatically: /media and /import-files
UPLOAD_DIR=uploads
UPLOAD_TEMP_DIR=./tmp                    # Temporary directory for file processing

Rate Limiting

Configure rate limits for unauthenticated users:


RATE_LIMIT_FILE_UPLOAD=5        # 5 uploads per hour
RATE_LIMIT_PROGRESS_CHECK=100   # 100 progress checks per hour
RATE_LIMIT_API_GENERAL=50       # 50 general API requests per hour
RATE_LIMIT_WINDOW_MS=3600000    # 1 hour window in milliseconds

Batch Processing

Adjust these values to tune performance vs memory usage:


BATCH_SIZE_DUPLICATE_ANALYSIS=5000   # Memory efficient for duplicate detection
BATCH_SIZE_SCHEMA_DETECTION=10000    # Larger batches for schema building efficiency
BATCH_SIZE_EVENT_CREATION=1000       # Smaller to avoid transaction timeouts
BATCH_SIZE_DATABASE_CHUNK=1000       # Database query chunk size

Cache Configuration

Generic cache system settings:


CACHE_BACKEND=filesystem               # Cache backend: memory or filesystem
CACHE_DEFAULT_TTL=3600                 # Default cache TTL in seconds (1 hour)
CACHE_MAX_SIZE_MB=500                  # Maximum cache size in MB
CACHE_MAX_ENTRIES=1000                 # Maximum number of cache entries (memory backend)
CACHE_DIR=.cache                       # Base cache directory (filesystem backend)
CACHE_CLEANUP_INTERVAL_MS=3600000      # Cache cleanup interval (1 hour)

Geocoding Cache

Configure location cache cleanup:


GEOCODING_CACHE_CLEANUP_DAYS=90   # Days before cleaning up unused cache entries
GEOCODING_CACHE_MIN_HITS=3        # Minimum hits required to keep cache entry

URL Fetch Cache

For scheduled URL imports (outgoing requests):


URL_FETCH_CACHE_DIR=/tmp/url-fetch-cache          # Directory for URL fetch cache storage
URL_FETCH_CACHE_MAX_SIZE=104857600                # Maximum cache size in bytes (100MB)
URL_FETCH_CACHE_TTL=3600                          # Default TTL in seconds
URL_FETCH_CACHE_RESPECT_CACHE_CONTROL=true        # Respect Cache-Control headers from external APIs

Test Database Configuration

Test databases are automatically derived from DATABASE_URL:

E2E tests use: ${database}_test (e.g., timetiles_test)
Unit/Integration tests use: ${database}_test_${worker_id} (e.g., timetiles_test_1, timetiles_test_2)

No additional configuration needed - the test infrastructure handles this automatically.

Production vs Development

Development Settings (.env)


NODE_ENV=development
DATABASE_URL=postgresql://timetiles_user:timetiles_password@localhost:5432/timetiles
PAYLOAD_SECRET=dev-secret-change-in-production
LOG_LEVEL=debug

Production Settings (.env.production)


NODE_ENV=production
DATABASE_URL=postgresql://prod_user:strong_password@db.internal:5432/timetiles_prod
PAYLOAD_SECRET=<generate-with-openssl-rand-base64-32>
LOG_LEVEL=info
ENABLE_SECURITY_HEADERS=true

Configuration Files

Next.js Configuration

The apps/web/next.config.mjs file contains:

Standalone output for production
Image optimization settings
Security headers
Webpack customizations

TypeScript Configuration

Strict mode is enabled across the monorepo with shared configs in packages/typescript-config/.

Database Configuration

PostgreSQL settings can be tuned via environment variables or directly:


-- For production workloads
ALTER SYSTEM SET shared_buffers = '2GB';
ALTER SYSTEM SET effective_cache_size = '6GB';
ALTER SYSTEM SET work_mem = '64MB';
ALTER SYSTEM SET maintenance_work_mem = '512MB';
 
-- Apply changes
SELECT pg_reload_conf();

Validation

TimeTiles validates configuration on startup:

Required variables: Checks for DATABASE_URL and PAYLOAD_SECRET
Database connection: Verifies PostgreSQL is accessible
PostGIS extension: Ensures spatial functions are available

Troubleshooting Configuration

Missing Environment Variables


# Check loaded variables
make dev
# Look for warnings about missing configuration

Invalid Database URL


# Test connection
psql $DATABASE_URL -c "SELECT 1"

Geocoding Issues

Check geocoding provider configuration in the admin panel at /dashboard/collections/geocoding-providers.

To test a provider’s API key directly:


# Test Google Maps API (replace YOUR_API_KEY with the key from admin panel)
curl "https://maps.googleapis.com/maps/api/geocode/json?address=Paris&key=YOUR_API_KEY"
 
# Test OpenCage API
curl "https://api.opencagedata.com/geocode/v1/json?q=Paris&key=YOUR_API_KEY"
 
# Test Nominatim (no key required)
curl "https://nominatim.openstreetmap.org/search?q=Paris&format=json"

Dashboard

The dashboard at /dashboard provides a web interface for managing data. All authenticated users can access it, with permissions based on role:

User: Manage their own catalogs, datasets, and imports
Editor: User permissions plus access to advanced dataset configuration and branding
Admin: Full access including user management, system settings, and feature flags

Content Management

Editors and admins can manage site content through these features:

Branding

Customize site appearance in Branding (/dashboard/globals/branding):

Site Name: Displayed in header and browser tab
Site Description: Meta description for SEO
Logos: Separate uploads for light/dark themes
Favicons: Auto-generated from uploaded source images

Feature Flags

Feature flags are configured in Settings (/dashboard/globals/settings) under “Feature Flags”:

Flag	Default	Description
Allow Private Imports	On	Users can create private imports visible only to themselves
Enable Scheduled Imports	On	Users can create automated URL-based import schedules
Enable Public Registration	On	New users can self-register accounts
Enable Event Creation	On	New events can be created via imports or API
Enable Dataset Creation	On	Users can create new datasets
Enable Import Creation	On	Users can create new import jobs
Enable Scheduled Job Execution	On	Scheduled imports run automatically
Enable URL Fetch Caching	On	Cache URL fetches to reduce external requests

Scheduled Imports

Users can create automated imports that fetch data from a URL on a cron schedule.

Configuration

Enable/disable via the Enable Scheduled Imports feature flag
Users create schedules at /dashboard/collections/scheduled-imports
Each schedule specifies: URL, cron expression, target catalog/dataset, authentication (optional)

Authentication Options

Scheduled imports support several authentication methods for fetching protected URLs:

None: Public URLs with no authentication
API Key: Header or query parameter API key
Bearer Token: Authorization header with bearer token
Basic Auth: HTTP Basic authentication

URL Fetch Caching

Scheduled imports use HTTP caching (RFC 7234) to avoid re-downloading unchanged data. See Usage Limits for cache configuration.

Monitoring

View all schedules: /dashboard/collections/scheduled-imports
Check schedule health: GET /api/admin/schedule-service
System automatically cleans up stuck imports via background job

Audit Log

TimeTiles tracks user and admin actions for accountability and debugging.

What’s Tracked

20 action types across 5 domains:

Account: Login, logout, registration, email change, password change, deletion request/cancel/execute
Admin: User role change, trust level change, feature flag change
Data: Catalog/dataset/event create/update/delete
Import: Import start, import complete, import fail
System: Settings change, geocoding provider change

Privacy

IP addresses are stored for 30 days, then cleared by the audit-log-ip-cleanup background job
performedBy is only set when the acting user differs from the target user

Viewing Logs

Admin panel: /dashboard/collections/audit-log
Filter by user, action type, domain, or date range

User Data Management

TimeTiles includes self-service data management for users:

Data Export: Users can download all their data (catalogs, datasets, events, import history) as a ZIP archive from Account Settings
Account Deletion: Users can request account deletion with a 7-day grace period. Private data is permanently deleted; public data is transferred to an admin account for continuity.

Next Steps

Deploy to Production with your configuration
Setup Monitoring for your instance
Review Security Best Practices

Configuration

Environment Variables

Required Variables

Application Settings

Geocoding Configuration

Geocoding Providers

Geocoding Settings

File Upload Configuration

Rate Limiting

Batch Processing

Cache Configuration

Geocoding Cache

URL Fetch Cache

Test Database Configuration

Production vs Development

Development Settings (.env)

Production Settings (.env.production)

Configuration Files

Next.js Configuration

TypeScript Configuration

Database Configuration

Validation

Troubleshooting Configuration

Missing Environment Variables

Invalid Database URL

Geocoding Issues

Dashboard

Content Management

Pages

Navigation

Newsletter

Branding

Feature Flags

Scheduled Imports

Configuration

Authentication Options

URL Fetch Caching

Monitoring

Audit Log

What’s Tracked

Privacy

Viewing Logs

User Data Management

Next Steps