Skip to content

Configure the Server

This guide shows you how to configure a Teyaotlani server using TOML configuration files.

Prerequisites

Create a configuration file

Create a file named config.toml with your settings:

[server]
host = "localhost"
port = 3000
document_root = "./capsule"
enable_directory_listing = true

[logging]
level = "INFO"

Load the configuration

teyaotlani serve --config config.toml

from teyaotlani import ServerConfig, run_server
import asyncio

async def main():
    config = ServerConfig.from_toml("config.toml")
    await run_server(config)

asyncio.run(main())

Override configuration with CLI flags

CLI flags take precedence over configuration file values:

# Use config file but override port
teyaotlani serve --config config.toml --port 4000

# Use config file but override host
teyaotlani serve --config config.toml --host 0.0.0.0

Enable rate limiting

Protect your server from abuse with rate limiting:

[rate_limit]
enabled = true
capacity = 10        # Burst capacity
refill_rate = 1.0    # Tokens per second
retry_after = 30     # Suggested retry delay

This configuration allows 10 rapid requests, then throttles to 1 request per second. Rate-limited clients receive a 5 (server error) response with a suggested retry delay.

Set up access control

Restrict access by IP address:

[access_control]
enabled = true
allow_list = ["192.168.1.0/24", "10.0.0.0/8"]
deny_list = ["192.168.1.100/32"]
default_allow = false

Evaluation order:

  1. Deny list is checked first - matching IPs are blocked
  2. Allow list is checked second - matching IPs are allowed
  3. If no match, default_allow determines access

Configure logging

Adjust logging for your needs:

[logging]
level = "DEBUG"     # DEBUG, INFO, WARNING, ERROR
hash_ips = true     # Privacy: hash client IPs in logs
json = false        # Output JSON format for log aggregation

For production with a log aggregator:

[logging]
level = "INFO"
hash_ips = true
json = true

Bind to all interfaces

To make your server accessible from other machines:

[server]
host = "0.0.0.0"    # Listen on all interfaces
port = 300          # Standard Spartan port

Security consideration

Binding to 0.0.0.0 exposes your server to the network. Consider enabling access control or using a firewall.

Verify your configuration

Test your configuration before deploying:

# Start with debug logging to see all settings
teyaotlani serve --config config.toml --log-level DEBUG

Check the startup logs to verify your settings are applied correctly.

Complete example

Here's a production-ready configuration:

[server]
host = "0.0.0.0"
port = 300
document_root = "/var/spartan/capsule"
max_file_size = 52428800  # 50 MB
enable_directory_listing = false
index_files = ["index.gmi"]

[rate_limit]
enabled = true
capacity = 20
refill_rate = 2.0
retry_after = 60

[access_control]
enabled = false  # Using firewall instead

[logging]
level = "INFO"
hash_ips = true
json = true

Next steps