Pterodactyl Nginx Egg

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

Table of Contents

• Features
• Installation
• Auto-Update System
• SSL Certificate with Certbot
• 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.5
  • ✅ 8.4
  • ☑️ 8.3 (security-only)
  • ☑️ 8.2 (security-only)
  • ❌ 8.1 (EOL)

PHP Supported Versions

Installation

1. Download the egg file (egg-nginx-v3.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. If you enter the image manually, keep the full repository path lowercase, for example ghcr.io/jishwaah/pterodactyl-nginx-egg:8.4-latest
7. Fill in all required variables, including whether WordPress is desired and the PHP version field (must be set explicitly)
8. After the installation finishes, start the server manually once so Nginx, PHP-FPM, and the optional modules begin running

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	1	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)

SSL Certificate Setup Tutorial

With Certbot DNS-01 Challenge, you can create SSL certificates for your domain without needing port 80 or 443 open!
Let's Encrypt | Getting Started

📌 Requirements

• A DNS provider account with access to create TXT records
• Your domain name

---

• 🔹 Step 1: Enable Certbot in Pterodactyl Startup settings
  Set CERTBOT_STATUS=true

• 🔹 Step 2: Configure your email address
  Set CERTBOT_EMAIL=your@email.com

• 🔹 Step 3: Set your domain name
  Set CERTBOT_DOMAIN=yourdomain.com

• 🔹 Step 4: Restart your server and watch console output
  Certbot will display a DNS TXT record

• 🔹 Step 5: Create the DNS TXT record at your DNS provider

  • Name: _acme-challenge.yourdomain.com
  • Type: TXT
  • Value: Copy from Certbot output
  • Wait 2-5 minutes for DNS propagation

• 🔹 Step 6: Verify DNS with online tool
  Check: https://toolbox.googleapps.com/apps/dig/#TXT/_acme-challenge.yourdomain.com

• 🔹 Step 7: Continue in Pterodactyl console
  Type SPACE + ENTER twice in the command line

• 🔹 Step 8: Copy SSL configuration template
  Copy /nginx/conf.d/default-ssl.conf.temp content into default.conf

• 🔹 Step 9: Replace placeholders in default.conf
  Replace <port> with your port (e.g., 25783)
  Replace <domain> with your domain (e.g., yourdomain.com)

• 🔹 Step 10: Restart Nginx server

• 🔹 Step 11: Create DNS A records at your DNS provider

  • Name: @ → Type: A → Value: Your server IP
  • Name: www → Type: A → Value: Your server IP

• 🔹 Step 12: Access your site via HTTPS
  Visit https://<domain>:<port> in your browser! 🎉

---

📝 Important Notes

• Staging certificates are for testing only (not trusted by browsers)
• For production: Set CERTBOT_STAGING=false and CERTBOT_FORCE_RENEWAL=true
• Certificates expire after 90 days - manual renewal required
• Certificate files location: /home/container/letsencrypt/config/live/yourdomain.com/

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
• For private HTTPS repositories, set ACCESS_TOKEN to a personal access token. USERNAME is optional and defaults to x-access-token when left blank.
• For SSH repositories, use an SSH clone URL such as git@github.com:owner/repo.git and provide GIT_SSH_PRIVATE_KEY instead of ACCESS_TOKEN
• If you use SSH, ensure the private key has access to the repository and paste the full key including the BEGIN and END lines into GIT_SSH_PRIVATE_KEY
• GIT_SSH_KNOWN_HOSTS can be provided manually, but GitHub host verification is handled automatically during install when possible
• On server creation, your repo will be cloned into the www folder
• After the initial installation completes, start the server manually once to begin the first runtime boot sequence
• 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

🔨 Deploy Script

Use GitHub actions, or want to run an automatic script to run install for your web project when pulling from Git? Enable the Deploy Script toggle and configure the deploy script location for it to automatically run on container restart!

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