MCBDS Manager - Professional Minecraft Bedrock Server Management

Linux Installation Guide

Complete guide for installing MCBDS Manager API on Ubuntu Linux

Download Linux Package v1.1.51 View on GitHub
API-Only Installation

This is an API-only installation with no web dashboard UI included. Manage your server via:

  • REST API calls (curl, Postman, scripts)
  • MAUI mobile app (Android/iOS)
  • Web UI (available separately - coming soon)

Prerequisites

User Account Requirements:
  • Admin/sudo access required for initial setup
  • Commands marked with sudo - Run as admin user
  • Commands marked with sudo su - mcbds - Run as service user

Supported Ubuntu Versions

  • Ubuntu 22.04 LTS (recommended)
  • Ubuntu 24.04 LTS
  • Ubuntu 20.04 LTS (minimum)

Hardware Requirements

  • CPU: 2+ cores (4+ recommended for multiple players)
  • RAM: 4GB minimum (8GB+ recommended)
  • Storage: 5GB+ free space
  • Network: Static IP or DDNS (for external access)

Required Ports

  • 8080 - HTTP API Endpoints
  • 8081 - HTTPS API Endpoints (optional)
  • 19132/UDP - Minecraft Bedrock IPv4
  • 19133/UDP - Minecraft Bedrock IPv6

System Preparation

1. Update System Packages

sudo apt update && sudo apt upgrade -y

2. Install Essential Tools

sudo apt install -y curl wget unzip vim systemd ufw

3. Create Service User (recommended for security)

# Create dedicated user for MCBDS service
sudo useradd -r -m -d /opt/mcbds -s /bin/bash mcbds

# Set password (optional, for SSH access)
# sudo passwd mcbds

Install .NET 10 Runtime

Ubuntu 22.04/24.04

# Add Microsoft package repository
wget https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# Install .NET 10 ASP.NET Core Runtime
sudo apt update
sudo apt install -y aspnetcore-runtime-10.0

# Verify installation
dotnet --list-runtimes
Expected Output: 
Microsoft.AspNetCore.App 10.0.x [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 10.0.x [/usr/share/dotnet/shared/Microsoft.NETCore.App]

Deploy MCBDS API

1. Download Latest Release

# Switch to service user
sudo su - mcbds

# Create directory structure
mkdir -p /opt/mcbds/{api,binaries,backups,logs}
cd /opt/mcbds/api

# Download release package
wget https://www.mc-bds.com/downloads/mcbds-api-linux-x64-v1.1.51.zip -O mcbds-api.zip

# Extract package
unzip mcbds-api.zip
rm mcbds-api.zip

2. Make Executable

# Still as mcbds user
chmod +x /opt/mcbds/api/MCBDS.API

# Exit back to admin user for next steps
exit

Install Minecraft Bedrock Server

1. Install Required Dependencies (as admin)

# Exit from mcbds user if currently logged in
exit

# Run as admin/sudo user
sudo apt install -y libcurl4 openssl libc6 libstdc++6

2. Download Bedrock Server (as mcbds user)

Get Latest Download URL:
  1. Visit minecraft.net/download/server/bedrock
  2. Accept EULA and click "Download for Ubuntu (Linux)"
  3. Right-click download button and copy link address
  4. Use the copied URL in the wget command below
# Switch to service user
sudo su - mcbds
cd /opt/mcbds/binaries

# Download (replace URL with current version from minecraft.net)
wget https://minecraft.azureedge.net/bin-linux/bedrock-server-VERSION.zip

# Extract
unzip bedrock-server-*.zip
rm bedrock-server-*.zip

# Exit back to admin user
exit

3. Test Bedrock Server Manually (optional)

sudo su - mcbds
cd /opt/mcbds/binaries
LD_LIBRARY_PATH=. ./bedrock_server

# Press Ctrl+C to stop after verifying it starts
exit

Configure systemd Service

The following steps require admin/sudo privileges. If you're logged in as mcbds user, type exit first.

1. Create Service File

sudo vim /etc/systemd/system/mcbds-api.service

Service Configuration:

[Unit]
Description=MCBDS Manager API Service
After=network.target

[Service]
Type=simple
User=mcbds
Group=mcbds
WorkingDirectory=/opt/mcbds/api
ExecStart=/opt/mcbds/api/MCBDS.API
Restart=on-failure
RestartSec=10

# Environment variables
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
Environment=ASPNETCORE_URLS=http://0.0.0.0:8080

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/mcbds/api /opt/mcbds/binaries /opt/mcbds/backups /opt/mcbds/logs

# Resource limits
LimitNOFILE=65535
MemoryLimit=4G

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=mcbds-api

[Install]
WantedBy=multi-user.target

2. Configure API Settings

sudo vim /opt/mcbds/api/appsettings.json

Configuration:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Runner": {
    "ExePath": "/opt/mcbds/binaries/bedrock_server",
    "WorkingDirectory": "/opt/mcbds/binaries"
  },
  "Backup": {
    "FrequencyMinutes": 30,
    "BackupDirectory": "/opt/mcbds/backups",
    "MaxBackupsToKeep": 30,
    "Enabled": true
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:8080"
      }
    }
  }
}

