Pterodactyl Nginx Egg

A versatile Pterodactyl Egg featuring Nginx, PHP 8.x, WordPress, Git, Composer, Cronjob, ionCube Loader, Auto-Update, and Cloudflare Tunnel support.

Table of Contents

• Features
• Installation
• Auto-Update System
• Composer Modules Usage
• ionCube Loader Support
• Cloudflared Tunnel Tutorial 🚀
• Git Module
• Cronjob
• Change PHP version
• PHP extensions
• Notes
• License

Features

• 🔄 Auto-Update: Automatically checks for and applies updates via Tavuru API
• 🧹 LogCleaner: Cleans /tmp and old logs (dry-run supported)
• 🌱 Git Module: Auto git pull on restart
• 📦 Composer Module: Installs packages from composer.json or a fallback variable
• 🔐 ionCube Loader: Auto-detected and enabled for encrypted PHP
• 🌐 Cloudflare Tunnel: Secure tunnel with token validation
• 🚀 PHP-NGINX Startup: Auto-detects PHP-FPM version, runs NGINX in foreground
• 🖥️ Multi-arch support: AMD64 & ARM64
• 🎯 Selectable PHP Versions:
  • ✅ 8.4
  • ✅ 8.3
  • ☑️ 8.2 (security-only)
  • ☑️ 8.1 (security-only)

PHP Supported Versions

Installation

1. Download the egg file (egg-nginx-v2.json)
2. In your Pterodactyl panel, navigate to Nests in the sidebar
3. Import the egg under Import Egg
4. Create a new server and select the Nginx egg
5. Choose the Docker image matching your desired PHP version
6. Fill in all required variables, including whether WordPress is desired and the PHP version field (must be set explicitly)

Auto-Update System

The egg includes an intelligent auto-update system that keeps your installation current with the latest features and security updates.

How it works:

• Automatic Version Checking: Uses the Tavuru API to check for new releases
• Smart Differential Updates: Downloads only changed files, not the entire codebase
• Selective Updates: Only updates core system files (modules, nginx, php configs)
• User Data Protection: Never touches your www directory or user data
• Self-Update Capability: Can safely update its own update mechanism

Configuration:

Variable	Default	Description
AUTOUPDATE_STATUS	1	Enable (1) or disable (0) auto-update checks
AUTOUPDATE_FORCE	0	Automatically apply updates (1) or just check (0)

Update Behavior:

Conservative Mode (Default)

• AUTOUPDATE_STATUS=1, AUTOUPDATE_FORCE=0
• Checks for updates and shows availability
• Shows version information and changelog
• Updates must be manually approved

Automatic Mode

• AUTOUPDATE_STATUS=1, AUTOUPDATE_FORCE=1
• Automatically downloads and applies updates
• Shows detailed progress during updates
• Creates backups before applying changes

Disabled Mode

• AUTOUPDATE_STATUS=0
• Skips all update operations
• Useful for production environments requiring manual updates

Example Output:

[AutoUpdate] Current version: v2.1.0
[AutoUpdate] Latest version: v2.2.0
[AutoUpdate] ⚠ Update available: v2.1.0 → v2.2.0
[AutoUpdate] Update summary:
  • Total changes: 15
  • Files added: 3
  • Files modified: 8
  • Files removed: 2
[AutoUpdate] ✓ Update completed successfully

What Gets Updated:

• ✅ Module scripts (modules/)
• ✅ Nginx configurations (nginx/)
• ✅ PHP configurations (php/)
• ✅ Core scripts (start-modules.sh)
• ✅ Documentation (README.md, LICENSE)
• ❌ User content (www/ directory)
• ❌ User data (logs, uploads, databases)

Composer Modules Usage

This egg supports easy installation of PHP libraries using Composer.

How it works:

• If a composer.json file exists in your server's root directory, it will be used automatically to install dependencies.
• If composer.json is missing, the egg looks for a variable (e.g. COMPOSER_MODULES) with a space-separated list of Composer packages to install.
• If neither composer.json nor COMPOSER_MODULES is set, Composer installation is skipped.

Specifying Composer Modules manually:

• Enter the packages in the COMPOSER_MODULES variable in this format:

vendor/package[:version_constraint]

Examples:

• Latest stable version:

  symfony/http-foundation 
  

• Specific version or range:

  monolog/monolog:^2.0 doctrine/orm:~2.10 nesbot/carbon:^2.50 
  

