DEPLOYMENT_GUIDE.md

LuminariMUD Deployment Guide

Overview

LuminariMUD is a comprehensive MUD codebase implementing Pathfinder/D&D 3.5 mechanics. This guide covers the complete deployment process from source code to running server.

Important: This is a substantial deployment process for a complex C-based MUD server. Expect the initial setup to take 15-30 minutes depending on your system and experience level.

---

System Requirements

Minimum Requirements

• Operating System: Linux (Ubuntu 18.04+, CentOS 7+, Debian 9+) or Unix-like system
• Memory: 512MB RAM (2GB+ recommended for production)
• Storage: 1GB+ free disk space
• Network: TCP/IP networking capability
• Compiler: GCC 4.8+ with ANSI C90/C89 support

Recommended Requirements

• Operating System: Ubuntu 20.04+ LTS or CentOS 8+
• Memory: 4GB+ RAM for development, 2GB+ for production
• Storage: 5GB+ free disk space
• Compiler: GCC 9.0+ or Clang 10.0+
• Build System: GNU Autotools (automake, autoconf)
• Database: MariaDB 10.3+ (optional but recommended)

---

Dependencies Installation

Ubuntu/Debian (including WSL2)

# Update package list
sudo apt-get update

# Install REQUIRED build dependencies
sudo apt-get install -y build-essential git make autoconf automake

# Optional but recommended dependencies
sudo apt-get install -y libcrypt-dev libgd-dev libmariadb-dev \
                        libcurl4-openssl-dev libssl-dev mariadb-server \
                        pkg-config libjson-c-dev

# For debugging (recommended)
sudo apt-get install -y gdb valgrind

# If encountering line ending issues
sudo apt-get install -y dos2unix

CentOS/RHEL/Fedora

# For CentOS 7/RHEL 7
sudo yum install -y gcc make git autoconf automake

# For CentOS 8+/RHEL 8+/Fedora
sudo dnf install -y gcc make git autoconf automake

# Optional but recommended
sudo dnf install -y mariadb-server mariadb-devel gd-devel \
                    libcrypt-devel libtool json-c-devel

---

Deployment Process

Method 1: Automated Deployment Script (Recommended)

The deployment script handles all necessary steps automatically:

# Clone the repository
git clone https://github.com/LuminariMUD/Luminari-Source.git
cd Luminari-Source

# Run the deployment script (handles everything)
# Note: You'll be prompted for MySQL root password during setup
./scripts/deploy.sh

# Start the server
./bin/circle -d lib

The deployment script automatically performs:

• Installs dependencies (if needed)
• Generates the build system (autoreconf + configure - autotools preferred)
• Copies required configuration files (.example.h → .h)
• Builds the entire codebase
• Installs binaries to bin/
• Sets up and configures MariaDB database (REQUIRED)
• Creates database and runs initialization
• Initializes minimal world data (zones, rooms, mobs, objects) - enabled by default
• Creates required symlinks
• Creates necessary directories

Note: World initialization is ON by default. Use --no-init-world only if you have custom world files.

Method 2: Deploy Script with Custom Options

For more control over the deployment process:

# Clone the repository
git clone https://github.com/LuminariMUD/Luminari-Source.git
cd Luminari-Source

# Generate build system first (optional - deploy.sh will do this)
autoreconf -fvi

# Run deployment with custom options
./scripts/deploy.sh --auto  # Skip prompts where possible

# Or for development build
./scripts/deploy.sh --dev   # Includes debug symbols

# Start the server
./bin/circle -d lib

Deploy script options:

Option	Description
--auto	Skip prompts where possible (still prompts for MySQL root password)
--no-init-world	Skip world initialization (only if you have custom world files)
--skip-db	Skip database setup (NOT RECOMMENDED - database is required)
--skip-deps	Skip dependency installation
--dev	Development build with debug symbols
--prod	Production optimized build
-h, --help	Show help message

Note: World initialization is enabled by default. The server requires world data to start.

Running without --skip-db prompts for the MariaDB root password, creates the luminari database and user, and executes the in-engine database initializer (equivalent to running db_init_system all). This ensures every required table and stored procedure exists—including wilderness resources, region hints, vessels, and PubSub—without touching external .sql scripts. If you have custom data to seed, add it through the game or your own migrations after the initializer completes.

The generated credentials are written to lib/mysql_config (owned by the invoking user, mode 600) so the game can authenticate automatically. Re-running the deploy script refreshes credentials and reapplies the schema safely.

Method 3: Manual Deployment (Advanced Users Only)

For complete control over each step:

1. Clone Repository

git clone https://github.com/LuminariMUD/Luminari-Source.git
cd Luminari-Source

2. Generate Build System

# Generate configure script and Makefiles
autoreconf -fvi

3. Copy Configuration Files

# Required for compilation
cp src/campaign.example.h src/campaign.h
cp src/mud_options.example.h src/mud_options.h
cp src/vnums.example.h src/vnums.h

4. Configure and Build

# Configure the build
./configure

# Clean any previous builds
make clean

# Build using all available cores
make -j$(nproc)

# Install binaries to bin/
make install

5. Create Required Symlinks

# The MUD expects these in the root directory
ln -sf lib/world world
ln -sf lib/text text
ln -sf lib/etc etc

6. Set Up World Files

# Create world directories
mkdir -p lib/world/{zon,wld,mob,obj,shp,trg,qst,hlq}