3. Set Permissions

sudo chown -R mcbds:mcbds /opt/mcbds
sudo chmod -R 755 /opt/mcbds/api
sudo chmod -R 755 /opt/mcbds/binaries
sudo chmod -R 775 /opt/mcbds/backups
sudo chmod -R 775 /opt/mcbds/logs

4. Enable and Start Service

# Reload systemd configuration
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable mcbds-api.service

# Start service
sudo systemctl start mcbds-api.service

# Check status
sudo systemctl status mcbds-api.service

Firewall Configuration

Using UFW (Ubuntu Firewall)

# Enable UFW (if not already enabled)
sudo ufw status
sudo ufw enable

# Allow SSH (if managing remotely)
sudo ufw allow 22/tcp comment 'SSH'

# Allow MCBDS API HTTP
sudo ufw allow 8080/tcp comment 'MCBDS API HTTP'

# Allow MCBDS API HTTPS (optional)
sudo ufw allow 8081/tcp comment 'MCBDS API HTTPS'

# Allow Minecraft Bedrock Server
sudo ufw allow 19132/udp comment 'Minecraft Bedrock IPv4'
sudo ufw allow 19133/udp comment 'Minecraft Bedrock IPv6'

# Reload firewall
sudo ufw reload

# Verify rules
sudo ufw status numbered

Verification & Testing

1. Check Service Status

# View service status
sudo systemctl status mcbds-api.service

# View real-time logs
sudo journalctl -u mcbds-api.service -f

# View recent logs
sudo journalctl -u mcbds-api.service -n 100

2. Test API Endpoints

# Health check
curl http://localhost:8080/health

# Check server status
curl http://localhost:8080/api/runner/status

# List backups
curl http://localhost:8080/api/backup/list

3. Test from Remote Machine

# Replace YOUR_SERVER_IP with your server's IP address
curl http://YOUR_SERVER_IP:8080/health
curl http://YOUR_SERVER_IP:8080/api/runner/status

Troubleshooting

Check Logs
sudo journalctl -u mcbds-api.service -n 100 --no-pager
Missing appsettings.json
# Create comprehensive configuration file
sudo su - mcbds
cat > /opt/mcbds/api/appsettings.json << 'EOF'
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Runner": {
    "ExePath": "/opt/mcbds/binaries/bedrock_server",
    "WorkingDirectory": "/opt/mcbds/binaries"
  },
  "Backup": {
    "FrequencyMinutes": 30,
    "BackupDirectory": "/opt/mcbds/backups",
    "MaxBackupsToKeep": 30,
    "Enabled": true
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:8080"
      }
    }
  }
}
EOF
exit

# Restart service
sudo systemctl restart mcbds-api.service
Port Already in Use
# Check what's using port 8080
sudo netstat -tulpn | grep 8080
sudo lsof -i :8080
Permission Denied
# Fix ownership and permissions
sudo chown -R mcbds:mcbds /opt/mcbds
sudo chmod +x /opt/mcbds/api/MCBDS.API
sudo chmod +x /opt/mcbds/binaries/bedrock_server

Missing Dependencies
# Install required libraries
sudo apt install -y libcurl4 openssl libc6 libstdc++6

# Check library dependencies
ldd /opt/mcbds/binaries/bedrock_server
Test Manually
sudo su - mcbds
cd /opt/mcbds/binaries
LD_LIBRARY_PATH=. ./bedrock_server

Check Firewall
# Verify UFW rules
sudo ufw status numbered

# Test port connectivity from external machine
nc -zv YOUR_SERVER_IP 8080
nc -zuv YOUR_SERVER_IP 19132
Check Network Binding
# Verify API is listening on all interfaces
sudo netstat -tulpn | grep 8080
# Should show 0.0.0.0:8080, not 127.0.0.1:8080

Next Steps

1. Configure Server Properties

