# Proxy

By default, instances can be accessed by their IP. In order to get more
memorable URLs and allow supporting HTTPS. haze comes with a builtin reverse
proxy to allow using a wildcard domain.

## Setup

- [Setup a DNS record](./dns.html) for `*.haze.example.com` and
  `haze.example.com` pointing to your development machine.
- Set the `proxy` configuration with your domain and desired listen endpoint.
- Set up a service to run `haze proxy` in the background as your own user. A
  SystemD user service is recommended (see
  [haze.service](<[./haze.service](https://codeberg.org/icewind/haze/src/branch/main/haze.service)>)
  for an example).
- If you're already running a reverse proxy, configure your reverse proxy of
  choice to proxy `*.haze.example.com` and `haze.example.com` to the proxy's
  listen endpoint.
- (Optionally) [setup HTTPS](./https.html) for the proxy.

### Configuration

Add the following configuration to the `haze.toml` configuration file:

```toml
[proxy]
address = "haze.example.com" # the base domain for the proxy to use
listen = "127.0.0.1:8080" # the port+ip to listen on
# listen = "/var/run/haze/haze.sock" # or a unix socket path
```

### Without a reverse proxy

If you have no other http(s) servers on your development machine, you can setup
things without a reverse proxy.

Simply configure the proxy to listen on port `80` (or `443` when using HTTPS).

Binding to port 80 or443 as a regular user requires either giving the haze
binary the `net_bind_service` capability with
`sudo setcap cap_net_bind_service=+ep $(which haze)` (this will have to be done
every time your upgrade haze) or configure your system to allow unprivileged
users to bind on the low port numbers. Using
`sysctl net.ipv4.ip_unprivileged_port_start=80` and writing

```
net.ipv4.ip_unprivileged_port_start=80
```

to `/etc/sysctl.d/bind.conf` to make it persistent across reboot.

### With a reverse proxy

If you're already have other http(s) services listening on your machine, you'll
probably want to setup a reverse proxy to allow them to all be served on your
machine.

The setup for this will depend on your reverse proxy of the choice, the
following example configuration is for `nginx`.

```nginx
upstream haze-handler {
    server unix:/var/run/haze/haze.sock;
}

server {
    listen 80;
    server_name *.haze.example.com;

    location / {
            proxy_pass http://haze-handler;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## Usage

When the proxy is configured, generated URLs for the instances will use a
subdomain of the configured domain, e.g. the `rolling-bees` instance will be
available at `rolling-bees.haze.example.com`. Additionally, `haze.example.com`
will automatically point to the last created instance.

Additionally, the proxy allows access to the service containers trough either
`<instance id>-<service id>.haze.example.com` for a specific instance, or
`<service-id>.haze.example.com` for the last created instance. For example
`rolling-bees-mail.haze.example.com` will give access to the smtp4dev web
interface of the `rolling-bees` instance.