# Installation, updates and first start

Use maintained packages whenever possible. For custom installations, use the scripts included with this source version; do not combine parts of different releases.

## Supported entry points

| Installation | Recommended starting point |
|---|---|
| Linux DEB/RPM | https://rustproxy.linuxiarz.pl/ |
| OPNsense plugin | https://rustproxy-opn.linuxiarz.pl/ |
| Debian 13+ source bootstrap | `install-debian13.sh` from the project repository |
| Manual Linux/systemd install | Compile the application; use `install.sh` and `update.sh` |
| OCI container | Included `Dockerfile`; see [Container](CONTAINER.md) |

Package/plugin instructions and maintenance policies are maintained separately from the source archive.

## Debian 13+ source bootstrap

Review the remote script before execution. On a managed installation, `auto` selects install or update from `/opt/rustproxy/install.json`.

```bash
# Initial install or existing managed update
wget -qO- https://git.linuxiarz.pl/gru/RustProxy/raw/branch/master/install-debian13.sh | bash

# Explicit managed update
wget -qO- https://git.linuxiarz.pl/gru/RustProxy/raw/branch/master/install-debian13.sh | bash -s -- update
```

The script installs dependencies, builds with `cargo build --release --locked` as an unprivileged build user, then uses the local deployment scripts. Run it only on Debian 13+ and with access to its required repositories. Installing from a moving `master` branch does **not** pin a specific audited release; use a reviewed commit when reproducibility matters.

## Build from the source

The current `Cargo.toml` declares **Rust 1.99 minimum**, with a `stable` toolchain in `rust-toolchain.toml`. Use Cargo, a C compiler/linker, Bash and Python 3 (Python 3.11+ is advisable for project checks). Run as a normal build user:

```bash
bash dev.sh doctor
bash dev.sh check
bash dev.sh test
bash dev.sh release
```

`dev.sh release` builds the application; it is not equivalent to a successful production rollout. Cargo dependencies and Swagger assets must be available to the build environment. An example systemd unit is in `deploy/`.

For a first Linux/systemd installation:

```bash
bash install.sh --plan --binary target/release/rust-proxy
sudo bash install.sh --binary target/release/rust-proxy
```

Use `--plan` to inspect changes first. The installer refuses existing unmanaged/nonempty state rather than overwriting it. Common options include `--prefix`, `--data-dir`, `--http`, `--https`, `--no-https`, `--admin`, `--allow-remote-admin` and `--no-start` (see `install.sh --help`).

## Defaults and administrator setup

For the standard managed Linux installation:

| Item | Default |
|---|---|
| HTTP frontend | `0.0.0.0:80` |
| HTTPS frontend | `0.0.0.0:443` with an initially self-signed certificate |
| Administration | `127.0.0.1:9090`, HTTP on loopback |
| Installation | `/opt/rustproxy/current/` |
| Private data | `/var/lib/rustproxy` |
| Service account | `rustproxy` |

The first installation has no predefined administrator and no application Vhosts. Obtain the one-time setup token locally:

```bash
sudo -u rustproxy /opt/rustproxy/current/rust-proxy \
  --data-dir /var/lib/rustproxy admin setup-token
```

Use the setup page, or initialize the account interactively using `admin init`. To access loopback administration from another machine, tunnel over SSH:

```bash
ssh -L 9090:127.0.0.1:9090 operator@server
```

Then visit `http://127.0.0.1:9090` on your workstation. For a directly reachable administration listener, configure **Settings → Administration → HTTPS** and a suitable certificate, restrict the network, save and restart. Do not publish unauthenticated or plain-HTTP administration over the Internet. Public frontend HTTPS and administration HTTPS are separate.

### Listeners and networking

- Assign a trusted public certificate to the relevant hosts before exposing them.
- Configure DNS to reach the intended public listener; check IPv4/IPv6 and firewall rules.
- HTTP/3 needs UDP on the HTTPS port as well as TCP for normal HTTPS.
- Listener bindings supplied explicitly via service arguments/systemd are locked against panel changes. Network bind, administration TLS and some monitoring changes take effect after a restart.
- Ports below 1024 need the appropriate OS privileges/capability; use the installed service model rather than running the whole application as root.

## Managed update

Test the new build first. Then execute:

```bash
bash update.sh --plan --binary target/release/rust-proxy
sudo bash update.sh --binary target/release/rust-proxy
```

Managed updates preserve the saved configuration, create a private backup, switch releases and attempt rollback on failed startup/health checks. **They interrupt traffic and are not a substitute for a separate off-host backup.** Keep your backup password and test a restore on a separate installation. Source-tree/unmanaged migrations require the dedicated stopped upgrade path: see [Migration](MIGRATION.md).

## ACME prerequisites

The managed certificate service can create a private Python/Certbot environment in the data directory; a usable system Certbot may be used as fallback. DNS-01 providers need credentials and appropriate permissions. HTTP-01 needs incoming public TCP `80`. On systems without an available Python/Certbot runtime, PEM import and external certificate references can still be used. See [Certificates](ACME_PROVIDERS.md).

## After installation

Verify `systemctl status rustproxy` and `journalctl -u rustproxy` (managed systemd), the panel login, frontend certificates, first Vhost, real backend response, access policies, optional QUIC, current logs and a full backup/restore test. For error diagnosis, consult [Troubleshooting](TROUBLESHOOTING.md).

**Release verification:** supplied 0.34.0 source changes still require target-platform compilation and functional acceptance before Internet-facing production use.