Configuration

The server can be configured via command line arguments, a JSON configuration file, or both. CLI arguments override config file values.

Configuration File

By default, the server looks for a config file at:

~/.config/cal-docs-server/config.json

Use --config to specify a different location:

python3 -m cal_docs_server --config /path/to/config.json

If the default config file doesn't exist, the server starts normally. If you specify a config file with --config and it doesn't exist, the server exits with an error.

Config File Format

{
  "docs": "/path/to/documentation",
  "port": 80,
  "name": "My Documentation Server",
  "tokens": "/path/to/tokens.json",
  "base_url": "https://docs.example.com"
}

Options

Option	Type	Default	Description
docs	string	required	Path to documentation root directory
port	integer	80	Port to listen on
name	string	"Documents Server"	Server name displayed on index page
tokens	string	none	Path to tokens file for upload authentication
base_url	string	none	Base URL for links in API responses

Example Configurations

Minimal Config

{
  "docs": "/var/www/docs"
}

Full Config

{
  "docs": "/var/www/docs",
  "port": 8080,
  "name": "ACME Documentation",
  "tokens": "/etc/cal-docs-server/tokens.json",
  "base_url": "https://example.com"
}

Precedence

When the same option is specified in both the config file and CLI, the CLI value wins:

# Config file has port: 80, but CLI overrides to 8080
python3 -m cal_docs_server --config config.json --port 8080

This allows you to have a base configuration and override specific values as needed.