• Multiple packages separated by spaces:

  symfony/http-foundation:^6.0 monolog/monolog guzzlehttp/guzzle 
  

Notes:

• Make sure package names and versions exist on Packagist.
• Incorrect inputs can cause installation errors visible in the server console.
• Installing many or complex packages can increase startup time.
• Composer must be pre-installed in the container environment (this egg includes it).

ionCube Loader Support

• ionCube Loader is detected and enabled automatically if encrypted PHP files are present.
• No manual configuration needed; simply upload your ionCube-protected scripts and run.

🚀 Cloudflared Tunnel Tutorial

With Cloudflared, you can create a secure tunnel to your server, making it accessible over the internet without complicated port forwarding!
Cloudflared | Create a remotely-managed tunnel

📌 Requirements

• A Cloudflare account

---

• 🔹 Step 1: Log in to Zero Trust ↗ and go to Networks > Tunnel
• 🔹 Step 2: Select Create a tunnel.
• 🔹 Step 3: Choose Cloudflared for the connector type and select Next.
• 🔹 Step 4: Enter a name for your tunnel.
• 🔹 Step 5: Select Save tunnel.
• 🔹 Step 6: Save the token. (The token is very long)

---

• 🔹 Step 7: Activate Cloudflared

---

• 🔹 Step 8: Add your token.

---

• 🔹 Step 9: Add public hostname

---

• 🔹 Step 10: Depending on the type, select http and URL always "localhost" + the web server port

---

• 🔹 Step 11: Restart your webserver.

Git Module

• Specify your Git repository URL in the GIT_ADDRESS variable
• Enable Git by setting the GIT_STATUS variable to 1 or true
• On server creation, your repo will be cloned into the www folder
• On each restart, git pull runs to update the files

Cronjob

This egg includes a container-native cron engine for automated task scheduling without requiring system cron.

How it works:

• Enable cron by setting the CRON_STATUS variable to 1 or true
• Create or edit /home/container/crontab with your scheduled tasks
• The cron engine runs automatically in the background and executes jobs at the specified times
• All execution logs are saved to /home/container/logs/cron.log

Cron Job Examples:

# Run every minute
* * * * * echo "$(date): Task executed" >> /home/container/logs/task.log

# Daily backup at 2 AM
0 2 * * * tar -czf /home/container/backups/backup-$(date +%Y%m%d).tar.gz /home/container/www

# Clean old logs weekly (Sundays at midnight)
0 0 * * 0 find /home/container/logs -name "*.log" -mtime +7 -delete

# Laravel Scheduler (if using Laravel)
* * * * * cd /home/container/www && /usr/bin/php artisan schedule:run >> /home/container/logs/scheduler.log 2>&1

Notes:

• Uses custom cron engine - no system cron dependency required
• Supports command substitution like $(date) and environment variables
• Always use absolute paths in cron commands
• The cron engine starts automatically with the container

Change PHP version

Changing the PHP version is currently still somewhat cumbersome. A revised version will be available in the future.

• Step 1: In your Pterodactyl panel, go to the "Startup" tab on your web server. Change the variable "PHP VERSION" to the desired version.

---

• Step 2: Finally, you need to customise the Docker image. Select the appropriate Docker image to match the version.

PHP extensions

PHP extensions of PHP version 8.3:

Core, date, libxml, openssl, pcre, zlib, filter, hash, json, random, Reflection, SPL, session, standard, sodium, cgi-fcgi, mysqlnd, PDO, psr, xml, bcmath, calendar, ctype, curl, dom, mbstring, FFI, fileinfo, ftp, gd, gettext, gmp, iconv, igbinary, imagick, imap, intl, ldap, exif, memcache, mongodb, msgpack, mysqli, odbc, pcov, pdo_mysql, PDO_ODBC, pdo_pgsql, pdo_sqlite, pgsql, Phar, posix, ps, pspell, readline, shmop, SimpleXML, soap, sockets, sqlite3, sysvmsg, sysvsem, sysvshm, tokenizer, xmlreader, xmlwriter, xsl, zip, mailparse, memcached, inotify, maxminddb, protobuf, Zend OPcache

Notes

• Public web root directory: www
• To enable HTTPS, modify /home/container/nginx/conf.d/default.conf accordingly
• PHP extensions vary slightly per version; full list available in docs
• Changing PHP versions requires matching Docker image selection and restart
• Auto-updates are powered by the Tavuru API for reliable version management

License

MIT License

Forked and adapted from: https://gitlab.com/tenten8401/pterodactyl-nginx