Configuration

Configuration Guide

This document provides a comprehensive guide to configuring Heliotrope, including all available configuration options, their defaults, and usage examples.

Configuration Methods

Heliotrope supports three methods of configuration, listed in order of precedence:

1. JSON Configuration File
2. Command Line Arguments
3. Environment Variables

JSON Configuration File

You can specify a JSON configuration file using the --config argument, or by setting the USE_ENV environment variable to true and then using the HELIOTROPE_CONFIG environment variable.

Example config.json

{
    "GALLERYINFO_DB_URL": "postgresql+asyncpg://postgres_user:heliotropepasswd@localhost/heliotrope_db",
    "INFO_DB_URL": "mongodb://heliotrope:heliotropepasswd@localhost",
    "HOST": "0.0.0.0",
    "PORT": 8080,
    "WORKERS": 4,
    "DEBUG": false,
    "PRODUCTION": true,
    "INDEX_FILES": ["index-japanese.nozomi"]
}

Command Line Arguments

All configuration options can be set via command line arguments.

python -m heliotrope --help

Environment Variables

Environment variables use the HELIOTROPE_ prefix and configuration values ​​are loaded as environment variables only when HELIOTROPE_USE_ENV is set to true.

Note: List values in environment variables should be JSON-formatted strings.

export HELIOTROPE_USE_ENV='true'
export HELIOTROPE_HOST=0.0.0.0
export HELIOTROPE_PORT=8080
export HELIOTROPE_GALLERYINFO_DB_URL="postgresql+asyncpg://user:pass@localhost/db"

Configuration Options

Server Configuration

Option	Type	Default	Description
HOST	string	127.0.0.1	The hostname to listen on
PORT	integer	8000	The port of the webserver
WORKERS	integer	1	The number of worker processes to spawn
DEBUG	boolean	false	Enable debug mode
ACCESS_LOG	boolean	true	Enable access logging (use --access-log to disable)
FORWARDED_SECRET	string	""	Secret for validating forwarded headers

Application Configuration

Option	Type	Default	Description
PRODUCTION	boolean	false	Run the server in production mode
CONFIG	string	""	Path to the JSON configuration file
SENTRY_DSN	string	""	Sentry DSN for error tracking
USE_ENV	boolean	false	Use environment variables for configuration

Database Configuration

Option	Type	Default	Description
GALLERYINFO_DB_URL	string	""	database URL for gallery information (Recommend PostgresSQL)
INFO_DB_URL	string	""	MongoDB URL for additional information
USE_ATLAS_SEARCH	boolean	false	Use MongoDB Atlas Search features

Task Scheduling Configuration

Option	Type	Default	Description
REFRESH_DELAY	integer	86400	Delay between refresh ggjs tasks (seconds)