interactive beginner mode (--easy);
non-interactive/automation-friendly flags (--yes, --non-interactive);
optional report callback and debug logging;
service modes for headless hosting (systemd, tmux-systemd, screen, none);
step-by-step output suitable for bot-driven progress tracking;
built-in license and EULA acknowledgement flow;
rollback and dry-run mode.

Current version: v0.1.0.

Requirements

Bash 4+
sudo / root privileges
Internet access for downloading binaries/artifacts

Compatibility matrix

Environment	Status	Notes
Ubuntu / Debian	✅ Supported	Primary target for initial MVP (`apt`)
Alma / Rocky / RHEL-family	⚠️ Partial	Planned support paths exist, but this release focuses on core workflow verification
Arch Linux	⚠️ Partial	Generic support path in architecture, not fully validated in this release
Fedora	⚠️ Partial	Generic support path in architecture, not fully validated in this release
`yum` / `dnf`	⚠️ Partial	Service/dependency handling is planned for full parity
`pacman`	⚠️ Partial	Detection and abstraction are present, full validation pending
`tmux`	✅ Supported	Required for `tmux-systemd` mode
`screen`	✅ Supported	Optional service transport
`systemd`	✅ Supported	Required for autostart service modes

Supported cores

Core	Default directory	Default port	Runtime	Protocol	Notes
`pmmp`	`/opt/minecraft/pmmp`	`19132`	PHP	UDP	PocketMine Bedrock
`paper`	`/opt/minecraft/paper`	`25565`	Java 21	TCP	Requires Minecraft Java EULA acceptance
`purpur`	`/opt/minecraft/purpur`	`25565`	Java 21	TCP	Requires Minecraft Java EULA acceptance
`velocity`	`/opt/minecraft/velocity`	`25577`	Java 21	TCP	Requires Minecraft Java EULA acceptance
`powernukkitx`	`/opt/minecraft/powernukkitx`	`19132`	Java 21	UDP	Requires Minecraft Java EULA acceptance
`nethergamesmc`	`/opt/minecraft/nethergamesmc`	`19132`	PHP	UDP	Prompts for PHP build and PocketMine-MCPE version

Service mode screen is available and handled in the service layer with the current installer version.

Quick start

sudo bash install.sh --easy --core paper

The command above:

Runs in easy mode;
Prints a short planned checklist;
Uses safe defaults (/opt/minecraft/<core>, default port, tmux-systemd, minecraft user);
Installs dependencies, downloads the selected core, writes startup scripts and service.

Non-interactive usage (bot / CI)

sudo bash install.sh \
  --yes \
  --core paper \
  --dir /opt/minecraft/paper \
  --port 25565 \
  --service tmux-systemd \
  --ram 4G \
  --firewall yes \
  --accept-eula yes \
  --accept-license yes \
  --locale en

Step-by-step progress (for n00b-friendly UX and bot updates)

Every major action emits a step label via logs and report callbacks:

script parses arguments and validates environment;
checks OS/package manager;
validates license and EULA;
validates ports and directory;
installs base dependencies / Java (if needed);
deploys selected core;
configures service and permissions.

If a bot needs to send human-readable status updates, this is intended to be mapped to the step stream.

Reporting callback

--report-url <url> [--report-token <token>]

The installer sends started, step, success, and failed events. Network errors on callback are non-fatal by design.

Logs

Run output is mirrored with tee and saved to:

/var/log/astra-deploy/install-YYYY-MM-DD-HH-MM-SS.log

Installation modes and useful flags

Core selection and versions

--core <pmmp|paper|purpur|velocity|powernukkitx|nethergamesmc>
--mc-version <latest|version>
--build <latest|tag> (for nethergamesmc, PHP build)
legacy aliases: --version, --core-version for MC version

Directory and runtime

--dir <path>
--port <port>
--ram <2G> (RAM string for Java cores)
--user <username> (service user)
--service <systemd|tmux-systemd|screen|none>
--firewall <yes|no>

Safety and existing directory handling

--allow-existing – continue if directory is non-empty
--backup-existing – copy directory to .backup-<timestamp> first
--force-clean – clear target directory before install
by default, non-empty directory without these flags in non-interactive mode fails

Execution options

--easy / -E – guided beginner mode with defaults and plan preview
--yes / -y – assume positive answers
--non-interactive – explicit non-ask mode
--dry-run – simulate actions
--debug – verbose output

Agreements

--accept-license yes|no / --license (legacy)
--accept-eula yes|no / --eula for Java-based cores

You must accept these in automation workflows (--yes mode) before install proceeds.

Example for NetherGamesMC

sudo bash install.sh \
  --easy \
  --core nethergamesmc \
  --dir /opt/minecraft/nethergamesmc \
  --build latest \
  --mc-version latest \
  --service tmux-systemd

nethergamesmc flow includes:

PHP build resolution and download
Composer preparation
PocketMine-MP clone/build flow
Server startup script generation

Update mode

--update switches workflow to update mode. The installer validates existing directory first and replaces server artifacts via the core-specific update path where supported.

Locales

--locale en|ru or --lang en|ru
script also reads LANGUAGE / LANG environment fallback

Troubleshooting

Port is already in use
- Find the process by lsof -i:<port> and stop it, or choose a different --port.
- For non-standard setups, set --port to an available TCP/UDP port depending on the core.
Installer stops on missing dependencies or package errors
- Re-run with --debug to inspect detected package manager and failed command.
- Ensure the host has internet access and package repositories are reachable.
Permission denied while creating/changing files
- Run via sudo/root for privileged operations.
- Verify --user exists and has write permissions on --dir.
Firewall was not configured automatically
- Installer prints a manual notice when ufw/firewalld is unavailable.
- Open ports manually in your system firewall before continuing.
Report callback is not sent
- Callback failures are non-blocking.
- Validate URL/token and retry install with corrected --report-url and --report-token.

Safety notes

Script is designed with guardrails but still executes privileged operations (packages/services/firewall/files).
Backup critical data before running on production systems.
If callback API is unavailable, installation continues and writes local log details.

License

This repository is distributed under the MIT License.
See LICENSE for the full text and disclaimers.

Detailed usage

Core-specific usage examples are in:

docs/USAGE.md (English)
docs/USAGE.ru.md (Russian)

Version

sudo bash install.sh --version

Changelog

See CHANGELOG.md.

Contributing

Please read CONTRIBUTING.md.

README.md Unescape Escape

AstraDeploy