# Copy minimal world files
for dir in zon wld mob obj shp trg qst; do
    if [ -f lib/world/minimal/index.${dir} ]; then
        cp lib/world/minimal/index.${dir} lib/world/${dir}/index
    else
        echo '$' > lib/world/${dir}/index
    fi
    cp lib/world/minimal/*.${dir} lib/world/${dir}/ 2>/dev/null || true
done

# Create HLQ index
echo '$' > lib/world/hlq/index

7. Create Text Files

# Create directories
mkdir -p lib/text/help lib/etc

# Create required text files
echo "Welcome to LuminariMUD!" > lib/text/news
echo "LuminariMUD Credits" > lib/text/credits
echo "Message of the Day" > lib/text/motd
echo "Immortal MOTD" > lib/text/imotd
echo "Help" > lib/text/help/help
echo "Immortal Help" > lib/text/help/ihelp
echo "Info" > lib/text/info
echo "Wizard List" > lib/text/wizlist
echo "Immortal List" > lib/text/immlist
echo "Policies" > lib/text/policies
echo "Handbook" > lib/text/handbook
echo "Background" > lib/text/background
echo "Welcome!" > lib/text/greetings

# Create help index
echo '$' > lib/text/help/index

# Create minimal config
echo "# LuminariMUD Configuration" > lib/etc/config

8. Create Required Directories

mkdir -p lib/plrfiles/{A-E,F-J,K-O,P-T,U-Z,ZZZ}
mkdir -p lib/plrobjs/{A-E,F-J,K-O,P-T,U-Z,ZZZ}
mkdir -p lib/house
mkdir -p lib/mudmail
mkdir -p log

9. Start the Server

./bin/circle -d lib

---

Database Configuration (REQUIRED)

MySQL/MariaDB is required for LuminariMUD to function properly. The database provides essential persistent storage for player data, world state, wilderness systems, and many core game features.

Setting Up MySQL/MariaDB

1. Install and Start Database

# Ubuntu/Debian
sudo apt-get install mariadb-server
sudo systemctl start mariadb
sudo systemctl enable mariadb

# Secure the installation
sudo mysql_secure_installation

2. Create Database and User

mysql -u root -p

CREATE DATABASE luminari CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'luminari'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON luminari.* TO 'luminari'@'localhost';
FLUSH PRIVILEGES;
EXIT;

3. Configure Connection

# Create configuration file
cat > lib/mysql_config << EOF
mysql_host = localhost
mysql_database = luminari
mysql_username = luminari
mysql_password = your_secure_password
EOF

# Set secure permissions
chmod 600 lib/mysql_config

---

Running the Server

Using the Autorun Script (Recommended for Production)

# Start with auto-restart on crash
./autorun

# Run in background
nohup ./autorun &

Direct Startup

# Start on default port (4000)
./bin/circle -d lib

# Start on specific port
./bin/circle -q 5000 -d lib

# Run in background
nohup ./bin/circle -d lib > log/server.log 2>&1 &

Using Screen/Tmux (Recommended for Remote Servers)

# Using screen
screen -S luminari
./bin/circle -d lib
# Detach: Ctrl+A then D
# Reattach: screen -r luminari

# Using tmux
tmux new -s luminari
./bin/circle -d lib
# Detach: Ctrl+B then D
# Reattach: tmux attach -t luminari

Server Management

# Check if running
ps aux | grep circle

# View logs
tail -f log/syslog

# Stop autorun script
touch .killscript

# Pause autorun temporarily
touch pause

---

Troubleshooting

Common Issues

Build Fails - Missing Configuration Files

cp src/campaign.example.h src/campaign.h
cp src/mud_options.example.h src/mud_options.h
cp src/vnums.example.h src/vnums.h

Build Fails - No Makefile

# Generate build system first
autoreconf -fvi
./configure

Binary Not in bin/ Directory

# Must run make install after building
make install

Windows Line Endings (CRLF) Errors

# Fix line endings
sudo apt-get install dos2unix
dos2unix configure autorun
find . -name "*.sh" -exec dos2unix {} \;

MUD Won't Start - Missing World Files

# ERROR: opening index file 'world/zon/index': No such file or directory
# CAUSE: Missing world data - you MUST use --init-world or provide custom world

# SOLUTION: Re-run deployment with --init-world
./scripts/deploy.sh --auto --init-world

# OR create required symlinks if they're missing
ln -sf lib/world world
ln -sf lib/text text
ln -sf lib/etc etc

Port Already in Use

# Find what's using port 4000
sudo lsof -i :4000

# Kill the process
kill -9 [PID]

# Or use a different port
./bin/circle -q 5000 -d lib

MySQL Connection Fails

• Verify service is running: sudo systemctl status mariadb
• Check credentials in lib/mysql_config
• Test connection: mysql -u luminari -p luminari
• The database is REQUIRED - you must fix connection issues for the MUD to function properly

---

Post-Deployment

After successful deployment:

1. Connect to the MUD: Use any MUD client to connect to localhost:4000
2. Create Admin Character: The first character created gets admin privileges
3. Review Documentation:
   • Getting Started - Player and builder basics
   • Developer Guide - For code development
   • Database Guide - Database details
4. Start Building: Use OLC (Online Creation) commands to build your world

---

Known Issues

Minor Issues (Non-blocking)

1. Configure script cosmetic error: cat: ./src/conf.h.in: No such file or directory - harmless, doesn't affect build
2. MySQL config template: Uses placeholder values - customize as needed
3. Start room warnings: "Immort/Frozen start room does not exist" - cosmetic warnings on startup

These issues do not prevent successful deployment.

---

Support

• GitHub Issues: Report bugs or request features
• Documentation: Check the docs/ directory for detailed guides
• Logs: Check log/syslog for error messages

---

Last updated: September 2025 Deployment status: WORKING