# Installation Guide

veld is distributed as source and built with Cargo. This guide covers **Linux**
(production, including a systemd service) and **Windows** (development).

- [Prerequisites](#prerequisites)
- [Linux](#linux)
  - [Build from source](#linux-build)
  - [Run as a systemd service](#linux-systemd)
  - [Updating](#linux-update)
- [Windows](#windows)
- [Verifying the install](#verifying)
- [Troubleshooting](#troubleshooting)

---

## Prerequisites

- **Rust toolchain** (stable, edition 2021). Install via [rustup](https://rustup.rs).
  Tested with Rust 1.75+ and 1.96.
- A C compiler/linker (for some transitive dependencies):
  - Linux: `build-essential` (`gcc`, `make`).
  - Windows: the **MSVC build tools** (installed automatically with the default
    `rustup` toolchain `stable-x86_64-pc-windows-msvc`), or use the GNU toolchain.
- `git` to clone the repository.

---

## Linux

### <a id="linux-build"></a>1. Build from source

```bash
# Install Rust (skip if already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Build tools
sudo apt-get update && sudo apt-get install -y build-essential git

# Clone and build
git clone https://github.com/xinluw/veld.git
cd veld
cargo build --release
# -> binary at target/release/veld
```

Quick run (foreground):

```bash
./target/release/veld -c conf/veld.conf test    # validate config
./target/release/veld -c conf/veld.conf start   # run
```

### <a id="linux-systemd"></a>2. Run as a systemd service

This installs veld as a persistent service that starts on boot. Adjust the port,
document root, and user to taste.

**a. Install the binary**

```bash
sudo install -m 0755 target/release/veld /usr/local/bin/veld
```

**b. Create config, document root, and runtime directories**

```bash
sudo mkdir -p /etc/veld /var/www/veld /var/lib/veld/logs

# A starter page
echo '<h1>veld works</h1>' | sudo tee /var/www/veld/index.html >/dev/null

# Let the service user own its runtime dir (replace www-data with your user)
sudo chown -R www-data:www-data /var/lib/veld
sudo chmod -R a+rX /var/www/veld
```

Create `/etc/veld/veld.conf`:

```nginx
worker_processes auto;
error_log /var/lib/veld/logs/error.log warn;
pid       /var/lib/veld/veld.pid;

events {
    worker_connections 4096;
    multi_accept on;
}

http {
    default_type application/octet-stream;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    access_log off;

    server {
        listen 8080;
        server_name localhost;
        root /var/www/veld;
        index index.html;

        location / {
            try_files $uri $uri/ =404;
        }
    }
}
```

> Binding ports below 1024 (e.g. 80/443) requires extra privileges. Either run the service
> as `root`, or grant the binary the capability:
> `sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/veld`.

**c. Install the systemd unit**

Copy [`examples/veld.service`](../examples/veld.service) to
`/etc/systemd/system/veld.service` (edit `User=` if needed), then:

```bash
sudo cp examples/veld.service /etc/systemd/system/veld.service
sudo systemctl daemon-reload
sudo systemctl enable --now veld
```

**d. Manage the service**

```bash
sudo systemctl status veld      # status
sudo systemctl restart veld     # restart
sudo systemctl reload veld      # reload config (SIGHUP)
journalctl -u veld -f           # follow logs
```

### <a id="linux-update"></a>3. Updating after a code change

```bash
cd veld
git pull
cargo build --release
sudo install -m 0755 target/release/veld /usr/local/bin/veld
sudo systemctl restart veld
```

---

## Windows

veld builds and runs on Windows for development. Zero-copy `sendfile` and
`SO_REUSEPORT` are Linux-only; on Windows the server falls back to a portable send path
and a single shared listener, so use Linux for production benchmarking.

```powershell
# 1. Install Rust: download and run rustup-init from https://rustup.rs
#    (choose the default stable-x86_64-pc-windows-msvc toolchain)

# 2. Clone and build
git clone https://github.com/xinluw/veld.git
cd veld
cargo build --release
# -> binary at target\release\veld.exe

# 3. Validate and run
.\target\release\veld.exe -c conf\veld.conf test
.\target\release\veld.exe -c conf\veld.conf start
```

To run as a Windows background service you can use a wrapper such as
[NSSM](https://nssm.cc/) pointing at `veld.exe` with the same arguments.

---

## <a id="verifying"></a>Verifying the install

```bash
# Replace 8080 with your listen port
curl -i http://127.0.0.1:8080/

# Expected: HTTP/1.1 200 OK with Server: veld
```

---

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| `address already in use` | Another process holds the port. Find it with `ss -ltnp \| grep :PORT` and stop it, or change `listen`. |
| Permission denied binding :80/:443 | Use `setcap` (see above) or run as root. |
| `cargo: command not found` after install | Run `source "$HOME/.cargo/env"` or open a new shell. |
| Old `cargo`/lockfile error (`lock file version 4`) | Use a recent toolchain: `rustup update stable` and build with `~/.cargo/bin/cargo`. |
| Build fails on a transitive C dependency | Install a C toolchain (`build-essential` on Linux; MSVC build tools on Windows). |
| Service won't start | `journalctl -u veld -e` for the error; check paths in the config exist and are owned by the service user. |