sample.env

# =============================================================================
# Secret references — keeping credentials out of this file
# =============================================================================
# Any value here may be written as a REFERENCE instead of a literal. The value
# is then fetched when the stack starts rather than stored in this file, so a
# credential need never be committed, and rotating one does not leave the old
# value in git history forever.
#
#   KEY=!ref:env:VARIABLE_NAME       read from the environment
#   KEY=!ref:file:/path/to/secret    the file's contents (a ~ is expanded)
#   KEY=!ref:cmd:some command        run it, take stdout
#
# Worked example using SOPS, which needs no additional infrastructure — the
# encrypted file is safe to commit, the key is not:
#
#   RCON_PASSWORD=!ref:cmd:sops -d --extract '["rcon_password"]' secrets.enc.yaml
#   HCLOUD_TOKEN=!ref:file:~/.secrets/hcloud-token
#   DISCORD_WEBHOOK_URL=!ref:env:OMCSI_DISCORD_WEBHOOK
#
# Notes:
#
# - This is entirely optional. A file of plain literal values keeps working
#   exactly as before, and `./up.sh` does no extra work unless a `!ref:` is
#   actually present.
# - The `!ref:` sigil exists so a literal can never be mistaken for a reference.
#   A password of `file:something` stays that password.
# - If any reference fails to resolve, nothing is started. There is no partial
#   startup with a blank password.
# - The maintenance scripts (`upgrade.sh`, `rollback.sh`, `trigger-backup.sh`)
#   read a few values straight out of this file with grep — container and volume
#   names only, never secrets. Do not put a reference on CONTAINER_NAME,
#   VOLUME_NAME, or BACKUPS_VOLUME_NAME; they would be read literally.
# - Resolve manually with `scripts/resolve-secrets.sh --format shell` when you
#   need the values in your own shell, for example before `terraform apply`.
#
# WHICH VALUES CANNOT BE TAKEN BACK
#
# Not every credential here is equal, and the difference matters when deciding
# what to keep in a file at all:
#
# - RCON_PASSWORD, ADMIN_PASSWORD, DEPLOY_AUTH_TOKEN, DISCORD_WEBHOOK_URL —
#   rotate at the source and the old value is dead. Recoverable.
# - A cloud provider API token — rotate it and the old value is dead, but until
#   you do, it can create and destroy servers and spend real money.
# - A kubeadm cluster-admin kubeconfig — NOT REVOCABLE. Kubernetes has no
#   certificate revocation list, so a leaked admin certificate stays valid until
#   it expires no matter what you change afterwards. Undoing that leak means
#   rotating the cluster CA and re-issuing every credential on the node. Never
#   commit one, anywhere, even to a private repository.
# =============================================================================

# Version of minecraft expected to be installed
MINECRAFT_VERSION=26.2

# Operator user UUID, name, and level
# To get your UUID, visit https://mcuuid.net/ and enter your Minecraft username
OPERATOR_UUID=YOUR_UUID_HERE
OPERATOR_NAME=YOUR_USERNAME_HERE
OPERATOR_LEVEL=4

# Server settings
SERVER_MOTD=An Open Minecraft Server
MAX_PLAYERS=20
DIFFICULTY=normal
GAMEMODE=survival
PVP_ENABLED=true
ONLINE_MODE=true
# Whitelist. WHITELIST_ENABLED turns the whitelist on, so only players listed in
# whitelist.json may join. ENFORCE_WHITELIST additionally kicks players who are
# already connected but not on the list whenever the list is reloaded; it has no
# effect unless WHITELIST_ENABLED is true. Both default to false.
# server.properties is regenerated on every container start, so `/whitelist on`
# in the console does not survive a restart -- set these instead.
WHITELIST_ENABLED=false
ENFORCE_WHITELIST=false
# Whether to start the Minecraft server automatically on wrapper startup (default: true)
MINECRAFT_AUTO_START=true
# Whether to automatically restart the Minecraft server if it stops unexpectedly (default: false)
MINECRAFT_AUTO_RESTART=false

# Java memory allocation settings
# Default: -Xmx3G -Xms2G (3GB max, 2GB initial)
# Adjust based on your server needs and available RAM
JAVA_OPTS=-Xmx3G -Xms2G

# Whether to overwrite existing server data
OVERWRITE_EXISTING_SERVER=false

# Docker configuration (for running parallel dev servers)
# Container name - change this to run multiple servers in parallel
CONTAINER_NAME=open-mc-server

# Host port mappings - change these to avoid port conflicts when running parallel servers
# Minecraft server port (default: 25565)
HOST_PORT=25565
# RCON port (default: 25575)
HOST_RCON_PORT=25575
# BlueMap port (default: 8100)
HOST_BLUEMAP_PORT=8100
# Minecraft wrapper REST API port (default: 8092) — change when running parallel servers
WRAPPER_PORT=8092

