Template Worker Deployment

This guide covers deploying the template-worker service in both Docker and native (systemd) environments.

# From the repository root
docker build -f Dockerfile -t template-worker:latest .

docker run -p 60000:60000 \
  -v /path/to/config:/app/config \
  template-worker:latest

[Unit]
Description=AntiRaid Template Worker
After=network.target postgresql.service

[Service]
Type=simple
User=antiraid
Group=antiraid
WorkingDirectory=/opt/antiraid
ExecStart=/opt/antiraid/template-worker
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Copy service file
sudo cp data/systemd-example/splashtail-staging-templateworker.service \
  /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable and start
sudo systemctl enable splashtail-staging-templateworker
sudo systemctl start splashtail-staging-templateworker

Configuration

Configuration File

The service is configured via:

• Service config file: config.yaml or config.docker.yaml
• Environment variables for sensitive data
• Runtime parameters for VM distribution strategy selection

Required Configuration

• Database connection settings
• Redis connection (if used)
• HTTP server port (default: 60000)
• VM distribution strategy
• Resource limits

Environment Variables

Common environment variables:

• Database connection strings
• API keys and secrets
• Logging configuration
• Feature flags

Health & Monitoring

Health Endpoints

The service provides:

• Health Check: Basic health status endpoint
• Metrics: Prometheus metrics (if configured)

Monitoring

Monitor service health using:

# Docker
docker ps  # Check container status
docker logs -f <template-worker-container>

# Systemd
systemctl status splashtail-staging-templateworker
journalctl -u splashtail-staging-templateworker -f

Logging

The service uses structured logging:

• Log levels: ERROR, WARN, INFO, DEBUG, TRACE
• JSON format (configurable)
• Log rotation support

Networking

Port Configuration

• Default port: 60000
• Configurable via configuration file
• Internal only in Docker deployments (not exposed to host)

Network Requirements

• Access to PostgreSQL database
• Access to Redis (if used)
• Communication with Bot service
• Communication with API service (if needed)

Troubleshooting

Common Issues

1. Port Already in Use

   • Check if another service is using port 60000
   • Change port in configuration

2. Database Connection Failed

   • Verify database is running
   • Check connection string in config
   • Verify network connectivity

3. VM Creation Failures

   • Check resource limits
   • Verify builtins and templating-types are available
   • Check logs for specific errors

4. High Memory Usage

   • Monitor VM count and memory per VM
   • Adjust resource limits if needed
   • Consider VM cleanup strategies

Debug Mode

Enable debug logging:

# Set log level
RUST_LOG=debug template-worker

# Or in config
log_level: "debug"

Related Documentation

• Template Worker Overview

  Template Worker Service

  Developer documentation for the template-worker service - the template execution engine that runs user-defined Lua/Luau scripts in a sandboxed environment.

  - Service overview
• Architecture

  Template Worker Architecture

  Architecture details for the template-worker service including VM distribution, lifecycle, and runtime management.

  - Service architecture
• Development

  Template Worker Development

  Development guide for the template-worker service including building, testing, and code structure.

  - Building from source
• Hosting Guides - General hosting information

References

• Template Worker Repository
• Dockerfile