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

## 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

```bash
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)

```bash
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:

```bash
/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

```bash
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

## 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

## 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`](LICENSE) for the full text and disclaimers.

## Version

```bash
sudo bash install.sh --version
```