# Volume name - change this to use separate data for parallel servers
VOLUME_NAME=mcserver

# Web Application Configuration
# Web container name
WEB_CONTAINER_NAME=open-mc-webapp
# Web app data volume name - change this to use separate data for parallel servers
WEBAPP_VOLUME_NAME=webapp-data
# Alert manager data volume name - change this to use separate data for parallel servers
ALERT_MANAGER_VOLUME_NAME=alert-manager-data
# Backups volume name
BACKUPS_VOLUME_NAME=backups
# Nginx SSL cert volume name
NGINX_SSL_VOLUME_NAME=nginx-ssl
# Data storage path inside the container (mounted from the volume)
DATA_STORAGE_PATH=/app/data
# Nginx reverse proxy container name
NGINX_CONTAINER_NAME=open-mc-nginx
# Web application HTTP port (redirects to HTTPS, default: 8080)
WEB_HTTP_PORT=8080
# Web application HTTPS port (default: 8443)
WEB_HTTPS_PORT=8443

# Upload size limits (plugin JARs and world archives)
# A request meets these in order and the smallest one wins, so raise them
# together. Note the different suffixes — nginx uses 100M / 5G, Spring uses
# 100MB / 5120MB, and the WORLD_UPLOAD_* values are plain MB.
#   1. NGINX_MAX_BODY_SIZE     — proxy cap; over it you get a bare 413
#   2. MAX_*_UPLOAD_SIZE       — Spring multipart limits in both services
#   3. WORLD_UPLOAD_MAX_*      — the wrapper's own checks on the archive
NGINX_MAX_BODY_SIZE=100M
MAX_FILE_UPLOAD_SIZE=2048MB
MAX_REQUEST_UPLOAD_SIZE=2048MB
WORLD_UPLOAD_MAX_FILE_SIZE_MB=2048
# Zip bomb protection: a world expands well past its compressed size, so keep
# this several times the archive limit above.
WORLD_UPLOAD_MAX_EXTRACTED_MB=10240
WORLD_UPLOAD_MAX_ENTRIES=100000

# Where an in-flight upload is buffered. Empty uses each container's writable
# layer, which a multi-GB archive can exhaust — point it at a mounted path
# (e.g. /mcserver/tmp) before accepting uploads that large.
MULTIPART_TEMP_DIR=

# JVM flags for the web app's own JVM (not the Minecraft server — that is
# JAVA_OPTS above). Empty lets the JVM size itself, which is fine on a machine
# of its own; set e.g. -Xmx160m when memory is tight.
WEBAPP_JAVA_TOOL_OPTIONS=

# Time allowed for an upload to transfer, extract, swap in and restart the
# server. NGINX_UPLOAD_TIMEOUT applies to the upload routes only; the rest of
# the dashboard keeps nginx's 60s.
NGINX_UPLOAD_TIMEOUT=3600s
WORLD_UPLOAD_READ_TIMEOUT_SECONDS=600

# RCON password for web app to connect to server
RCON_PASSWORD=minecraft
# Admin credentials for web dashboard
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin
# External service URLs (optional)
DYNMAP_URL=
# Where the dashboard links for the map. With NGINX_BLUEMAP_ENABLED=true below,
# this is the proxy's own address plus NGINX_BLUEMAP_PATH — e.g.
# https://your-host:8443/map/ — otherwise it is the wrapper's published BlueMap
# port, e.g. http://your-host:8100/.
BLUEMAP_URL=

# Serve BlueMap's webapp through the nginx proxy at NGINX_BLUEMAP_PATH, so the
# map is reachable over HTTPS alongside the dashboard instead of only on the
# wrapper's plain-HTTP HOST_BLUEMAP_PORT.
#
# Off by default: nothing listens on the wrapper's BlueMap port until the
# BlueMap plugin is actually installed in the server's plugins directory, and a
# route to a dead upstream is a 502 waiting to happen. Turn it on once BlueMap
# is in place, then set BLUEMAP_URL above to match.
#
# On Kubernetes these are nginx.bluemap.enabled / nginx.bluemap.path in
# helm/omcsi/values.yaml.
NGINX_BLUEMAP_ENABLED=false
NGINX_BLUEMAP_PATH=/map/
# Activity Tracker plugin integration (optional)
ACTIVITY_TRACKER_URL=
ACTIVITY_TRACKER_ENABLED=false
# Web app refresh interval in milliseconds (default: 1800000 = 30 minutes)
WEB_REFRESH_INTERVAL_MS=1800000
# Dashboard customization (optional)
DASHBOARD_TITLE=Minecraft Server Dashboard
DASHBOARD_SUBTITLE=Server Management & Information
DASHBOARD_PRIMARY_COLOR=#667eea
DASHBOARD_SECONDARY_COLOR=#764ba2
DASHBOARD_DARK_MODE=true
# Plugin directory path (default: /mcserver/plugins)
PLUGINS_DIRECTORY=/mcserver/plugins
# Default plugins to install automatically on server setup (optional).
# Comma-separated list of direct download URLs to plugin JARs. Each is
# downloaded into PLUGINS_DIRECTORY on startup, keyed by filename, so a
# plugin that already exists there (installed manually or on a prior boot)
# is left untouched. Leave empty to skip default plugin installation.
DEFAULT_PLUGINS=
# World directory path (default: /mcserver/world). Shared by the web app, which
# lists and deletes worlds under this path, and the minecraft-wrapper, which
# installs uploaded worlds there.
WORLD_DIRECTORY=/mcserver/world

