Quick Start

Get your Next.js app running on Pterodactyl or Pelican in minutes.

Before you begin

Make sure you have already imported the egg and created a server. If not, complete the Installation guide first.

Your Next.js project must meet these requirements:

• A valid package.json with next listed as a dependency.
• Your next.config.js must not hardcode a port. The egg passes the panel-allocated port via the -p flag at runtime.

Configure and start your server

1. Import the egg and create a server

   If you have not done so yet, follow the Installation guide to import next-js-egg.json and create a server. Return here once your server exists in the panel.

2. Set your Git repository URL

   On the server’s Startup tab, set GIT_URL to the full HTTPS URL of your repository:

   https://github.com/your-username/your-nextjs-app
   

   The egg clones this URL on first start. On subsequent starts it either pulls new commits (if AUTO_UPDATE=1) or skips the pull.

   If you prefer to upload your project files manually instead of using Git, leave GIT_URL empty and upload your files via the panel File Manager. The egg will skip cloning and use whatever files are already in the server volume, as long as a package.json is present.

3. Set the branch

   Set GIT_BRANCH to the branch you want to deploy. The default is main. Leave it empty to let Git use the repository’s default branch.

   main
   
4. Choose a run environment

   Set NODE_RUN_ENV to control how Next.js starts:

   Production (recommended for live sites)

   production
   

   In production mode the egg runs next build followed by next start. This produces an optimised build suitable for real traffic.

   In development mode the egg skips the build step and runs next dev, giving you hot-reload. Use this only for active development — it is slower and not optimised for production traffic.

5. Choose a package manager

   Set PACKAGE_MANAGER to control how dependencies are installed:

   Value	Behaviour
   auto (recommended)	Detects from lockfile: pnpm-lock.yaml → pnpm, yarn.lock → yarn, otherwise npm.
   npm	Always uses npm. Uses npm ci if package-lock.json exists, otherwise npm install.
   pnpm	Always uses pnpm. Installs pnpm globally if not present.
   yarn	Always uses Yarn. Installs Yarn globally if not present.

   auto is the safest choice — it uses whichever lockfile you committed to your repo.

6. Start the server

   Click Start in the panel. The egg will:

   1. Clone your repository (first start) or pull latest changes (if AUTO_UPDATE=1).
   2. Copy .env.pterodactyl to .env if the file exists in the server volume.
   3. Install dependencies using your chosen package manager.
   4. Run next build (production mode only).
   5. Start Next.js on the panel-allocated port.

   The panel marks the server as Running when it detects one of these strings in stdout:

   ready on
   started server on
   Local:        http://
   Compiled successfully
   ▲ Next.js
   

   If your startup script suppresses or redirects stdout, the panel may never detect the ready signal and the server will stay in “Starting…” indefinitely. Make sure Next.js output reaches stdout.

Working with private repositories

If your repository is private, set two additional variables on the Startup tab before starting the server:

Variable	Value
USERNAME	Your GitHub or GitLab username
ACCESS_TOKEN	A personal access token with repo scope

The egg injects these into the clone URL automatically. Do not embed them in GIT_URL itself.

To create a GitHub personal access token, go to Settings → Developer settings → Personal access tokens → Tokens (classic) and generate a token with the repo scope.

Injecting environment variables

If your app requires a .env file (API keys, database URLs, etc.), do not put secrets directly into panel variables. Instead:

1. Create your .env file locally with all required keys and values.
2. Rename it to .env.pterodactyl.
3. Upload it to the server’s root directory (/home/container/) via the panel File Manager.
4. Start (or restart) the server — the egg copies it to .env before your app starts.

You only need to re-upload .env.pterodactyl when your environment variables change. The file persists across restarts; you do not need to re-upload it every time.

Auto-update behaviour

The AUTO_UPDATE variable controls what happens on every server start after the first clone:

AUTO_UPDATE	Behaviour
1 (default)	Runs git reset --hard then git pull to bring the repo up to date before installing and building.
0	Skips the pull. The egg installs dependencies and builds from whatever files are currently in the volume.

Set AUTO_UPDATE=0 if you want full control over which commit is deployed — for example, if you pin a specific commit or tag manually.