Summary

This RFC proposes a standardized approach to managing timezone configurations across Coder deployments, including database interactions and user interfaces. The objective is to ensure a consistent timezone configuration that supports deployment-level and user-level needs without reliance on environment-specific settings that may vary across replicas and clusters.

Background

Currently, there is no deployment-wide or user-wide timezone configuration in Coder. Timestamps are typically stored in UTC, yet displayed timezones can differ across environments and users, resulting in inconsistent data views, particularly in metrics and insights. One example is the DAU graph, which gets different results based on the timezone of the user viewing it.

Goals

• Consistent Deployment-wide Timezone: Ensure all Coder components operate with a unified timezone setting.
• User-Level Timezone Settings: Allow user-configured timezone settings for personalized views, especially in UI elements.
• Clear Database Handling: Store all timestamps in UTC and adjust timezones only when displaying data to the user.
• UI Transparency: Enable configuration of timezone settings within the Coder UI to improve visibility and manageability.

Proposed Solution

1. Database Timezone Consistency

• Timestamp Storage: Store all timestamps in PostgreSQL as timestamptz in UTC.
• Timestamp Retrieval: Retrieve timestamps from the database in UTC and convert to the appropriate timezone only when displaying data.

2. Deployment-Level Timezone Configuration

• Definition: Define a deployment-wide timezone that applies uniformly across the Coder environment for consistency in insights, metrics, and system-level timestamps.
• Implementation:
  • Environment Variable (TZ): Continue allowing the TZ environment variable to set the initial deployment timezone, but enable a dedicated configuration within the Coder UI for transparency.
  • Fallback Behavior: Default to UTC if the configured timezone is invalid or cannot be retrieved.

3. User-Level Timezone Settings

• Purpose: Allow users to select a timezone for personalized adjustments, which will be reflected in:
  • Autostart and Autostop schedules
  • UI and CLI timestamp displays
• Configuration Location: Add a timezone setting within user account settings, enabling each user to select their preferred timezone.

4. Display Handling

• Insights and Metrics: Default to the deployment-level timezone for aggregated metrics and data visualizations (e.g., DAUs), ensuring a unified view for all users.
• User-Specific Data: Adjust based on the user's account-level timezone for individual settings (like autostart/stop times).

5. UI Configuration and Management

• Deployment Settings UI: Expose the deployment-wide timezone setting in the Coder UI, allowing administrators to view and adjust the timezone without relying solely on the TZ environment variable.
• User Account Settings UI: Include a timezone configuration option in user account settings, ensuring user-level timezone preferences are respected across all UI and CLI displays.

Open Questions

• Should the deployment-wide timezone be configurable at the organization level or a global setting across the deployment?
• What fallback should be implemented if neither the TZ environment variable nor the UI configuration is available or valid?
• Is there a value in providing a user-level TZ setting?