AstraDeploy/README.md

AstraDeploy

AstraDeploy is a Bash installer for Minecraft server cores (Java and Bedrock) with:

• 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
bds	/opt/minecraft/bds	19132	native	UDP	Official Bedrock Dedicated Server zip binary

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:

1. Runs in easy mode;
2. Prints a short planned checklist;
3. Uses safe defaults (/opt/minecraft/<core>, default port, tmux-systemd, minecraft user);
4. 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|bds>
• --mc-version <latest|version>
• --build <latest|tag> (for nethergamesmc, PHP build)
• --mc-version for bds resolves required Bedrock package version (latest allowed)
• 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:

1. PHP build resolution and download
2. Composer preparation
3. PocketMine-MP clone/build flow
4. Server startup script generation

Example for BDS

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

bds flow includes:

1. resolve version from official Bedrock download page or provided tag;
2. download bedrock-server-<version>.zip;
3. extract/update server files;
4. generate start.sh and configure service.

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.