mcserver/docs/infrastructure-base.md

Infrastructure & Host Baseline Setup Guide

1. Cloud Hardware Baseline

• Provider: Oracle Cloud Infrastructure (OCI)
• Architecture: Ampere A1 Flex (aarch64 / ARM64)
• Resources: 4 OCPUs (Neoverse N1), 24 GB System RAM
• Storage Allocation: 200 GB Always Free Block Volume (Resized Boot Volume)
• Memory Strategy:
  • Container JVM Heap (-Xmx12G -Xms12G): Allocated per instance manifest
  • Host OS & Page Cache: Minimum 12 GB reserved for kernel, filesystem page cache, and Docker daemon overhead

---

2. Host OS & Network Optimization

Firewall Configuration (UFW)

Allocate port ranges to support primary and secondary instances:

# Primary Instance Ports (Java + Simple Voice Chat)
sudo ufw allow 25565/tcp comment 'MC Java Port - Primary Instance'
sudo ufw allow 24454/udp comment 'Voice Chat Port - Primary Instance'

# Secondary Instance Ports
sudo ufw allow 25566/tcp comment 'MC Java Port - Secondary Instance'
sudo ufw allow 24455/udp comment 'Voice Chat Port - Secondary Instance'

sudo ufw enable

Linux Kernel TCP Optimization (BBR + FQ)

Enable Bottleneck Bandwidth and RTT (BBR) congestion control to minimize network latency:

sudo modprobe tcp_bbr
sudo bash -c 'cat <<EOF > /etc/sysctl.d/99-minecraft.conf
net.core.default_qdisc=fq
net.ipv4.tcp_congestion_control=bbr
EOF'
sudo sysctl --system

---

3. Host Ownership Safeguard

Ensure host user retains ownership of repository files and container data volumes to prevent PermissionError (EACCES) or Git unlink failures:

sudo chown -R $USER:$USER ~/mcserver
chmod -R u+rwX ~/mcserver

---

4. OCI Storage Volume Expansion (Always Free Tier)

Oracle Cloud allows up to 200 GB of Always Free block volume storage per tenancy. To expand the default 47 GB boot volume on Ubuntu instances without reinstalling:

Phase 1: OCI Console Allocation

1. In OCI Console, navigate to Compute -> Instances -> [Your Instance] -> Storage / Boot Volume.
2. Select View boot volume details -> Edit.
3. Change volume size from 47 GB up to 200 GB and save.

Phase 2: Live Kernel Rescan & Partition Growth (Ubuntu)

Execute on the host terminal to rescan the block device and resize the online ext4 filesystem:

# 1. Force kernel rescan of resized OCI paravirtualized disk
sudo dd iflag=direct if=/dev/oracleoci/oraclevda of=/dev/null count=1
echo "1" | sudo tee /sys/class/block/`readlink /dev/oracleoci/oraclevda | cut -d'/' -f 2`/device/rescan

# 2. Grow partition 1 on /dev/sda
sudo apt-get update && sudo apt-get install -y cloud-guest-utils
sudo growpart /dev/sda 1

# 3. Resize ext4 filesystem online
sudo resize2fs /dev/sda1

# 4. Verify capacity (Target: ~190G+ available)
df -h /

---

5. Automated SSL/TLS Certificate Provisioning (AutoModpack)

AutoModpack uses TLS 1.3 to encrypt modpack distribution to clients. To prevent client "Certificate Verification" warnings, host-side Let's Encrypt certificates are issued via DNS-01 challenge and synced to AutoModpack in PKCS#8 format.

Prerequisites

• Domain DNS: mc.sotohome.top configured on Cloudflare (DNS Only / Grey Cloud).
• Cloudflare API Token: Scoped with Zone.DNS edit permissions for sotohome.top.

Package Installation

sudo apt update && sudo apt install -y certbot python3-certbot-dns-cloudflare

Credentials & Issuance

1. Save token to restricted host path /etc/letsencrypt/cloudflare.ini:

   dns_cloudflare_api_token = <YOUR_CLOUDFLARE_API_TOKEN>
   

2. Restrict file permissions:

   sudo chmod 600 /etc/letsencrypt/cloudflare.ini
   

3. Issue Let's Encrypt certificate:

   sudo certbot certonly \
     --dns-cloudflare \
     --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
     -d mc.sotohome.top \
     --non-interactive --agree-tos -m jgsc00@gmail.com
   

AutoModpack Certificate Sync & PKCS#8 Conversion

AutoModpack requires keys in PKCS#8 PEM format placed inside runtime/data/automodpack/.private/:

sudo openssl pkcs8 -topk8 -nocrypt \
  -in /etc/letsencrypt/live/mc.sotohome.top/privkey.pem \
  -out /tmp/key.pem

sudo cp /etc/letsencrypt/live/mc.sotohome.top/fullchain.pem \
  ~/mcserver/instances/forge-1.20.1-survival/runtime/data/automodpack/.private/cert.crt

sudo cp /tmp/key.pem \
  ~/mcserver/instances/forge-1.20.1-survival/runtime/data/automodpack/.private/key.pem

sudo rm /tmp/key.pem
sudo chown -R opc:opc ~/mcserver/instances/forge-1.20.1-survival/runtime/data/automodpack/.private/
sudo chmod 600 ~/mcserver/instances/forge-1.20.1-survival/runtime/data/automodpack/.private/cert.crt
sudo chmod 600 ~/mcserver/instances/forge-1.20.1-survival/runtime/data/automodpack/.private/key.pem

Automatic Renewal Deploy Hook

Certbot executes /etc/letsencrypt/renewal-hooks/deploy/automodpack.sh on 60-day auto-renewals to convert keys, update AutoModpack, and restart mc_forge_server.