Edit /opt/mcbds/binaries/server.properties to customize your server

2. Start Managing via API

Example API calls:

# Start server
curl -X POST http://localhost:8080/api/runner/start

# Stop server
curl -X POST http://localhost:8080/api/runner/stop

# Send command
curl -X POST http://localhost:8080/api/runner/command \
  -H "Content-Type: application/json" \
  -d '{"command": "say Hello from API!"}'
3. Connect Mobile App

Download the MAUI mobile app for native iOS/Android management

4. Setup Automated Backups

Configure backup frequency and retention in appsettings.json

API Endpoints Reference

Runner Management
  • GET /api/runner/status
  • POST /api/runner/start
  • POST /api/runner/stop
  • POST /api/runner/restart
  • POST /api/runner/command
Allowlist Management
  • GET /api/allowlist
  • POST /api/allowlist
  • DELETE /api/allowlist/{xuid}
Backup Management
  • GET /api/backup/list
  • POST /api/backup/create
  • GET /api/backup/download/{filename}
  • DELETE /api/backup/{filename}
Pack Management
  • GET /api/packs/resource
  • POST /api/packs/resource
  • GET /api/packs/behavior
  • POST /api/packs/behavior

Need Help?

Check out these resources:

Report Issue Get Started View Features

Linux Installation Guide

Complete guide for installing MCBDS Manager API on Ubuntu Linux

Download Linux Package v1.1.51 View on GitHub
API-Only Installation

This is an API-only installation with no web dashboard UI included. Manage your server via:

  • REST API calls (curl, Postman, scripts)
  • MAUI mobile app (Android/iOS)
  • Web UI (available separately - coming soon)

Prerequisites

Supported Ubuntu Versions

  • Ubuntu 22.04 LTS (recommended)
  • Ubuntu 24.04 LTS
  • Ubuntu 20.04 LTS (minimum)

Hardware Requirements

  • CPU: 2+ cores (4+ recommended for multiple players)
  • RAM: 4GB minimum (8GB+ recommended)
  • Storage: 5GB+ free space
  • Network: Static IP or DDNS (for external access)

Required Ports

  • 8080 - HTTP API Endpoints
  • 8081 - HTTPS API Endpoints (optional)
  • 19132/UDP - Minecraft Bedrock IPv4
  • 19133/UDP - Minecraft Bedrock IPv6

Quick Start

For the complete installation guide with detailed explanations, continue reading below. Here's a high-level overview:

  1. Download and extract the Linux package
  2. Install .NET 10 ASP.NET Core Runtime
  3. Download Minecraft Bedrock Server
  4. Configure systemd service
  5. Start and manage via API

Download

MCBDS API Linux Package v1.1.51

Pre-compiled .NET 10 binaries for Ubuntu 20.04+

Download (mcbds-api-linux-x64-v1.1.51.zip)
Package Includes:
  • ? Pre-compiled .NET 10 API binaries
  • ? All required dependencies and libraries
  • ? Default configuration files
  • ? REST API endpoints
  • ? No web dashboard UI (API-only)
  • ? No Minecraft Bedrock server binaries (download separately)
Note: You'll need to download the Minecraft Bedrock Server separately from minecraft.net
Complete Installation Guide

For the full step-by-step installation instructions, please refer to the complete Linux Installation Guide on GitHub

API Endpoints

Manage your server via REST API. Here are the key endpoint categories:

Runner Management
  • GET /api/runner/status
  • POST /api/runner/start
  • POST /api/runner/stop
  • POST /api/runner/command
Allowlist Management
  • GET /api/allowlist
  • POST /api/allowlist
  • DELETE /api/allowlist/{xuid}
Backup Management
  • GET /api/backup/list
  • POST /api/backup/create
  • GET /api/backup/download/{filename}
  • GET /api/backup/settings
Pack Management
  • GET /api/packs/resource
  • POST /api/packs/resource
  • GET /api/packs/behavior
  • POST /api/packs/behavior

After Installation

1. Configure Server Properties

Edit /opt/mcbds/binaries/server.properties to customize your server

2. Start Managing via API

Use curl, Postman, or any HTTP client to interact with the REST API

3. Connect Mobile App

Download the MAUI mobile app for native iOS/Android management

4. Setup Automated Backups

Configure backup frequency and retention in appsettings.json

Need Help?

Check out these resources:

Full Guide Report Issue Get Started

Support MCBDS Manager Development

Help us continue developing and improving MCBDS Manager. Your support makes a difference!

Support Us on GoFundMe