Environment Variables

Command-Line Arguments

Template Worker uses command-line arguments for runtime configuration. All arguments can be passed using the -- prefix.

Worker Type

--worker-type

enum

default:"processpool"

Type of worker to use. Options:

processpool (alias: process-pool): Uses a process pool for executing tasks. Recommended for production
threadpool (alias: thread-pool): Uses a thread pool for executing tasks
processpoolworker (alias: process-pool-worker): Single worker within a process pool (spawned automatically)
register (alias: register-commands): Registers Discord commands and exits
migrate (alias: apply-migration): Applies database migrations and exits
shell (alias: fauxpas): Spawns a Lua shell for debugging

Database Configuration

--max-db-connections

u32

default:"7"

Maximum number of connections in the PostgreSQL connection poolAdjust based on your database capacity and expected load. Each worker process/thread will create its own pool.

Worker Pool Settings

--process-workers

usize

Number of process workers to use for the process poolIf not specified, defaults to the shard count from Sandwich. Only used when worker-type is processpool.

--worker-id

usize

The worker ID to use when running as a process pool workerOnly used when worker-type is processpoolworker. Set automatically when spawned by the master process.

Runtime Tuning

--tokio-threads-master

usize

default:"10"

Number of Tokio runtime threads for the master processUsed by processpool, threadpool, and shell worker types.

--tokio-threads-worker

usize

default:"3"

Number of Tokio runtime threads for worker processesUsed by individual process pool workers. Each worker still uses a single thread for the Lua VM.

Debugging Options

--use-tokio-console

boolean

default:"false"

Enable Tokio Console for async runtime debuggingWarning: May increase resource usage. Only enable when debugging async issues.

--worker-debug

boolean

default:"false"

Enable debug logging for Lua workersProvides verbose output from Lua VM execution, useful for debugging templates.

Logging

RUST_LOG

string

default:"info"

Rust logging level configurationExamples:

template-worker=info: Info level for the main application
template-worker=debug,sqlx=warn: Debug for app, warnings for SQLx
debug: Debug level for all modules

See env_logger documentation for advanced filtering.

Process Pool Workers

MESOPHYLL_CLIENT_TOKEN

string

Authentication token for Mesophyll IPC clientRequired when running as a process pool worker (worker-type=processpoolworker). Set automatically by the master process when spawning workers.

Usage Examples

Production Deployment (Process Pool)

RUST_LOG=template-worker=info ./template-worker \
  --worker-type processpool \
  --max-db-connections 7 \
  --tokio-threads-master 10

Development (Thread Pool)

RUST_LOG=debug ./template-worker \
  --worker-type threadpool \
  --max-db-connections 3 \
  --worker-debug

Register Discord Commands

./template-worker --worker-type register

Apply Database Migrations

./template-worker --worker-type migrate

Debug Shell

RUST_LOG=debug ./template-worker \
  --worker-type shell \
  --max-db-connections 3

Process Pool Worker (Spawned Automatically)

# Spawned by master process - not typically run manually
MESOPHYLL_CLIENT_TOKEN=<token> ./template-worker \
  --worker-type processpoolworker \
  --worker-id 0 \
  --process-workers 4 \
  --max-db-connections 5

Docker Configuration

When running in Docker, set environment variables in docker-compose.yml:

template-worker:
  image: template-worker:latest
  environment:
    RUST_LOG: "template-worker=info"
  command: [
    "--worker-type", "processpool",
    "--max-db-connections", "7"
  ]

Configuration Validation

Template Worker validates configuration at startup:

Missing config.yaml file will cause immediate exit
Invalid worker type combinations (e.g., worker-id without processpoolworker) will panic
Missing required environment variables (e.g., MESOPHYLL_CLIENT_TOKEN for workers) will panic

Performance Tuning

Database Connections

For production deployments:

Process pool: --max-db-connections should be 5-10 per process
Thread pool: Can use higher values (10-20) since all threads share one pool
Monitor your PostgreSQL max_connections setting

Tokio Threads

Master process: 10 threads handles most workloads well
Worker processes: 3 threads is sufficient since Lua execution is single-threaded per worker
Increase if you see high task queue latency in Tokio Console

Process vs Thread Pool

Process pool: Better isolation, required for production, slightly higher memory usage
Thread pool: Simpler, good for development, faster startup, shared memory

Get Started

Architecture

Configuration

Deployment

Environment Variables

Command-Line Arguments

Worker Type

Database Configuration

Worker Pool Settings

Runtime Tuning

Debugging Options