AstraDeploy/README.md

# AstraDeploy

[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![Bash](https://img.shields.io/badge/Bash-4%2B-brightgreen)](https://www.gnu.org/software/bash/)
[![Version](https://img.shields.io/badge/Version-v0.1.0-blue)](README.md)

`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

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

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

## Example for BDS

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

## Detailed usage

Core-specific usage examples are in:
- [`docs/USAGE.md`](docs/USAGE.md) (English)
- [`docs/USAGE.ru.md`](docs/USAGE.ru.md) (Russian)

## Version

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

## Changelog

See [`CHANGELOG.md`](CHANGELOG.md).

## Contributing

Please read [`CONTRIBUTING.md`](CONTRIBUTING.md).