# CI/CD Plugin Deployment and World Upload Configuration
# Set a strong random secret here to protect the minecraft-wrapper's
# POST /api/plugins/deploy and POST /api/world/upload endpoints. Use the same value as
# the DEPLOY_AUTH_TOKEN GitHub Actions secret in your plugin repository. Leave empty to
# disable both endpoints. The web app also receives this token: it presents it when
# forwarding a dashboard world upload to the wrapper, so leaving it empty disables
# world upload from the dashboard too.
DEPLOY_AUTH_TOKEN=
# Shared secret for the POST /api/deployment-history endpoint on the web app.
# The minecraft-wrapper sends this token when reporting deployment events.
# Leave empty to reject all deployment history writes.
DEPLOYMENT_AUTH_TOKEN=

# Whether the minecraft-wrapper integration is enabled in the web app (default: true)
MINECRAFT_WRAPPER_ENABLED=true
# Minecraft wrapper REST API URL used by the web app and agent manager.
# Docker Compose only — the Helm chart derives this from the in-cluster Service.
MINECRAFT_WRAPPER_URL=http://minecraft-wrapper:8092
# The web app's sleep-aware mode (SLEEP_AWARE_ENABLED / WRAPPER_STATEFULSET_NAME)
# is deliberately absent here: it reads and scales the wrapper's Kubernetes
# StatefulSet, and Compose has no notion of scaling a service to zero. It is
# set by the Helm chart's webapp.sleepAware.enabled and defaults to off.

# Alert Manager integration for web app actions (default: true)
ALERT_MANAGER_ENABLED=true

# Accordion Chat Configuration
# Note: Accordion Chat runs as a separate application. Clone and run it from:
# https://github.com/Stephenson-Software/accordion
# Accordion Chat URL (optional) - URL to your running Accordion Chat instance
ACCORDION_CHAT_URL=

# Backup Manager Configuration
# Backup container name
BACKUP_CONTAINER_NAME=open-mc-backup-manager
# Backup manager API port (default: 8091)
BACKUP_PORT=8091
# Maximum size of the backups directory in MB (default: 10GB)
# Cap on the whole backups directory. The newest backup is never deleted to
# satisfy it, so a cap below one backup's size means only ever holding that one.
# Allow a few times the world size.
BACKUP_MAX_SIZE_MB=10240
# Backup schedule (cron expression, default: 0 0 2 * * ? = 2 AM every day)
# Set to - to disable scheduled backups; POST /api/backups/trigger still works.
BACKUP_SCHEDULE=0 0 2 * * ?

# Alert Manager Configuration
# Alert manager container name
ALERT_CONTAINER_NAME=open-mc-alert-manager
# Alert manager API port (default: 8090)
ALERT_PORT=8090
# Alert manager alerts endpoint, shared by minecraft-wrapper, web app, backup-manager and
# agent-manager (default: http://alert-manager:8090/api/alerts). All of them POST to this
# value verbatim, so it must include the /api/alerts path.
ALERT_MANAGER_URL=http://alert-manager:8090/api/alerts
# Discord webhook URL for notifications (optional)
# To get a webhook URL: Discord Server Settings → Integrations → Webhooks
DISCORD_WEBHOOK_URL=
# Enable/disable Discord notifications (default: false)
DISCORD_ENABLED=false
# RCON connection the alert manager uses to broadcast alerts in-game via "say".
# MINECRAFT_RCON_HOST/PORT are Docker Compose only — the Helm chart derives them
# from the in-cluster minecraft-wrapper Service. The password comes from RCON_PASSWORD above.
MINECRAFT_RCON_HOST=minecraft-wrapper
MINECRAFT_RCON_PORT=25575
# Whether the alert manager broadcasts alerts in-game over RCON at all (default: true)
MINECRAFT_RCON_ENABLED=true

