Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configs

The configuration system in Kinesis API allows you to control and customize various aspects of the platform. These settings determine how the system behaves, what features are available, and how components interact with each other.

Accessing Configs

You can access and modify configuration settings from the Configs page in the web interface:

  1. Log in to your Kinesis API instance
  2. Navigate to /web/configs in your browser
  3. You'll see a list of all available configuration options

Configs Page

Configuration Categories

Configuration items in Kinesis API are grouped into several categories for the purpose of this documentation:

  • Environment Settings: Control the overall environment context
  • System Identifiers: Determine how the system identifies itself
  • URL Configuration: Define endpoints and access points
  • Security Settings: Control authentication and security parameters
  • SMTP Configuration: Settings for email functionality
  • Resource Limits: Define system resource boundaries
  • Feature Toggles: Enable or disable specific features

Core Configuration Options

Environment Settings

ENV

  • Default: dev
  • Description: The environment context in which the platform is being used.
  • Possible Values: dev (Development), staging (Staging/Testing), prod (Production)
  • Impact: Primarily used for identification and logging; has minimal impact on system behavior.

System Identifiers

PROJECT_NAME

  • Default: Kinesis API
  • Description: The name by which the platform is identified in the UI and emails.
  • Impact: Appears in the user interface, email templates, and other user-facing areas.

URL Configuration

API_URL

  • Default: Determined during installation
  • Description: The base URL where API endpoints are accessible.
  • Example: https://api.example.com
  • Impact: Used as the base for all API communication and for generating links.

API_PRE

  • Default: Empty
  • Description: A prefix for all API routes.
  • Example: Setting this to /api/v1 would change endpoint paths from /user/login to /api/v1/user/login
  • Impact: Affects how all API endpoints are accessed.

FRONT_URL

  • Default: [API_URL]/web
  • Description: The URL where users access the web interface.
  • Example: https://api.example.com/web
  • Impact: Used for redirects and generating links to the web interface.

Security Settings

INIT_CODE

  • Default: code
  • Description: The security code required when calling the /init endpoint.
  • Impact: Protects against unauthorized initialization of the system.

JWT_EXPIRE

  • Default: 3600 (1 hour)
  • Description: The lifetime of JWT authentication tokens in seconds.
  • Common Values:
    • 3600 (1 hour)
    • 86400 (24 hours)
    • 604800 (1 week)
  • Impact: Determines how frequently users need to reauthenticate.

CORS_WHITELIST

  • Default: Empty
  • Description: A comma-separated list of domains allowed to make cross-origin requests.
  • Example: example.com,api.example.com or * (allow all)
  • Impact: Critical for security; controls which external domains can access your API.

TOKEN_KEY

  • Default: Automatically generated during initialization
  • Description: The encryption key used for generating and validating JWT tokens.
  • Impact: Critical for security; changing this will invalidate all existing JWT tokens, forcing all users to log in again.

SMTP Configuration

These settings are required for user registration, password reset, and other email functionality.

SMTP_USERNAME

  • Default: Empty
  • Description: The username for SMTP server authentication.
  • Impact: Required for sending emails from the system.

SMTP_FROM_USERNAME

  • Default: Same as SMTP_USERNAME
  • Description: The email address that appears in the "From" field.
  • Impact: Affects how email recipients see the sender.

SMTP_PASSWORD

  • Default: Empty
  • Description: The password for SMTP server authentication.
  • Impact: Required for sending emails from the system.

SMTP_HOST

  • Default: Empty
  • Description: The hostname or IP address of the SMTP server.
  • Examples: smtp.gmail.com, smtp.office365.com
  • Impact: Determines which email server handles outgoing mail.

SMTP_PORT

  • Default: 587
  • Description: The port used to connect to the SMTP server.
  • Common Values: 25, 465, 587
  • Impact: Must match the requirements of your SMTP server.

SMTP_MECHANISM

  • Default: PLAIN
  • Description: The authentication mechanism for the SMTP server.
  • Options: PLAIN, LOGIN, XOAUTH2
  • Impact: Must match the authentication method supported by your SMTP server.

SMTP_STARTTLS

  • Default: true
  • Description: Whether to use STARTTLS when connecting to the SMTP server.
  • Impact: Security feature for encrypted email transmission.

SUPPORT_EMAIL

  • Default: support@kinesis.world
  • Description: The email address where contact form submissions are sent.
  • Impact: Determines where user inquiries are directed.

SMTP_FAKE_RECIPIENT

  • Default: hello@kinesis.world
  • Description: The email address used for testing SMTP configurations.
  • Impact: Used when testing email delivery; emails sent during testing will be addressed to this recipient.

Resource Limits

UPLOAD_SIZE

  • Default: 2048 (2 MB)
  • Description: Maximum allowed size for file uploads in kilobytes.
  • Impact: Affects media uploads and other file-related operations.

Feature Toggles

INITIAL_SETUP_DONE

  • Default: false (before setup), true (after setup)
  • Description: Indicates whether the initial setup process has been completed.
  • Impact: Controls whether the setup wizard appears on login.

Custom Configuration Items

In addition to the built-in configuration options, Kinesis API allows you to create and manage your own custom configuration settings:

Adding Custom Configs

  1. On the Configs page, click the "Add Config" button
  2. Enter a unique key name (use uppercase and underscores for consistency, e.g., MY_CUSTOM_CONFIG)
  3. Enter the value for your configuration
  4. Click "Save" to create the new configuration

Important Disclaimers

⚠️ Caution: Modifying or deleting configuration items can have serious consequences for your Kinesis API instance. Incorrect changes may lead to system instability, security vulnerabilities, or complete system failure. Be particularly careful when modifying:

  • Security-related settings like TOKEN_KEY
  • URL configurations like API_URL or API_PRE
  • SMTP settings that enable email functionality

Always test changes in a non-production environment first, and ensure you understand the purpose and impact of each configuration item before modifying it.

Managing Configuration Items

Modifying Configs

To modify a configuration:

  1. Find the config you want to change in the list
  2. Click the edit button (pencil icon) next to it
  3. Enter the new value in the input field
  4. Click "Save" to apply the change

Most configuration changes take effect immediately, but some may require a system restart.

Deleting Configs

You can delete configuration items that are no longer needed:

  1. Find the config you want to delete in the list
  2. Click the delete button (trash icon) next to it
  3. Confirm the deletion when prompted

Configuration History

Kinesis API maintains a history of configuration changes, including:

  • What was changed
  • When it was changed
  • Who made the change

This audit trail is valuable for troubleshooting and compliance purposes.

Best Practices

  1. Environment-Specific Settings: Use different configuration items for development, staging, and production environments
  2. Security Configs: Regularly rotate sensitive settings like INIT_CODE
  3. SMTP Testing: Always test email settings after changes using the "Test SMTP" function
  4. Documentation: Keep a record of non-default configuration items and why they were changed
  5. Review Regularly: Periodically review configuration items to ensure they remain appropriate