# Agent Manager Configuration
# Agent manager container name
AGENT_CONTAINER_NAME=open-mc-agent-manager
# Agent manager API port (default: 8093)
AGENT_PORT=8093
# Discord bot token (required for agent manager)
AGENT_DISCORD_BOT_TOKEN=
# Discord channel ID to listen on (required for agent manager)
AGENT_DISCORD_CHANNEL_ID=
# Anthropic API key (required for agent manager)
AGENT_ANTHROPIC_API_KEY=
# Anthropic model the agent uses (default: claude-sonnet-4-20250514)
AGENT_ANTHROPIC_MODEL=claude-sonnet-4-20250514
# Maximum output tokens per Anthropic response (default: 1024).
# Raise this if diagnostic answers are being cut short; lower it to cap API spend.
AGENT_ANTHROPIC_MAX_TOKENS=1024
# Enable/disable the agent manager (default: false)
AGENT_ENABLED=false

# Backup manager URL for agent-manager to trigger backups
BACKUP_MANAGER_URL=http://backup-manager:8091

# Per-tool confirmation toggles
AGENT_START_SERVER_REQUIRES_CONFIRMATION=true
AGENT_STOP_SERVER_REQUIRES_CONFIRMATION=true
AGENT_RESTART_SERVER_REQUIRES_CONFIRMATION=true
AGENT_TRIGGER_BACKUP_REQUIRES_CONFIRMATION=true

# Diagnostic log access
# When true, the agent may include recent server log lines in diagnostic responses.
# Both flags must be true: LOGS_DIAGNOSTIC_ENABLED on the wrapper AND DIAGNOSTICS_LOGS_ENABLED on the agent.
# Logs are sanitized (IP addresses redacted) before being sent to the Anthropic API by default.
LOGS_DIAGNOSTIC_ENABLED=false
LOGS_DIAGNOSTIC_MAX_LINES=100
DIAGNOSTICS_LOGS_ENABLED=false
DIAGNOSTICS_LOGS_MAX_LINES=500
# When true (default), player IP addresses in server logs are redacted to [IP_REDACTED] before being forwarded to Anthropic.
# Set to false only if you have independently verified that logs contain no personally identifiable information.
DIAGNOSTICS_LOGS_ANONYMIZE=true

# Webapp data in diagnostics
# When enabled, the agent will include webapp server status and activity tracker stats in diagnostic responses.
# Set WEBAPP_URL to the internal URL of the web-app container (default: http://webapp:8080).
DIAGNOSTICS_WEBAPP_ENABLED=false
WEBAPP_URL=http://webapp:8080

# Alert Toggles - Control which events trigger alerts
# Server lifecycle alerts
ALERTS_SERVER_START=true
ALERTS_SERVER_STOP=true
ALERTS_SERVER_CRASH=true
# Plugin deployment alerts
ALERTS_PLUGIN_DEPLOY=true
# World upload alerts
ALERTS_WORLD_UPLOAD=true
# Backup alerts
ALERTS_BACKUP_SUCCESS=true
ALERTS_BACKUP_FAILURE=true
# Upgrade alerts
# Read by upgrade.sh on the Docker host — Docker Compose only, no Kubernetes equivalent.
ALERTS_UPGRADE_START=true
ALERTS_UPGRADE_COMPLETE=true
ALERTS_UPGRADE_FAILURE=true
# Configuration alerts
ALERTS_CONFIG_WARNING=false

# Usage reporting
# Once the minecraft-wrapper is up it sends ONE "startup" event to the project's
# usage service (https://github.com/Stephenson-Software/trace) so the maintainers
# can see how many OMCSI deployments exist and which versions run. It carries the
# program name (open-mc-server-infrastructure), the wrapper's version and the tags
# below — nothing per request or per player, and nothing about your world, your
# operator account, your host or its address. It runs on its own thread, never
# blocks startup and never fails the server. The wrapper logs one INFO line on
# every start saying whether reporting is on. On Kubernetes these are the
# minecraftWrapper.env.USAGE_REPORTING_* values in helm/omcsi/values.yaml.
# Details: https://github.com/Stephenson-Software/trace#usage-reporting
# Set to false to turn it off (default: true)
USAGE_REPORTING_ENABLED=true
# Where the event goes (default: https://trace.danielstephenson.dev)
USAGE_REPORTING_ENDPOINT=https://trace.danielstephenson.dev
# Program key. Leave empty to use the project's bundled write-only key.
USAGE_REPORTING_KEY=
# Optional comma-separated k=v tags attached to the event, e.g. ci=true so a CI
# deployment can be told apart from a real one. "version" is reserved.
USAGE_REPORTING_TAGS=
# The switch every trace client honours, checked before USAGE_REPORTING_ENABLED:
# off (or false, 0, no) turns reporting off. Leave empty for "not set".
TRACE_USAGE_REPORTING=
# The https://consoledonottrack.com convention: 1 (or true, yes) turns it off too.
DO_NOT_TRACK=